17. The miraj-migrate migration tool

miraj-migrate copies an existing SQL database (schema, views and rows) to a running MIRAJ server. It reads the source in read-only mode over the network protocol: the source is neither stopped nor modified, so the tool can be rerun as many times as needed before the cutover.

17.1 General syntax#

miraj-migrate inspect --source-db <database> [source options]
miraj-migrate run     --source-db <database> [source and target options]
                      [--drop-existing] [--skip-data] [--batch-rows <n>] [--only t1,t2]
miraj-migrate --help

Exit codes:

17.2 Commands#

17.3 Options#

Source

Target (MIRAJ server)

Behavior of run

On the command line, a password is visible in the process list: prefer environment variables for production use.

17.4 How a migration proceeds#

1. Connection to the source and to the target (both in full UTF-8, emoji included); creation of the target database if necessary.
2. For each table: reading of its definition on the source, creation on the target (with --drop-existing, prior deletion), then copy of the rows by multi-row INSERT.
3. Verification: the source row count, the count of rows read and the target row count must be identical.
4. For each view: creation on the target, then a check read (SELECT … LIMIT 1). The source DEFINER account is removed, as it generally does not exist on the target.
5. Summary: number of tables migrated, list of failures, list of objects to be handled by hand.

Tables are processed one after another; a failure on one table does not stop the following ones. Foreign key constraints are recreated with the table; the copy is done without checking the order between tables, since the source has already guaranteed consistency.

Example:

> miraj-migrate inspect --source-db gestion --source-host 10.0.0.5 --source-user lecture
Base source « gestion » ([email protected]:3306) : 2 table(s), 1 vue(s)
  table clients          3001 ligne(s)
  table lignes          15005 ligne(s)
  vue   v_soldes
Total : 18006 ligne(s)

> miraj-migrate run --source-db gestion --source-host 10.0.0.5 --source-user lecture --drop-existing
Migration de « gestion » ([email protected]:3306) vers « gestion » ([email protected]:7007)
  table clients          3001 ligne(s) copiée(s), vérifiée(s)
  table lignes          15005 ligne(s) copiée(s), vérifiée(s)
  vue   v_soldes         créée
Bilan : 2 table(s) migrée(s), 0 échec(s)

17.5 What is not migrated#

• Triggers, stored routines and events: they are only listed (« À reprendre manuellement », i.e. "to be redone manually"). Their body depends on the source dialect and must be reviewed, then recreated with MIRAJ SQL (chapters 5 and 6).
• Accounts and privileges: to be recreated with CREATE USER and GRANT (chapter 10).
• Concurrent writes: the copy is not a snapshot. For a database still in use, suspend writes during run, or rerun run --drop-existing just before the cutover.
• Content: verification compares row counts, not values. For a stronger check, compare aggregates or a per-table fingerprint on both servers.

Table definitions are replayed as the source provides them: a clause that MIRAJ rejects appears as a failure for that table, with the error message of the MIRAJ server (chapter 15).

17.6 Common error messages#