migrate Command

Apply database migrations using the Akron CLI to synchronize schema changes across SQLite, MySQL, PostgreSQL, and MongoDB.

Overview

The migrate command applies pending database migrations to bring your database schema up to date. It tracks which migrations have been applied and only runs new ones.

Basic Syntax

akron migrate --db <database_url> [options]

Parameters

--db

Type: str (required)

Database connection URL to apply migrations to.

--migrations-dir

Type: str (optional)

Directory containing migration files. Default: ./migrations/

--target

Type: str (optional)

Migrate to specific migration by name. Default: latest

--rollback

Type: flag (optional)

Rollback the last applied migration.

--dry-run

Type: flag (optional)

Show which migrations would be applied without executing them.

Examples

Apply All Pending Migrations

1# Apply all pending migrations
2akron migrate --db "sqlite:///myapp.db"
Expected Output
Migration Status Check:
======================
✓ 001_initial_schema.py - APPLIED
✓ 002_add_user_profiles.py - APPLIED
• 003_add_products_table.py - PENDING
• 004_update_user_schema.py - PENDING

Applying migrations:
====================
→ Applying 003_add_products_table.py... ✓
→ Applying 004_update_user_schema.py... ✓

✓ Applied 2 migrations successfully
✓ Database is now up to date

Migrate to Specific Version

1# Migrate up to a specific migration
2akron migrate --db "mysql://user:pass@host:3306/store" --target "003_add_products_table"
Expected Output
Migration Target: 003_add_products_table.py
==========================================
→ Applying 003_add_products_table.py... ✓

✓ Migrated to target: 003_add_products_table
✓ 1 migration applied

Rollback Last Migration

1# Rollback the most recent migration
2akron migrate --db "postgres://user:pass@host:5432/app" --rollback
Expected Output
Rollback Confirmation:
=====================
Last applied migration: 004_update_user_schema.py
This will execute the downgrade() function.

Are you sure you want to rollback? (y/N): y

→ Rolling back 004_update_user_schema.py... ✓
✓ Migration rolled back successfully

Dry Run Preview

1# Preview what migrations would be applied
2akron migrate --db "mongodb://localhost:27017/social" --dry-run
Expected Output
Migration Preview (DRY RUN):
============================
✓ 001_initial_collections.py - APPLIED
✓ 002_add_user_preferences.py - APPLIED
• 003_update_post_schema.py - PENDING (would apply)
• 004_add_indexes.py - PENDING (would apply)

Would apply 2 migrations.
Run without --dry-run to execute.

Migration Tracking

Migration History Table

Akron automatically creates a migration tracking table to record applied migrations:

1# Migration tracking table structure
2CREATE TABLE akron_migrations (
3 id SERIAL PRIMARY KEY,
4 migration_name VARCHAR(255) NOT NULL UNIQUE,
5 applied_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
6 checksum VARCHAR(64) NOT NULL
7);

Check Migration Status

1# View applied migrations
2akron migrate --db "sqlite:///app.db" --dry-run

This shows which migrations have been applied and which are pending.

Migration Safety

Transaction Safety

Each migration runs in a transaction and rolls back on failure:

1Migration Process:
21. BEGIN TRANSACTION
32. Execute migration upgrade()
43. Record migration in tracking table
54. COMMIT TRANSACTION (or ROLLBACK on error)

Checksum Validation

Migration files are checksummed to detect changes after application, preventing inconsistencies in team environments.

Backup Recommendation

Always backup production databases before running migrations, especially those involving data transformations or structural changes.

Production Deployment

Deployment Script Example

1#!/bin/bash
2# deploy.sh - Production deployment script
3
4echo "Starting deployment..."
5
6# 1. Backup database
7pg_dump $DATABASE_URL > backup_$(date +%Y%m%d_%H%M%S).sql
8
9# 2. Apply migrations
10akron migrate --db "$DATABASE_URL"
11
12if [ $? -eq 0 ]; then
13 echo "✓ Migrations applied successfully"
14
15 # 3. Deploy application code
16 ./deploy_app.sh
17
18 echo "✓ Deployment complete"
19else
20 echo "✗ Migration failed - deployment aborted"
21 exit 1
22fi

Zero-Downtime Migrations

1# For zero-downtime deployments:
2# 1. Apply backward-compatible migrations first
3akron migrate --db "$DATABASE_URL" --target "005_add_new_columns"
4
5# 2. Deploy new application version
6./deploy_new_version.sh
7
8# 3. Apply remaining migrations
9akron migrate --db "$DATABASE_URL"

Error Handling

Common Errors

  • Migration file not found: Check migrations directory path
  • SQL syntax error: Review migration file syntax
  • Permission denied: Ensure database user has DDL privileges
  • Foreign key constraint: Check table dependency order
  • Migration checksum mismatch: Migration file was modified after application

Recovery Strategies

1# If migration fails:
2# 1. Check error details
3akron migrate --db "sqlite:///app.db" --dry-run
4
5# 2. Fix the migration file
6vim migrations/005_problematic_migration.py
7
8# 3. If migration was partially applied, manually clean up:
9akron raw-sql --db "sqlite:///app.db" --query "DROP TABLE IF EXISTS partial_table"
10
11# 4. Mark migration as not applied (if needed)
12akron raw-sql --db "sqlite:///app.db" --query "DELETE FROM akron_migrations WHERE migration_name = '005_problematic_migration.py'"
13
14# 5. Re-run migration
15akron migrate --db "sqlite:///app.db"

Related Commands

Migration Management

→ makemigrations command→ inspect-schema command

Schema Operations

→ create-table command→ raw-sql command

Development

→ seed command→ Getting Started guide