NEW COMMAND

akron db migrate

Apply pending migration files to update your database schema and synchronize it with your akron.json configuration.

Syntax

1akron db migrate [OPTIONS]

Options

Option	Description	Default
--dry-run	Show what would be migrated without applying changes	false

How It Works

Migration Process

Connects to the database using the URL from akron.json
Checks for existing migration history in _akron_migrations table
Identifies pending migrations by comparing applied vs. available migrations
Applies each migration step in chronological order
Records successful migrations in the database
Reports completion status and any errors

Examples

Dry Run (Preview Mode)

Preview what changes will be applied without modifying the database:

1akron db migrate --dry-run

Expected Output

🔍 Dry run - showing pending migrations:
   • initial.json
   • add_user_authentication.json
   • create_posts_table.json

Apply All Pending Migrations

Apply all pending migrations to the database:

1akron db migrate

Expected Output

📦 Applying 3 migration(s)...
   Applying initial.json...
   ✅ Applied initial.json
   Applying add_user_authentication.json...
   ✅ Applied add_user_authentication.json
   Applying create_posts_table.json...
   ✅ Applied create_posts_table.json
✅ All migrations applied successfully!

No Pending Migrations

When all migrations are already applied:

1akron db migrate

Expected Output

✅ No pending migrations.

Migration Error Handling

When a migration fails:

1akron db migrate

Expected Output

📦 Applying 2 migration(s)...
   Applying initial.json...
   ✅ Applied initial.json
   Applying invalid_migration.json...
   ❌ Migration failed: column 'email' already exists

Error: Migration stopped due to failure. Please fix the issue and try again.

Migration Steps

Supported Operations

Table Operations

• create_table - Create new tables with schema
• drop_table - Remove existing tables

Column Operations

• add_column - Add new columns to tables
• drop_column - Remove columns (limited support)
• modify_column - Change column definitions (limited support)

Migration Tracking

_akron_migrations Table

Akron tracks applied migrations in a special table:

1CREATE TABLE _akron_migrations (
2    id INTEGER PRIMARY KEY AUTOINCREMENT,
3    migration_name TEXT UNIQUE NOT NULL,
4    checksum TEXT NOT NULL,
5    applied_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
6);

Migration Record Example

id | migration_name           | checksum                                                   | applied_at          |
----|-------------------------|------------------------------------------------------------|---------------------|
1  | initial.json            | 495bf72e9cefcc7fd020cddeadfcb4d535cab46d6076b7d0b6befdc76e9006d3 | 2023-12-01 10:30:15 |
2  | add_user_auth.json      | a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0 | 2023-12-01 11:45:22 |

Database-Specific Behavior

SQL Databases

SQLite, MySQL, PostgreSQL:

• Full migration support
• Transaction-based application
• Migration history tracking
• Foreign key constraints supported

MongoDB

Document database:

• Collection creation/deletion
• Schema-less by nature
• Limited migration tracking
• Index operations (future)

Troubleshooting

⚠️ Common Issues

Database Connection Failed

Check your database URL in akron.json and ensure the database server is running.

Migration Already Applied

This migration was already applied. Check akron db status for current state.

Column Already Exists

The migration tries to create a column that already exists. Review your schema changes.

💡 Recovery Steps

Check current status with akron db status
Review failed migration file for issues
Fix schema definition in akron.json if needed
Generate new migration if necessary
Try migration again

Best Practices

✅ Recommended Practices

• Always run --dry-run first to preview changes
• Backup your database before applying migrations in production
• Apply migrations in staging environment first
• Monitor migration logs for any warnings or errors
• Keep migration files in version control

❌ Avoid These Mistakes

• Don't manually edit migration files after generation
• Don't skip migrations or apply them out of order
• Don't run migrations directly on production without testing
• Don't delete migration files that have been applied

Next Steps

After applying migrations:

Verify changes with akron db status
Test your application with the updated schema
Commit migration files to version control
Deploy to staging/production environments

→ Check Migration Status → Schema Management Guide → Getting Started