Skip to content

Conversation

@fbac
Copy link
Collaborator

@fbac fbac commented Jun 18, 2025

Add migrator service to transfer MLS V1 data from source database to xmtpd database format with blockchain publishing support

Introduces a complete data migration service that reads data from a source database, transforms it into xmtpd envelope format, and writes it to either the destination database or blockchain. The implementation includes:

  • Core migration service in pkg/migrator/migrator.go with concurrent processing pipelines for group messages, inbox logs, welcome messages, and key packages
  • Database readers in pkg/migrator/reader.go for fetching batches of records from source tables
  • Data transformers in pkg/migrator/transformer.go that convert source data to XMTPD envelope format with proper signing
  • Database and blockchain writers in pkg/migrator/writer.go for persisting migrated data
  • Migration progress tracking via new migration_tracker table and associated queries
  • Configuration options in pkg/config/migration.go for enabling and configuring the migration service
  • Integration with the main server in pkg/server/server.go to start and stop the migration service
  • Comprehensive test suite with database and blockchain test infrastructure

📍Where to Start

Start with the NewMigrationService constructor function in pkg/migrator/migrator.go to understand how the migration service is initialized, then review the Start method to see how the migration process begins.


Macroscope summarized 5e37275.

@graphite-app
Copy link

graphite-app bot commented Jun 18, 2025

How to use the Graphite Merge Queue

Add either label to this PR to merge it via the merge queue:

  • Queue - adds this PR to the back of the merge queue
  • Hotfix - for urgent hot fixes, skip the queue and merge this PR next

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

@fbac fbac force-pushed the 06-16-migrator_service branch from 295de6b to 0c0c7f7 Compare June 19, 2025 13:16
@fbac fbac force-pushed the 06-16-migrator_service branch from 3419fb0 to bd47f2c Compare June 19, 2025 15:41
@fbac fbac force-pushed the 06-16-migrator_service branch 2 times, most recently from f2f0375 to 3d4c084 Compare June 24, 2025 15:25
@fbac fbac force-pushed the 06-16-migrator_service branch 2 times, most recently from a1d2a96 to 1ed12b2 Compare June 25, 2025 17:57
@fbac fbac marked this pull request as ready for review June 30, 2025 16:47
@fbac fbac requested a review from a team as a code owner June 30, 2025 16:47
@fbac fbac changed the title Scaffold migrator service Add migrator service Jun 30, 2025
@fbac fbac self-assigned this Jun 30, 2025
Francisco de Borja Aranda Castillejo added 2 commits July 8, 2025 14:09
### Add comprehensive test coverage for migrator service functionality
including `Migrator`, `Transformer`, and reader components
- Adds comprehensive test files
[migrator_test.go](https://github.com/xmtp/xmtpd/pull/936/files#diff-e7344016aadd58a42e5066743aaa1f3c963766d2838ef917dbbd852d1a8f50b1)
and
[transformer_test.go](https://github.com/xmtp/xmtpd/pull/936/files#diff-4d2f9cd6dca8594127cb38e1818e608c4fcfd4fc803ffa4402afb6a6922bc29a)
with full coverage for migration processing, record transformation, and
envelope generation
- Makes internal structs `dbMigrator` and `transformer` public as
`Migrator` and `Transformer` in
[migrator.go](https://github.com/xmtp/xmtpd/pull/936/files#diff-ccb0d31b1e7491838a2e4c7f2f6523eed971d6f18d4c04f006e14e2767671693)
and
[transformer.go](https://github.com/xmtp/xmtpd/pull/936/files#diff-c76d70079716ba42e22c5b5031c1960504cccbca874aadb118385ca67341cf62)
- Changes transaction isolation level from `sql.LevelRepeatableRead` to
`sql.LevelReadCommitted` in
[writer.go](https://github.com/xmtp/xmtpd/pull/936/files#diff-79de0174d18bbb97eb4c62be1eeec1e2132ff3060f5beafb3b8721044791b258)
- Updates originator ID constants to public visibility in
[types.go](https://github.com/xmtp/xmtpd/pull/936/files#diff-9f0a533504d524cea30380cd792a79e21a2c6a46594c9be99de7399fd288d1ba)
- Removes `address_log` entry from migration tracker initialization in
[00013_add-migration-tracker.up.sql](https://github.com/xmtp/xmtpd/pull/936/files#diff-72c04e16b6d52ace37aacc924f60a1f71e195a42c0cb88d4391c20434a01ded8)
- Updates test database setup function to return connection string in
[testdata/db.go](https://github.com/xmtp/xmtpd/pull/936/files#diff-278351e442418d10eeff08343634456f23e59d16ac396e18147814d88b60c17f)

#### 📍Where to Start
Start with the `TestMigrator` function in
[migrator_test.go](https://github.com/xmtp/xmtpd/pull/936/files#diff-e7344016aadd58a42e5066743aaa1f3c963766d2838ef917dbbd852d1a8f50b1)
to understand the main test flow and then examine the `Migrator` struct
in
[migrator.go](https://github.com/xmtp/xmtpd/pull/936/files#diff-ccb0d31b1e7491838a2e4c7f2f6523eed971d6f18d4c04f006e14e2767671693).

----

_[Macroscope](https://app.macroscope.com) summarized 5ef48b5._
@fbac fbac mentioned this pull request Jul 9, 2025
33 tasks
@fbac fbac requested review from mkysel and neekolas July 16, 2025 15:51
@fbac fbac force-pushed the 06-16-migrator_service branch from e3426b3 to 29eb415 Compare July 31, 2025 14:50
@fbac fbac force-pushed the 06-16-migrator_service branch from 5e535ae to 5e37275 Compare July 31, 2025 15:28
err = db.RunInTx(
m.ctx,
m.writer,
nil,
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mkysel @neekolas should we force some type of db isolation?

Copy link
Collaborator

@mkysel mkysel left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I dont expect our partners to run this. It might be cleaner to have a separate binary that is specific the migration.

@fbac fbac merged commit 2321080 into main Jul 31, 2025
10 checks passed
@fbac fbac deleted the 06-16-migrator_service branch July 31, 2025 22:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants