rally-db-migrations-test v0.0.1-ST-866

Rally Database Migrations

Utilities to manage migrations between versions of the database schema.

Database migrations are controlled with Umzug, using javascript files that execute SQL scripts to perform "up" or "down" migrations.

An "up" migration is a forward migration, i.e., going from version 1.0 to 1.1, and a "down" migration represents a backward migration, i.e., to rollback from version 1.1 to 1.0

Migration scripts are stored in:

/src/
    scripts/
        database-migrations/
            scripts/
            sql/

The scripts folder contains a series of javascripts with naming convention:

<Maj>_<min>_<step>_<desc>

Where Maj and min define the major and minor versions, respectively, step indicates the step of the migration, and desc is a description.

For example, the script:

000_000_001_initial_database_creation.js

is the script for version 000.000, step number 001.

In the sql folder are subfolders by maj/min version (e.g., 000_000/) that contain the "up" and "down" migration SQL scripts that are run to perform the database migrations

Therefore, to prepare a new migration step, include:

scripts/
    <your js script>.js
sql/
    MAJ_min/
        <your "up" SQL script>.sql
        <your "down" SQL script>.sql

Migration script are executed in the order of the file names in the /scripts/ folder, i.e., an "up" migration would occur in the following order:

000_000_001
000_000_002
000_001_001
001_000_001

The "down" migrations occur in the opposite (descending) order.

Run Locally

yarn install

Check Database Access

Attempt to connect to the database.

yarn db-authenticate

If the authentication fails, then check your configuration settings (host, port, user, password, database, etc.)

Check Current Migration Status

Provides the version of migrations that have been applied, and a list of pending migrations.

yarn migrate-status

Migrate to the Latest, or to a Specfic Target

Migrates to a specific target.

yarn migrate-to <target>

To apply all pending migrations, leave \<target> blank, which will be treated as "migrate-to latest"

% implied "latest"
yarn migrate-to

To migrate to a specific target, specific the \<target> as MMM_mmm_sss. For example, to migrate to MAJOR version MMM=000, minor version mmm=002, step sss=007:

yarn migrate-to 000_002_007

Note that the migration scripts that do not exist will be skipped. For example, if you have migrated up to version 001_002_100, and then change to a different branch, you may find in an older branch that step 100 does not exist. Thus, the migration system cannot find the necessary scripts to perform up/down migrations. If so, then those steps are merely "skipped" during any migration attempts.

Migrate Up/Forward

Migrates up by executing the next pending migration.

yarn migrate-up

Migrate Down/Backward

Rollsback to previous versions by unwinding the last applied migration.

yarn migrate-down

Insert Test Data

Inserts test data, including a SUPER UserAccount

yarn test-data

Check for Schema Differences

Populates a temporary database (appdb_temp) with the database schema definitions according to the Sequelize models. The results can be used by a database diff tool to check for differences between the currently running database, and whatever the Sequelize models require.

yarn migrate-sync

Build Docker image

docker build ./ -t rally-db-migrations