Skip to main content
By default, Mage uses sqlite to store orchestration data (trigger, pipeline run, and block run). To use a different database, you can set the MAGE_DATABASE_CONNECTION_URL environment variable. In production, you can set the environment variable in the corresponding Terraform script.

​
PostgreSQL

export MAGE_DATABASE_CONNECTION_URL=postgresql+psycopg2://user:password@host:port/dbname To use a specific schema_name in PostgreSQL: export MAGE_DATABASE_CONNECTION_URL="postgresql+psycopg2://user:password@host:port/dbname?options=-c%20search_path%3Dschema_name"

​
Get credentials from AWS Secret Manager

You can also instruct Mage to fetch your Postgres DB credentials from AWS Secret Manager. You will need to set the following environment variables: The expected format of the secret is JSON string with the following keys:
  • username
  • password
  • engine (must be postgres)
  • host
  • port
  • dbname

​
MSSQL (not officially supported)

export MAGE_DATABASE_CONNECTION_URL="mssql+pyodbc://?odbc_connect=DRIVER={ODBC Driver 18 for SQL Server};SERVER=host;DATABASE=dbname;UID=user;PWD=password;ENCRYPT=yes;TrustServerCertificate=yes;"

​
Troubleshoot database migration failures

Mage uses Alembic migrations for orchestration tables such as triggers, pipeline runs, block runs, users, secrets, and audit events. If the server fails during startup with an error like alembic, sqlalchemy.exc, DROP INDEX, CREATE INDEX, alembic_version, or Can't locate revision, use the Mage database CLI before manually editing the database. Start with a read-only diagnosis:
If your project uses the default SQLite database, run the command from the project directory or pass the project path:
The command prints the database dialect, redacted database URL, revision stored in the alembic_version table, migration head in the installed Mage code, recommendations, and any pending revisions that have not been migrated yet. To list every Alembic revision available in the installed Mage code:
This is read-only and does not connect to or change the database. To inspect the current schema for a specific database table:
If your database uses a non-default schema, pass it explicitly:
This prints the table columns, types, nullability, primary key columns, defaults, indexes, and foreign keys. Use it to confirm whether a failed migration already created or removed the table objects referenced by the error before you decide to roll back or stamp a revision.

​
Run pending migrations

If the database is behind the installed Mage code, run:
To migrate to a specific Alembic revision:
This runs migration SQL and uses Mage’s database migration lock so multiple processes do not migrate the same database at the same time.

​
Roll back a failed or incompatible migration

If a migration was applied and you need to revert it, roll back one migration:
Or roll back to a specific revision:
Review the migration file before rolling back in production. A rollback can drop columns, indexes, tables, or enum values depending on the migration. Rollback statements often need exclusive locks on orchestration tables. For example, a downgrade that drops columns from the user table can wait while the running Mage server has active sessions using that table. The CLI applies a PostgreSQL lock timeout so the command fails instead of waiting forever:
To inspect active PostgreSQL sessions that may be blocking the rollback:
For an overall statement cap, also pass:
If rollback times out waiting for locks, stop the Mage server or other workers connected to the orchestration database, then retry the rollback. After the rollback finishes, run mage db diagnose before restarting Mage.

​
Stamp a revision without running SQL

Use stamp only when the database schema already matches the target revision but the alembic_version metadata is missing or wrong:
For non-interactive recovery:
stamp changes Alembic metadata without creating, dropping, or altering database objects. It can help when a migration partially completed outside Alembic, but it can also hide real schema drift if used incorrectly. If you see an error such as index "..." does not exist, confirm whether the rest of the migration’s expected schema changes are already present before stamping past that revision.

​
Typical recovery flow

  1. Back up the database before making changes in production.
  2. Run mage db diagnose.
  3. Run mage db history to find the target revision and surrounding migrations.
  4. If the error names a table, index, or constraint, run mage db schema <table> to inspect the live table.
  5. If the database is behind, run mage db migrate.
  6. If the latest migration is bad for your deployment, run mage db rollback --revision -1, then pin or deploy a Mage version with a compatible migration chain.
  7. If the schema already matches the intended revision but alembic_version is wrong, run mage db stamp <revision>.
  8. Run mage db diagnose again and restart Mage.