pnpm migrate command with a UI.
Migration Tab Structure
- 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.| Status | Description | Display |
|---|---|---|
| Pending | Migrations not yet applied | π Yellow |
| Applied | Already applied migrations | β Green |
| Failed | Error occurred during execution | β Red |
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:| Change Type | Example |
|---|---|
| Table creation | Add new Entity |
| Column addition | Add Property |
| Column modification | Change type/length |
| Column deletion | Delete Property |
| Index addition | Add Index |
| Foreign key addition | Add belongsTo relation |
Checking Migration Files
Click on a generated migration file to preview its contents:Running Migrations
Run Single Migration
- Select migration file
- Click [Apply] button
- Click [Confirm] in the confirmation modal
Run All Pending Migrations
Click the [Run All] button to run all pending migrations in order.Rolling Back Migrations
Single Rollback
- Select an Applied status migration
- Click [Rollback] button
- Click [Confirm] in the confirmation modal
Migration Preview
You can preview what changes will occur before running a migration.Preview Contents
- β 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:- Modify the timestamp in the migration filename
- Change directly in the file system
- Refresh in the UI
Troubleshooting
Migration Failed
Symptom: Error during migration execution Causes and solutions:| Error | Cause | Solution |
|---|---|---|
| Foreign key constraint | Referenced table doesnβt exist | Create referenced table first |
| Column already exists | Column already exists | Check migration file |
| Cannot drop column | Data exists or constraints exist | Delete constraints first |
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