Skip to main content

Advanced - Database Migrations

Note

For Aerie deployments PRIOR to v3.3.0, please reference this page for accurate information as to how the migration script works.

To aid in migrating between database versions we provide a Python script called aerie_db_migration.py. In order to run it, the following software is required:

Additional Python package requirements can be installed by running the following command in the deployment directory:

python -m pip install -r requirements.txt

Once the prerequisite software has been installed, the script can be executed by running the following command from inside the Aerie deployment directory:

python aerie_db_migration.py <SUBCOMMAND>

Where <SUBCOMMAND> is one of status or migrate (see below). Alternatively, you can add the script to your PATH and run it from anywhere with the command aerie_db_migration.py:

export PATH="$HOME/path/to/deployment:$PATH"

The script expects all migration files present on the server to also exist on the local machine. In order to reset the state of all migrations (for example, to be able to remove old migration files), see the Hasura documentation.

Subcommands

aerie_db_migration.py contains two subcommands: status and migrate.

Status

Displays the current migration status of the database.

aerie_db_migration.py status [-h] [-p HASURA_PATH] [-e ENV_PATH] [--endpoint ENDPOINT] [--admin-secret ADMIN_SECRET]
Option NameOption Description
-h, --helpShows the help message.
-p HASURA_PATH, --hasura-path HASURA_PATHThe path to the directory containing the config.yaml and migrations folder for Aerie. Defaults to ./hasura
-e ENV_PATH, --env-path ENV_PATHEnvfile to load envvars from.
--endpoint ENDPOINT The http(s) endpoint for the Hasura instance.
--admin-secret ADMIN_SECRETThe admin secret

Migrate

Migrates the database.

aerie_db_migration.py migrate [-h] [-p HASURA_PATH] [-e ENV_PATH] [--endpoint ENDPOINT] [--admin-secret ADMIN_SECRET] (-a | -r) [--all]
Option NameOption Description
-h, --helpShows the help message.
-a, --applyApply migration steps to the database.
-r, --revertRevert migration steps to the database.
--allApply (Revert) ALL unapplied (applied) migration steps to the database.
-p HASURA_PATH, --hasura-path HASURA_PATHThe path to the directory containing the config.yaml and migrations folder for Aerie. Defaults to ./hasura
-e ENV_PATH, --env-path ENV_PATHEnvfile to load envvars from.
--endpoint ENDPOINT The http(s) endpoint for the Hasura instance.
--admin-secret ADMIN_SECRETThe admin secret

It is necessary to at least specify --apply or --revert.

Migrating a Database

If --all has been specified, then aerie_db_migration.py will automatically apply or revert all applicable changes to the database. It will then output the details of each change applied, followed by the overall status. For example:

> aerie_db_migration.py migrate -a --all
###############################
AERIE DATABASE MIGRATION HELPER
###############################
VERSION TYPE NAME
1 up sample_migration
INFO migrations applied
INFO Metadata reloaded
INFO Metadata is consistent

###############
Database Status
###############
VERSION NAME SOURCE STATUS DATABASE STATUS
1 sample_migration Present Present

Otherwise, aerie_db_migration will enter a step-by-step mode, where you will be prompted whether to apply each available migration step. For example:

> aerie_db_migration.py migrate -a
###############################
AERIE DATABASE MIGRATION HELPER
###############################

MIGRATION STEPS AVAILABLE:
VERSION NAME SOURCE STATUS DATABASE STATUS
1 sample_migration Present Not Present

CURRENT STEP:

VERSION TYPE NAME
1 up sample_migration

Apply 1_sample_migration? (y/n/quit): _

Entering y will apply the migration and then proceed to the next step, should one exist. Entering n, q, or quit will exit the program.