pgmig 1.0.3

Generate migrations between Postgres databases.

Use pgmig to compare the structure of two Postgres databases — a source and a target — and generate the SQL that turns the source into the target.

pgmig connects read-only to both databases and never runs the generated SQL for you: you review it and apply it yourself.

pgmig officially supports Postgres 14–18 — the majors currently maintained upstream — and is tested against each in CI. Other versions may work but are not tested.

This project is currently in active development, see Roadmap.

Table of Contents

1. Getting Started
2. Configuration
3. FAQ
4. Contributing
5. License

Getting Started

Installation

pgmig is available as pgmig on PyPI.

Invoke pgmig directly with uvx:

uvx pgmig generate \
  --source postgresql://user:pass@localhost:5432/current \
  --target postgresql://user:pass@localhost:5432/desired

Or install pgmig with uv (recommended) or pip:

# With uv.
uv tool install pgmig@latest  # Install pgmig globally.
uv add --dev pgmig            # Or add pgmig to your project.

# With pip.
pip install pgmig

Usage

pgmig can be used directly in the command line or as a Python library.

Command line

Print the migration SQL that makes source match target:

pgmig generate \
  --source postgresql://user:pass@localhost:5432/current \
  --target postgresql://user:pass@localhost:5432/desired

When the two structures already match, nothing is printed.

Library

The same diff is available as a function that returns the SQL as a string:

import pgmig

sql = pgmig.generate(
    source="postgresql://user:pass@localhost:5432/current",
    target="postgresql://user:pass@localhost:5432/desired",
)

print(sql)  # the migration SQL

generate returns an empty string when the structures already match.

Configuration

pgmig has no configuration file — everything is passed on the command line (or as arguments to pgmig.generate).

The CLI (pgmig generate) and the library (pgmig.generate) share the same options; the CLI adds a few more (— in the library column):

Connections

Each DSN can be passed as a flag or through its environment variable; an explicit flag wins. Command-line arguments are visible in ps output and shell history, so prefer the environment variables for anything containing secrets — for example, in CI:

- run: pgmig generate --check
  env:
    PGMIG_SOURCE: ${{ secrets.PROD_DATABASE_URL }}
    PGMIG_TARGET: postgresql://postgres:postgres@localhost:5432/desired

Other commands:

A DSN is any libpq connection string, e.g. postgresql://user:pass@host:5432/dbname.

FAQ

Do I need libpq installed?

By default, yes — pgmig requires the Postgres client library (libpq) on the machine. For standalone / CLI use you can skip that by installing the binary extra, which bundles it:

pip install 'pgmig[binary]'

Contributing

Contributions are welcome!

See CONTRIBUTING.md for details.

License

pgmig is distributed under the terms of the MIT license.