SQLAlchemy

Use DBLiftClient.from_sqlalchemy when your application already owns an Engine or a Connection. This is the primary Python-native entry point, and the one the Django, Flask and FastAPI helpers build on.

api · DBLiftClient.from_sqlalchemy

From an engine

migrate.py

python

from sqlalchemy import create_engine

from dblift.api import DBLiftClient

engine = create_engine("postgresql+psycopg://user:password@localhost/app")

with DBLiftClient.from_sqlalchemy(
    engine=engine,
    migrations_dir="migrations",
) as client:
    client.validate()
    client.migrate()

Engine or connection

A live connection works in place of an engine. Do not pass both engine= and connection= in one call.

migrate.py

python

with engine.connect() as connection:
    client = DBLiftClient.from_sqlalchemy(
        connection=connection,
        migrations_dir="migrations",
    )
    client.migrate()
    client.close()

from_sqlalchemy also takes migrations_dir as a list of paths, a schema, and logging arguments: logger, log_level, log_format and log_file.

Ownership

When you supply the engine or the connection, DBLift does not own it. client.close() releases DBLift’s own resources and leaves your engine undisposed and your externally supplied connection open — your application keeps its normal SQLAlchemy lifecycle.

Read-only status checks

status.py

python

with DBLiftClient.from_sqlalchemy(engine=engine, migrations_dir="migrations") as client:
    info = client.info()
    pending = getattr(info, "pending_migrations", []) or []

info() never applies migrations, which is what makes it safe in startup guards, health endpoints and deploy checks.

Python migrations

A Python migration receives a MigrationContext with the active engine, connection, schema, config, placeholders, log (not logger), dry_run, db, raw_client, provider, and an execute helper.

migrations/V1_1_0__add_users.py

python

from dblift.api import MigrationContext

def migrate(context: MigrationContext) -> None:
    context.execute("CREATE TABLE app_users (id INTEGER PRIMARY KEY)")

Sync engines only

from_sqlalchemy accepts synchronous Engine and Connection objects. In an async application, keep a sync engine for migration work or wrap the client with AsyncDBLiftClient.

SQLAlchemy

From an engine

Engine or connection

Ownership

Read-only status checks

Python migrations

Read next