Managing centralized migrations

Enterprise Edition

This command is supported by the Enterprise Edition only.

$ tt migrations COMMAND [COMMAND_OPTION ...]

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

Important

Only Tarantool EE clusters with etcd centralized configuration storage are supported.

COMMAND is one of the following:

publish
apply
status
stop
remove

publish

$ 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.

Warning

Using the options that ignore checks when publishing migration may cause migration inconsistency in the cluster.

apply

$ 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 Troubleshooting migrations.

Warning

The use of migration troubleshooting options may lead to migration inconsistency in the cluster. Use them only for local development and testing purposes.

status

$ 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 <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

stop

$ tt migrations stop ETCD_URI [OPTION ...]

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

Warning

Calling tt migration stop may cause migration inconsistency 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.

remove

$ 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

Note

In this case, cluster credentials are not required.

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

Authentication

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 Options.

Options

--acquire-lock-timeout INT¶

Applicable to: apply

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

--config-storage-password STRING¶

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

Version:

Managing centralized migrations

publish

apply

status

stop

remove

Authentication

Options