Using migra directly

We recommend using migra's schema diffing powers via the databaseci package, as this will be the best supported means of use in future.

databaseci uses migra under the hood to do PostgreSQL schema "diffing".

databaseci is written by the same author as migra. It expands the same focussed design philosophy to more areas of database tooling, and aims to make development and maintenance of these tools more financially stable.

databaseci is free to use for individuals and small organisations, but a paid sub comes with extra features (like subsetting) and is required if in production use in an organization with more than 5 users.

migra will continue to be maintained as a separate standalone package focussed entirely as before on excellent schema diffing.

To use migra separately, you can just install it with pip:

pip install migra

You'll also need a postgres driver if you don't already have one installed, if in doubt use the psycopg2-binary package:

pip install psycopg2-binary

Basic usage

migra follows the usage pattern of other diff tools: Two arguments, a and b, or from and to. In database migration terms, they could also be thought of as current state and desired state.

For example, given two databases running locally called, a and b, the following command will generate the schema diff to transform a's structure into b's structure:

migra postgresql:///a postgresql:///b

The command will deliberately fail if any DROP... statements are contained in the diff. To stop this, and generate a diff even if it would be destructive, add the --unsafe flag:

migra --unsafe postgresql:///a postgresql:///b

migra command line options

The command line version of migra includes a number of options for getting the diff output you desire. If using the API, similarly named options are available on the Migration object.

• --unsafe: Migra will throw an exception if drop... statements are generated, as a precaution. Adding this flag will disable the safety feature and happily generate the drop statements. Remember, always review generated statements before running them!

• --schema [SCHEMA_NAME]: Specify a single schema to diff.

• --create-extensions-only Only output create extension statements, nothing else. This is useful when you have extensions as part of a setup script for a single schema: Those extensions need to be installed, but extensions are usually not installed in a custom schema.

  You'd generate a setup script in two steps:

  • Generate the necessary create extension if not exists... statements using --create-extensions-only.
  • Generate the schema changes with --schema-only.

  Then combine the output of 1 and 2 into a single database sync script.

• --with-privileges: This tells migra to spit out permission-related change statements (grant/revoke). This is False by default: Often one is comparing databases from different environments, where the users and permissions are completely different and not something one would want to sync.

• --force-utf8: Some folks have reported unicode character output issues on windows command lines. This flag often fixes it!