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.
- Generate the necessary create extension if not exists... statements using
-
--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!