Configuration

delembic.ini

Delembic reads configuration from delembic.ini. It walks up from the current directory, so you can run delembic commands from any subdirectory of your project.

Full example

[delembic]
script_location = delembic
sqlalchemy.url = postgresql+psycopg://user:pass@localhost/mydb
alembic_config = alembic.ini

Options

script_location

Path to the folder containing versions/. Relative to the location of delembic.ini. Default: delembic

sqlalchemy.url

SQLAlchemy database URL. Required. Examples:

postgresql+psycopg://user:pass@localhost/mydb
postgresql+psycopg2://user:pass@localhost/mydb
sqlite:///data.db
sqlite:///:memory:

alembic_config

Path to your alembic.ini. Relative to delembic.ini. Optional — only needed if you use Alembic integration. When set, delembic revision will auto-capture current Alembic heads into depends_on.

Custom Folder Name

delembic init data-migrations

delembic.ini is updated automatically:

[delembic]
script_location = data-migrations

Environment Variables

Delembic does not read environment variables directly. Use env.py (generated by delembic init) to inject them:

# delembic/env.py
import os
from sqlalchemy import create_engine

DATABASE_URL = os.environ["DATABASE_URL"]

def get_engine():
    return create_engine(DATABASE_URL)

Then reference it from your migrations if needed, or configure sqlalchemy.url to read from env using a wrapper.

Metadata Tables

Delembic automatically creates two tables on first run:

delembic_version

Current status per revision. One row per revision, replaced on retry.

Column	Type	Description
revision	TEXT	Revision ID (e.g. D001)
status	TEXT	success or failed
applied_at	DATETIME	When this run started
duration_seconds	FLOAT	How long the migration took
username	TEXT	OS user who ran the migration
hostname	TEXT	Hostname where migration ran

delembic_run_history

Full append-only audit log. Every run appended, never deleted.

Column	Type	Description
id	INTEGER	Auto-increment primary key
revision	TEXT	Revision ID
status	TEXT	success or failed
started_at	DATETIME	Run start time
ended_at	DATETIME	Run end time
duration_seconds	FLOAT	Duration
exception	TEXT	Full traceback (failures only)
username	TEXT	OS user
hostname	TEXT	Hostname

Note

Failed migration work is rolled back. The failure record is always committed on a separate connection — the audit trail survives transaction failures.