DbMigrations is a DBMS-independent migration system for maintaining database schemas. It maintains a linear progress of database changes and is capable of both creating and applying new migrations.
DbMigrations is divided into various subcommands each implement a different feature. To obtain a list of subcommands, use dbmigrations --help
.
To create a new migration, dbmigrations create
can be executed. This will create the file BASEDIR/DATABASE/DATESTAMP/up
where BASEDIR
is the migrations base directory (specified with -b
, default .
), DATABASE
is the name of the database (specified with -d
), and DATESTAMP
is a UTC timestamp in the format yyyyMMddHHmmss
.
To specify a specific version name for creation, -v VERSION
can be supplied. VERSION
is not required to be a timestamp in the format above, but when using this flag be aware of the order in which migrations are applied.
usage: dbmigrations create [-a] [-b BASEDIR] [-d DATABASE] [-v VERSION]
[--help]
optional arguments:
-a, --advanced Create an advanced migration.
-b BASEDIR, --basedir BASEDIR
Specify the migrations base directory.
-d DATABASE, --db DATABASE, --database DATABASE
Specify the database name.
-v VERSION, --version VERSION
Specify the migration version.
--help show this help message and exit
To run migrations, dbmigrations apply
can be executed. This will apply all migrations in the migrations base directory (specified with -b
) with the specified database name (specified with -o database
). It will apply each migration in Lexicographical order.
usage: dbmigrations apply [-o KEY VALUE] [-b BASEDIR] [-v VERSION]
[--env-prefix PREFIX] [-h HOST] [-d DATABASE]
[-p PORT] [-U USER] [--help]
optional arguments:
-o KEY VALUE Specify migrator options.
-b BASEDIR, --basedir BASEDIR
Specify the migrations base directory.
-v VERSION, --version VERSION
Force application of a specific version.
--env-prefix PREFIX Specify the environment prefix.
-h HOST Equivalent to `-o host HOST`.
-d DATABASE Equivalent to `-o database DATABASE`.
-p PORT Equivalent to `-o port PORT`.
-U USER Equivalent to `-o user USER`.
--help show this help message and exit
DbMigrations projects often need to specify connection information (e.g. hostname, username) or other information, in order to create a database connection. Since the options required for any particular DBMS vary, DbMigrations needs some way to allow for that variety of configuration options to be passed to the migrator. To accomplish this, DbMigrations allows for arbitrary key/value pairs to be passed to the migrator.
Three different interfaces exist for specifying options for DbMigrations migrators:
- Command Line Arguments
- Environment Variables
- Configuration File
Key/Value pairs can be passed to the migrator with the -o KEY VALUE
flag.
Providing passwords through command line arguments is strongly discouraged, see the note about Passwords and Security for more information.
For example:
$ dbmigrations print-config -o database testDb -o user testUser -o host my.host
Key Value
host my.host
user testUser
database testDb
Since this notation can be unweildy for commonly used options, the following shorthands may be used to set common environment variables:
-d DATABASE
equivalent to-o database DATABASE
-h HOST
equivalent to-o host HOST
-p PORT
equivalent to-o port PORT
-U USER
equivalent to-o user USER
No shorthand is provided to set a password because command line arguments is an insecure of providing command line arguments. See the note about Passwords and Security for more information.
The environment may also be used to pass options to DbMigrations migrators. This method allows options to be specified globally, rather than per-run. However, since DbMigrations shares the environment with many other processes on the system, options that are intended for DbMigrations are prefixed to prevent options meant for other processes to be passed into DbMigrations.
DbMigrations will ignore all environment variables that do not begin with the environment prefix. If an environment variable does begin with the environment prefix, the key of that variable is altered so that the prefix is removed from it and then made lowercase. The modified key and value are then passed into the migrator.
By default, the prefix is "MIG_
".
For example, using the default prefix:
$ MIG_DATABASE=dbTest MIG_PASSWORD=wXyZ dbmigrations print-config
Key Value
password wXyZ
database dbTest
$ DATABASE=dbTest MIG_PASSWORD=wXyZ dbmigrations print-config
Key Value
password wXyZ
The prefix can be changed with the command line argument --env-prefix PREFIX
.
A project settings file may be provided to specify configuration options for a single migrations project. The project configuration file must be named dbmigrations.conf
. DbMigrations will look in the migrations base directory for such a file. If the file exists, it is used to specify options for DbMigraitons migrators.
The body of the file is simply a JSON object with keys and values for each option.
Providing passwords through configuration files is strongly discouraged, see the note about Passwords and Security for more information.
For security reasons, providing passwords in plaintext via configuration files or command line arguments is strongly discouraged. However, since DbMigrations does not place any restrictions on the content or meanings of options, DbMigrations naively allows providing passwords through all three methods. It is recommended that database passwords only be provided through environment variables.
For debugging purposes, DbMigrations provides a way to print configuration options at the command line. This can be invoked by running dbmigrations print-config
. For security reasons, this has been disabled by default. Enabling this feature can be done by setting the PRINT_CONFIG_ENABLED
option to True
in settings.py.