dblift 5.1.0

Plain SQL migrations for Python. See the exact SQL before it runs.

Get started · Documentation · Coming from Flyway · Adopt an existing database

DBLift applies versioned .sql files to your database and remembers what ran. Same file convention as Flyway (V1__create_users.sql), installed with pip, usable as a CLI or as a Python library. Preview, undo, checksums and locking are part of the open-source package. Apache 2.0.

Try it in 60 seconds

No database server needed — this runs against a local SQLite file.

pip install "dblift[cli]"

mkdir migrations
echo "CREATE TABLE users (id INTEGER PRIMARY KEY, email TEXT NOT NULL UNIQUE);" > migrations/V1__create_users.sql
echo "DROP TABLE users;" > migrations/U1__create_users.sql

export DBLIFT_DB_URL="sqlite:///app.db"

dblift migrate --dry-run --show-sql   # prints the SQL, applies nothing
dblift migrate                        # applies V1
dblift info                           # what ran, when, by whom, and whether it can be undone
dblift undo                           # runs U1, rolls the last migration back

For a real database, install the driver extra next to cli and point the URL at it:

pip install "dblift[cli,postgresql]"
export DBLIFT_DB_URL="postgresql+psycopg://user@localhost:5432/mydb"
export DBLIFT_DB_PASSWORD="..."

Your first migration → · Configuration →

Is this for you?

You run Flyway from a Python project. A JVM, a Docker image or a downloaded tarball, kept patched only to apply SQL files. DBLift reads the same V / R / U file names, and dblift import-flyway copies your flyway_schema_history so every environment keeps its history. What changes is the install line. Move from Flyway →

You apply SQL with a migrate.sh or a home-made migrate.py. It works until two files share a number, someone edits an applied file, a replica starts at the same time, or production turns out to be two migrations behind staging. That script is a migration tool you maintain by accident. Rename the files, run dblift baseline once per existing database, and delete it. Adopt an existing database → · Naming conventions →

You want migrations you can read in a pull request. Not revisions generated from an ORM — the SQL you wrote, reviewed as SQL, run as written. Works next to SQLAlchemy, Django, FastAPI and Flask, or with none of them.

What you get

Everything below ships in the open-source package.

Ordering: DBLift applies out-of-order migrations by default — if V3 is applied and a teammate's V2 merges later, V2 still runs. This is the opposite of Flyway's default. Use --strict or strict_mode: true to enforce version order. Versioning →

Use it from Python

Run migrations when your app starts:

from sqlalchemy import create_engine
from dblift.api import DBLiftClient

engine = create_engine("postgresql+psycopg://user:pass@localhost/app")
with DBLiftClient.from_sqlalchemy(engine, migrations_dir="migrations") as client:
    client.migrate()

AsyncDBLiftClient (from dblift.api.async_client import AsyncDBLiftClient) does the same without blocking an event loop. API → · Async client →

Give your tests a migrated database:

pip install pytest-dblift

def test_schema_is_current(dblift_migrated_db, dblift_client):
    assert dblift_client.info().pending_count == 0

pytest-dblift →

Integrations: Django management commands and system check · FastAPI · Flask · SQLAlchemy · OpenTelemetry spans · CI/CD recipes for GitHub Actions, GitLab CI and pre-commit · an MCP server for AI assistants.

How it compares

Alembic is the right choice when your schema is driven by SQLAlchemy models and you want autogenerated revisions. DBLift is for teams who write the SQL themselves.

Databases

20 engines. SQLite needs no driver extra; every other engine has its own, e.g. pip install "dblift[cli,postgresql]".

A bare pip install dblift is the lightweight library install (PyYAML and SQLAlchemy only). dblift[cli] adds the command line (Rich, Jinja2) and SQL analysis (SQLGlot). Python API users can add SQL analysis without the CLI using dblift[analysis]; the API runs without it by default, in execution-only mode, and uses it when you pass analysis_mode="full". dblift[all] installs both plus every database driver.

PostgreSQL · MySQL · MariaDB · SQL Server · Oracle · DB2 · SQLite · DuckDB · CockroachDB · Redshift · Snowflake · Neon · Supabase · Aurora PostgreSQL · AlloyDB · YugabyteDB · TimescaleDB · Citus · Azure Cosmos DB · MongoDB

What each engine supports is in the capability matrix; connection details are under Engines.

What Pro adds

The OSS tier covers the full migration lifecycle: apply, preview, validate state, roll back, and import from Flyway. When review risk grows, the Pro tier adds:

See pricing and Pro features →

Documentation

Everything lives at docs.dblift.com.

Project

• Released on PyPI with trusted publishing — see the changelog and releases.
• Questions, ideas, "would this work for us?" Ask in Discussions.
• Found a bug? Open an issue. Reports with a failing migration file attached get fixed fastest.
• Want to contribute? See CONTRIBUTING.md.
• Security: see SECURITY.md.
• License: Apache 2.0.

If DBLift saved you a JVM or a migrate.sh, a ⭐ helps other teams find it.