Skip to content

Database Migrations

xcorecli provides a streamlined wrapper around Alembic to manage your database schema migrations, with added safety features like automated backups.

Getting Started

Migrations are managed via the migration command group.

Initialize Migrations

Set up Alembic for a new project:

1
2
3
4
5
6
7
8
xcli migration init
# Creating alembic/ directory...
# Scanning for models...
#   Found: plugins/auth_plugin/models.py — User, Role
#   Found: plugins/billing_engine/models.py — Invoice, Subscription
# alembic.ini written
# env.py written (multi-model aware)
# Migrations initialized.

Scan for Models

Preview all discovered SQLAlchemy models before generating a migration:

1
2
3
4
5
6
7
8
9
xcli migration scan

# Discovered Models
# ─────────────────────────────────────────
#  Model           Module               Table
#  User            auth_plugin.models   users
#  Role            auth_plugin.models   roles
#  Invoice         billing.models       invoices
#  Subscription    billing.models       subscriptions

Scan Paths

Xcore automatically scans your main app and all installed plugins. Configure additional paths:

integration.yaml
1
2
3
4
migration:
  scan_paths:
    - "myapp/models"
    - "plugins/*/models.py"

Common Workflows

Create a Migration

Generate a new migration script based on model changes:

Generate Migration
1
2
3
xcli migration revision -m "add subscription table"
# Generating migrations/versions/2026_05_27_1234_add_subscription_table.py
# Done.

Apply Migrations

Upgrade the database to the latest schema version:

Upgrade (with automatic backup)
1
2
3
4
5
xcli migration upgrade head --backup
# Creating backup: backups/2026-05-27T14-32-00.sql.gz
# Running migrations:
#   2026_05_27_1234_add_subscription_table ... OK
# Database at revision: 2026_05_27_1234

Rollback

Revert the last applied migration:

Downgrade by 1
1
2
3
xcli migration downgrade -1
# Reverting: 2026_05_27_1234_add_subscription_table
# Done.

Migration History

Check which migrations have been applied:

1
2
3
4
5
6
7
xcli migration history

# Revision               Applied At           Description
# ─────────────────────────────────────────────────────────
# 2026_05_27_1234   2026-05-27 14:32:00  add subscription table
# 2026_05_14_5678   2026-05-14 09:15:12  add user roles
# 2026_04_15_9012   2026-04-15 11:00:00  initial schema

Safety & Backups

Before dangerous operations, xcorecli can automatically back up your database.

Create a Backup

Manually trigger a timestamped backup (supports SQLite, PostgreSQL, MySQL, MariaDB):

1
2
xcli migration backup
# Backup created: backups/2026-05-27T14-32-00.sql.gz (2.3 MB)

Restore from Backup

Restore to a previous state. Omit the path to use the latest backup:

Restore latest
1
2
3
4
xcli migration restore

# Or specify a specific backup file:
xcli migration restore backups/2026-05-14T09-15-12.sql.gz

List Backups

1
2
3
4
5
6
7
8
xcli migration backups

# Available Backups
# ─────────────────────────────────────────
#  File                              Size    Date
#  2026-05-27T14-32-00.sql.gz       2.3 MB  2026-05-27
#  2026-05-14T09-15-12.sql.gz       2.1 MB  2026-05-14
#  2026-04-15T11-00-00.sql.gz       1.8 MB  2026-04-15

Backup Storage

Backups are stored in ./backups by default. Configure the path:

integration.yaml
1
2
migration:
  backup_dir: "/var/lib/xcore/backups"

Stamping

Use xcli migration stamp <id> to mark the database at a specific revision without running migration scripts — useful when adopting Xcore on an existing database.