/serverpod:merge-migrations#

Context Framework Note: Merges multiple development migrations into a single migration before production deployment.

Triggers#

• When cleaning up migrations before production deployment
• When consolidating multiple development migrations into one
• When cleaning up migration history

Context Trigger Pattern#

/serverpod:merge-migrations --base {production_migration} [--options]

Parameters#

Note: --base is always required. Specify the production-applied migration ID to only merge development migrations after that point.

Behavioral Flow#

Step 1: Migration Analysis#

## Migration Analysis

**Production baseline**: {base_migration}
**Merge targets**: {count}

| # | Migration ID | Created | Changed Tables |
|---|-------------|---------|----------------|
| 1 | 20251229134213396 | 2025-12-29 | coupon |
| 2 | 20260112140301453 | 2026-01-12 | author |
| 3 | 20260113023207235 | 2026-01-13 | author |

**Affected tables**: coupon, author

Step 2: SQL Merge#

## SQL Merge Preview

### Before merge (individual migrations)

-- Migration 1: 20251229134213396 ALTER TABLE "coupon" ADD COLUMN "new_field" text;

-- Migration 2: 20260112140301453 ALTER TABLE "author" ADD COLUMN "memo" text;

-- Migration 3: 20260113023207235 ALTER TABLE "author" ADD COLUMN "extra" text;

 ### After merge (single migration)

-- Migration: {new_migration_id} BEGIN;

ALTER TABLE "coupon" ADD COLUMN "new_field" text; ALTER TABLE "author" ADD COLUMN "memo" text; ALTER TABLE "author" ADD COLUMN "extra" text;

-- MIGRATION VERSION FOR kobic INSERT INTO "serverpod_migrations" ("module", "version", "timestamp") VALUES ('kobic', '{new_migration_id}', now()) ON CONFLICT ("module") DO UPDATE SET "version" = '{new_migration_id}', "timestamp" = now();

COMMIT;

Step 3: User Confirmation#

## Merge Confirmation

**Caution**:
- This operation deletes existing migration files
- Run only on local development DB
- Existing migrations must already be applied to the production DB

**Proceed with merge? (Y/n)**

Step 4: Execute Merge#

# 1. Backup existing migrations
mkdir -p migrations_backup
for dir in migrations/{from} migrations/{middle} migrations/{to}; do
  cp -r  " $dir "   migrations_backup/
done

# 2. Delete existing migrations
rm -rf migrations/{from}
rm -rf migrations/{middle}
rm -rf migrations/{to}

# 3. Create new migration
serverpod create-migration --experimental-features=all

# 4. Update migration_registry.txt
# Remove old migration IDs, add new ID

Step 5: Verification#

## Merge Complete

Existing migrations backed up: `migrations_backup/`
New migration created: `{new_migration_id}`
migration_registry.txt updated

### Next Steps

1. **Reset local DB** (optional):
   

Recreate local DB from scratch#

melos run backend:pod:run-migration

 2. **Commit changes**:
   

git add backend/kobic_server/migrations/ git commit -m "chore(migration): merge migrations ({from}~{to} → {new_id})"

 ### Backup Location
Existing migrations are stored in `migrations_backup/`

Output Files#

backend/kobic_server/
├── migrations/
│   ├── {base_migration}/           # Production (preserved)
│   ├── {new_migration}/            # Newly created merged migration
│   │   ├── definition.json
│   │   ├── definition.sql
│   │   ├── definition_project.json
│   │   ├── migration.json
│   │   └── migration.sql
│   └── migration_registry.txt      # Updated
├── migrations_backup/              # Backup (can be deleted)
│   ├── {old_migration_1}/
│   ├── {old_migration_2}/
│   └── ...

Manual Merge Guide (Instead of Script)#

If the skill does not auto-execute, follow these steps manually:

1. Check Current State#

# Check migration_registry.txt
cat backend/kobic_server/migrations/migration_registry.txt

# Check post-production migrations
ls -la backend/kobic_server/migrations/ | grep  " 2026 "

2. Backup and Delete Existing Migrations#

cd backend/kobic_server

# Backup
mkdir -p migrations_backup
mv migrations/20251229134213396 migrations_backup/
mv migrations/20260112140301453 migrations_backup/
mv migrations/20260113023207235 migrations_backup/

# Remove the corresponding lines from migration_registry.txt
# Manually edit to remove the migration IDs to be deleted

3. Create New Migration#

# Code generation (based on current models)
melos run backend:pod:generate

# Create new migration
melos run backend:pod:create-migration

4. Verify#

# Check new migration
ls -la backend/kobic_server/migrations/ | tail -5

# Check migration_registry.txt
tail backend/kobic_server/migrations/migration_registry.txt

Examples#

Basic usage (production baseline)#

Auto-detect and merge all migrations after --base:

/serverpod:merge-migrations --base 20251223123500000

Range specification#

Merge specific range based on --base (after base ~ to):

/serverpod:merge-migrations \
  --base 20251223123500000 \
  --from 20251229134213396 \
  --to 20260113023207235

Dry-run (preview)#

Preview merged content without actual changes:

/serverpod:merge-migrations --base 20251223123500000 --dry-run

Core Rules#

1. Production baseline: Do not touch production-applied migrations
2. Backup required: Always backup before deletion
3. Local only: Never run on production DB
4. Order preserved: Migration order is automatically managed by timestamp
5. Verification required: Verify with melos run backend:pod:generate after merge

Cautions#

Production DB caution:

• Existing migrations are already applied to the production DB
• Merged migrations are only used in new environments
• Existing production is unaffected (references serverpod_migrations table)

Team collaboration:

• Migration conflicts possible with other developers
• Coordinate with team members before merging
• Check migration_registry.txt conflicts before PR merge