Managing centralized migrations

 
$ tt migrations COMMAND [COMMAND_OPTION ...]

tt migrations manages centralized migrations in a Tarantool EE cluster. See centralized_migrations_tt for a detailed guide on using the centralized migrations mechanism.

COMMAND is one of the following:

• publish
• apply
• status
• stop
• remove

 
$ tt migrations publish ETCD_URI [MIGRATIONS_DIR | MIGRATION_FILE] [OPTION ...]

tt migrations publish sends the migration files to the cluster's centralized configuration storage for future execution.

By default, the command sends all files stored in migrations/ inside the current directory.

 
$ tt migrations publish "https://user:pass@localhost:2379/myapp"

To select another directory with migration files, provide a path to it as the command argument:

 
$ tt migrations publish "https://user:pass@localhost:2379/myapp" my_migrations

To publish a single migration from a file, use its name or path as the command argument:

 
$ tt migrations publish "https://user:pass@localhost:2379/myapp" migrations/000001_create_space.lua

Optionally, you can provide a key to use as a migration identifier instead of the filename:

 
$ tt migrations publish "https://user:pass@localhost:2379/myapp" file.lua  \                        --key=000001_create_space.lua

When publishing migrations, tt performs checks for:

• Syntax errors in migration files. To skip syntax check, add the --skip-syntax-check option.
• Existence of migrations with same names. To overwrite an existing migration with the same name, add the --overwirte option.
• Migration names order. By default, tt migrations only adds new migrations to the end of the migrations list ordered lexicographically. For example, if migrations 001.lua and 003.lua are already published, an attempt to publish 002.lua will fail. To force publishing migrations disregarding the order, add the --ignore-order-violation option.

 
$ tt migrations apply ETCD_URI [OPTION ...]

tt migrations apply applies published migrations to the cluster. It executes all migrations from the cluster's centralized configuration storage on all its read-write instances (replica set leaders).

 
$ tt migrations apply "https://user:pass@localhost:2379/myapp"  \                    --tarantool-username=admin --tarantool-password=pass

To apply a single published migration, pass its name in the --migration option:

 
$ tt migrations apply "https://user:pass@localhost:2379/myapp"  \                    --tarantool-username=admin --tarantool-password=pass  \                    --migration=000001_create_space.lua

To apply migrations on a single replica set, specify the replicaset option:

 
$ tt migrations apply "https://user:pass@localhost:2379/myapp"  \                    --tarantool-username=admin --tarantool-password=pass  \                    --replicaset=storage-001

The command also provides options for migration troubleshooting: --ignore-order-violation, --force-reapply, and --ignore-preceding-status. Learn to use them in centralized_migrations_tt_troubleshoot.

 
$ tt migrations status ETCD_URI [OPTION ...]

tt migrations status prints the list of migrations published to the centralized storage and the result of their execution on the cluster instances.

Possible migration statuses are:

APPLY_STARTED – the migration execution has started but not completed yet

: or has been interrupted with tt migrations stop`

• APPLIED – the migration is successfully applied on the instance

• FAILED – there were errors during the migration execution on the instance

To get the list of migrations stored in the given etcd storage and information about their execution on the cluster, run:

 
$ tt migrations status "https://user:pass@localhost:2379/myapp"  \                       --tarantool-username=admin --tarantool-password=pass

If the cluster uses SSL encryption, add SSL options. Learn more in Authentication.

Use the --migration and --replicaset options to get information about specific migrations or replica sets:

 
$ tt migrations status "https://user:pass@localhost:2379/myapp"  \                     --tarantool-username=admin --tarantool-password=pass \                     --replicaset=storage-001 --migration=000001_create_writers_space.lua

The --display-mode option allows to tailor the command output:

• with --display-mode config-storage, the command prints only the list of migrations published to the centralized storage.
• with --display-mode cluster, the command prints only the migration statuses on the cluster instances.

To find out the results of a migration execution on a specific replica set in the cluster, run:

 
$ tt migrations status "https://user:pass@localhost:2379/myapp"  \                       --tarantool-username=admin --tarantool-password=pass  \                       --replicaset=storage-001 --display-mode=cluster

 
$ tt migrations stop ETCD_URI [OPTION ...]

tt migrations stop stops the execution of migrations in the cluster.

To stop the execution of a migration currently running in the cluster:

 
$ tt migrations stop "https://user:pass@localhost:2379/myapp"  \                     --tarantool-username=admin --tarantool-password=pass

tt migrations stop interrupts a single migration. If you call it to interrupt the process that applies multiple migrations, the ones completed before the call receive the APPLIED status. The migration is interrupted by the call remains in APPLY_STARTED.

 
$ tt migrations remove ETCD_URI [OPTION ...]

tt migrations remove removes published migrations from the centralized storage. With additional options, it can also remove the information about the migration execution on the cluster instances.

To remove all migrations from a specified centralized storage:

 
$ tt migrations remove "https://user:pass@localhost:2379/myapp"  \                       --tarantool-username=admin --tarantool-password=pass

To remove a specific migration, pass its name in the --migration option:

 
$ tt migrations remove "https://user:pass@localhost:2379/myapp"  \                       --tarantool-username=admin --tarantool-password=pass  \                       --migration=000001_create_writers_space.lua

Before removing migrations, the command checks their status on the cluster. To ignore the status and remove migrations anyway, add the --force-remove-on=config-storage option:

 
$ tt migrations remove "https://user:pass@localhost:2379/myapp"  \                        --force-remove-on=config-storage

To remove migration execution information from the cluster (clear the migration status), use the --force-remove-on=cluster option:

 
$ tt migrations remove "https://user:pass@localhost:2379/myapp"  \                       --tarantool-username=admin --tarantool-password=pass  \                       --force-remove-on=cluster

To clear all migration information from the centralized storage and cluster, use the --force-remove-on=all option:

 
$ tt migrations remove "https://user:pass@localhost:2379/myapp"  \                       --tarantool-username=admin --tarantool-password=pass  \                       --force-remove-on=all

Since tt migrations operates migrations via a centralizes etcd storage, it needs credentials to access this storage. There are two ways to pass etcd credentials:

• command-line options --config-storage-username and --config-storage-password
• the etcd URI, for example, https://user:pass@localhost:2379/myapp

Credentials specified in the URI have a higher priority.

For commands that connect to the cluster (that is, all except publish), Tarantool credentials are also required. The are passed in the --tarantool-username and --tarantool-password options.

If the cluster uses SSL traffic encryption, provide the necessary connection parameters in the --tarantool-ssl* options: --tarantool-sslcertfile, --tarantool-sslkeyfile, and other. All options are listed in tt-migrations-options.

Applicable to: apply

Migrations fiber lock acquire timeout in seconds. Default: 60. Fiber lock is used to prevent concurrent migrations run

A password for connecting to the centralized migrations storage (etcd).

See also: tt-migrations-auth.

A username for connecting to the centralized migrations storage (etcd).

See also: tt-migrations-auth.

Applicable to: status

Display only specific information. Possible values:

• config-storage – information about migrations published to the centralized storage.
• cluster – information about migration applied on the cluster.

See also: tt-migrations-status.

Applicable to: apply, remove, status, stop

A timeout for completing the operation on a single Tarantool instance, in seconds. Default values:

• 3 for remove, status, and stop
• 3600 for apply

Applicable to: apply

Apply migrations disregarding their previous status.

Applicable to: remove

Remove migrations disregarding their status. Possible values:

• config-storage: remove migrations on etcd centralized migrations storage disregarding the cluster apply status.
• cluster: remove migrations status info only on a Tarantool cluster.
• all to execute both config-storage and cluster force removals.

Applicable to: apply, publish

Skip migration scenarios order check before publish.

Applicable to: apply

Skip preceding migrations status check on apply.

Applicable to: publish

Put scenario to /<prefix>/migrations/scenario/<key> etcd key instead. Only for single file publish.

Applicable to: apply, remove, status

A migration to apply, remove, or check status.

Applicable to: publish

overwrite existing migration storage keys.

Applicable to: apply, remove, status, stop

Execute the operation only on the specified replica set.

Applicable to: publish

Skip syntax check before publish.

Applicable to: apply, remove, status, stop

Authentication type used to connect to the cluster instances.

Applicable to: apply, remove, status, stop

Tarantool cluster instances connection timeout, in seconds. Default: 3.

Applicable to: apply, remove, status, stop

A password used to connect to the cluster instances.

Applicable to: apply, remove, status, stop

SSL CA file used to connect to the cluster instances.

Applicable to: apply, remove, status, stop

SSL cert file used to connect to the cluster instances.

Applicable to: apply, remove, status, stop

Colon-separated list of SSL ciphers used to connect to the cluster instances.

Applicable to: apply, remove, status, stop

SSL key file used to connect to the cluster instances.

Applicable to: apply, remove, status, stop

SSL key file password used to connect to the cluster instances.

Applicable to: apply, remove, status, stop

File with list of password to SSL key file used to connect to the cluster instances.

Applicable to: apply, remove, status, stop

Whether SSL is used to connect to the cluster instances.

Applicable to: apply, remove, status, stop

A username for connecting to the Tarantool cluster instances.