Migration Failback

On this page

If issues arise during migration, run MOLT Fetch in failback mode after stopping replication and before writing to CockroachDB. This ensures that data remains consistent on the source in case you need to roll back the migration.

Prepare the CockroachDB cluster

Enable rangefeeds on the CockroachDB cluster:

SET CLUSTER SETTING kv.rangefeed.enabled = true;

GRANT SELECT, INSERT, UPDATE, FLASHBACK ON migration_schema.employees TO MIGRATION_USER;
GRANT SELECT, INSERT, UPDATE, FLASHBACK ON migration_schema.payments TO MIGRATION_USER;
GRANT SELECT, INSERT, UPDATE, FLASHBACK ON migration_schema.orders TO MIGRATION_USER;

Configure failback

Configure the MOLT Fetch connection strings and filters for failback mode, ensuring that the CockroachDB changefeed is correctly targeting your original source.

Connection strings

In failback mode, the --source and --target connection strings are reversed from other migration modes:

--source is the CockroachDB connection string. For example:

--source 'postgres://crdb_user@localhost:26257/defaultdb?sslmode=verify-full'

--target is the connection string of the database you migrated from.

--target 'postgres://postgres:postgres@localhost:5432/molt?sslmode=verify-full'

--target 'mysql://user:password@localhost/molt?sslcert=.%2fsource_certs%2fclient.root.crt&sslkey=.%2fsource_certs%2fclient.root.key&sslmode=verify-full&sslrootcert=.%2fsource_certs%2fca.crt'

--target 'oracle://C%23%23MIGRATION_USER:password@host:1521/ORCLPDB1'

Secure changefeed for failback

failback mode creates a CockroachDB changefeed and sets up a webhook sink to pass change events from CockroachDB to the failback target. In production, you should override the default insecure changefeed with secure settings.

Provide these overrides in a JSON file. At minimum, the JSON should include the base64-encoded client certificate (client_cert), key (client_key), and CA (ca_cert) for the webhook sink.

{
  "sink_query_parameters": "client_cert={base64 cert}&client_key={base64 key}&ca_cert={base64 CA cert}"
}

Pass the JSON file path to molt via --changefeeds-path. For example:

--changefeeds-path 'changefeed-secure.json'

Because the changefeed runs inside the CockroachDB cluster, the --changefeeds-path file must reference a webhook endpoint address reachable by the cluster, not necessarily your local workstation.

For details, refer to Changefeed override settings.

Replication flags

In the molt fetch command, use --replicator-flags to pass options to the included replicator process that handles continuous replication. For details on all available flags, refer to the MOLT Fetch documentation.

• Failback requires --stagingSchema, which specifies the staging schema name used as a checkpoint. MOLT Fetch logs the staging schema name when it starts replication:

  staging database name: _replicator_1749699789613149000
  

• When configuring a secure changefeed for failback, you must include --tlsCertificate and --tlsPrivateKey, which specify the paths to the server certificate and private key for the webhook sink connection.

Fail back from CockroachDB

Start failback to the source database.

1. Cancel replication to CockroachDB by entering ctrl-c to issue a SIGTERM signal to the fetch process. This returns an exit code 0.

2. Issue the MOLT Fetch command to fail back to the source database, specifying --mode failback. In this example, we filter the migration_schema schema and the employees, payments, and orders tables, configure the staging schema with --replicator-flags, and use --changefeeds-path to provide the secure changefeed override.

   molt fetch \
   --source $SOURCE \
   --target $TARGET \
   --schema-filter 'migration_schema' \
   --table-filter 'employees|payments|orders' \
   --replicator-flags '--stagingSchema _replicator_1739996035106984000 --tlsCertificate ./certs/server.crt --tlsPrivateKey ./certs/server.key' \
   --mode failback \
   --changefeeds-path 'changefeed-secure.json'
   

   molt fetch \
   --source $SOURCE \
   --target $TARGET \
   --schema-filter 'migration_schema' \
   --table-filter 'employees|payments|orders' \
   --replicator-flags '--stagingSchema _replicator_1739996035106984000 --tlsCertificate ./certs/server.crt --tlsPrivateKey ./certs/server.key' \
   --mode failback \
   --changefeeds-path 'changefeed-secure.json'
   

   molt fetch \
   --source $SOURCE \
   --target $TARGET \
   --schema-filter 'migration_schema' \
   --table-filter 'employees|payments|orders' \
   --replicator-flags '--stagingSchema _replicator_1739996035106984000 --tlsCertificate ./certs/server.crt --tlsPrivateKey ./certs/server.key --userscript table_filter.ts' \
   --mode failback \
   --changefeeds-path 'changefeed-secure.json'
   

3. Check the output to observe fetch progress.

   A starting replicator message indicates that the task has started:

   {"level":"info","time":"2025-02-20T15:55:44-05:00","message":"starting replicator"}
   

   The staging database name message contains the name of the staging schema:

    {"level":"info","time":"2025-02-11T14:56:20-05:00","message":"staging database name: _replicator_1739303283084207000"}
   

   A creating changefeed message indicates that a changefeed will be passing change events from CockroachDB to the failback target:

   {"level":"info","time":"2025-02-20T15:55:44-05:00","message":"creating changefeed on the source CRDB database"}
   

See also

• Migration Overview
• Migration Strategy
• MOLT Schema Conversion Tool
• MOLT Fetch
• MOLT Verify