Your First Migration

Write one SQL file, preview the exact statements it will run, then apply. Seven steps, OSS commands only.

1. Point DBLift at a database

The environment variable is the shortest path. Every command below works as-is once it is set.

export DBLIFT_DB_URL="postgresql+psycopg://user:password@localhost:5432/mydb"

Prefer a file? Write dblift.yaml in the project root. When --config and --db-url are omitted, the CLI loads dblift.yaml or dblift.yml from the current working directory. Pass --config path/to/dblift.yaml only for a file outside that directory. See Configuration.

2. Write the migration

Filenames follow V{version}__{description}.sql. The version decides apply order.

sql

-- migrations/V1_0_0__create_users_table.sql
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    email VARCHAR(255) NOT NULL UNIQUE
);

3. Check state, then preview

This is the step other tools skip. --dry-run --show-sql prints every statement the pending migrations would execute without touching the database.

dblift info                         # applied, pending, undo coverage
dblift migrate --dry-run --show-sql # exactly what would run

Command	What it tells you
`dblift info`	The full migration table: which versions are applied, which are pending, and whether each has a matching undo file.
`dblift migrate --dry-run --show-sql`	Exact SQL that would run, without applying it.

4. Apply

Migrations run in version order and each is recorded in the schema history table. Run dblift info again to confirm.

dblift migrate

5. Make it reversible

An undo file pairs with the migration by version: U1_0_0__drop_users_table.sql reverses V1_0_0__create_users_table.sql. Preview a rollback the same way you previewed the apply.

dblift undo --dry-run --show-sql
dblift undo --target-version=0   # back to before V1_0_0

The daily loop

dblift info                         # where are we?
dblift migrate --dry-run --show-sql # what will run?
dblift migrate                      # apply

Targeting Azure Cosmos DB?

Cosmos DB and MongoDB have no SQL DDL, so migrations are Python files such as V1_0_0__create_users_container.py that drive the vendor SDK. A .sql migration there fails with DBLIFT-NOSQL-001. Everything else on this page is unchanged.

Next: Naming Conventions and the Undo model.