Skip to main content
In the Migration tab, you can visually manage migrations to reflect Entity changes in the database. It replaces the CLI pnpm migrate command with a UI.

Migration Tab Structure

Migration Management ScreenMigration Execution Screen

Migration Management Screen

The Migration tab consists of two main areas:
  • Left Sidebar: Migration list (grouped by Pending/Applied status)
  • Right Content: Selected migration details and Preview

Checking Migration Status

Check Status

Click the [Check Status] button to check the current migration status.

Per-Database Status

When multiple databases are configured, you can check status for each DB individually:

Creating Migrations

Sonamu automatically generates migrations when you modify an Entity.

Auto-generated Cases

When there are Entity changes like:

Checking Migration Files

Click on a generated migration file to preview its contents:

Running Migrations

Run Single Migration

  1. Select migration file
  2. Click [Apply] button
  3. Click [Confirm] in the confirmation modal
Execution process:

Run All Pending Migrations

Click the [Run All] button to run all pending migrations in order.
Production caution: Always backup before running migrations on production databases.

Rolling Back Migrations

Single Rollback

  1. Select an Applied status migration
  2. Click [Rollback] button
  3. Click [Confirm] in the confirmation modal
Rollback process:
Data loss risk: Rollback can delete tables or columns, which may result in data loss.

Migration Preview

You can preview what changes will occur before running a migration.

Preview Contents

Icon meanings:
  • βœ… Addition: New tables/columns/indexes
  • πŸ”„ Modification: Existing column type/length changes
  • ⚠️ Deletion: Table/column deletion (potential data loss)

Multi-Database Management

Sonamu can manage multiple databases simultaneously.

Database Selection

You can select target databases when running migrations:
  • β˜‘οΈ Development Master
  • β˜‘οΈ Testing
  • ☐ Production (manual selection)
By default, migrations are automatically applied to databases ending with _master and the test database. Production databases require explicit selection to apply.

Migration Order

Migrations are executed in timestamp order of filenames:

Changing Order

If you need to change the order:
  1. Modify the timestamp in the migration filename
  2. Change directly in the file system
  3. Refresh in the UI
Foreign key caution: Referenced tables must be created first. Example: For posts.user_id β†’ users.id relationship, users table must be created first

Troubleshooting

Migration Failed

Symptom: Error during migration execution Causes and solutions:

Migration Record Mismatch

Symptom: Actual DB state differs from migration records Solution:

Cannot Rollback

Symptom: Error when attempting rollback Cause: down() function not properly defined Solution: Open migration file and fix the down() function

Practical Tips

1. Migrate in Small Units

2. Test Before Production

3. Migration Record Management

  • Commit migration files to Git
  • Specify changes in commit messages
  • Share migration order with team members

Next Steps

Scaffolding Tab

Auto-generate Model code

migrate CLI

Manage migrations via CLI