managing-apps/.cursor/commands/migration-local.md

migration-local

When to Use

Use this command when you want to:

• Create a new EF Core migration based on model changes
• Apply the migration to your local PostgreSQL database
• Update your local database schema to match the current code

Prerequisites

• .NET SDK installed (dotnet --version)
• PostgreSQL running locally
• Local database connection configured (default: Host=localhost;Port=5432;Database=managing;Username=postgres;Password=postgres)

Execution Steps

Step 1: Verify Database Project Structure

Check that the database project exists:

• Database project: src/Managing.Infrastructure.Database
• Startup project: src/Managing.Api
• Migrations folder: src/Managing.Infrastructure.Database/Migrations

Step 2: Build the Solution

Before creating migrations, ensure the solution builds successfully:

Run: dotnet build src/Managing.sln

If build succeeds:

• Continue to Step 3

If build fails:

• Show build errors
• Analyze errors:
  • C# compilation errors
  • Missing dependencies
  • Configuration errors
• Try to fix errors automatically:
  • Fix C# compilation errors
  • Fix missing imports
  • Fix configuration issues
• If errors can be fixed:
  • Fix the errors
  • Re-run build
  • If build succeeds, continue to Step 3
  • If build still fails, show errors and ask user for help
• If errors cannot be fixed automatically:
  • Show detailed error messages
  • Explain what needs to be fixed
  • STOP: Do not proceed until build succeeds

Step 3: Check for Pending Model Changes

Check if there are any pending model changes that require a new migration:

Run: cd src/Managing.Infrastructure.Database && dotnet ef migrations add --dry-run --startup-project ../Managing.Api --name "CheckPendingChanges_$(date +%s)"

If no pending changes detected:

• Inform: "✅ No pending model changes detected. All migrations are up to date."
• Ask user: "Do you want to create a migration anyway? (y/n)"
• If yes: Continue to Step 4
• If no: STOP - No migration needed

If pending changes detected:

• Show what changes require migrations
• Continue to Step 4

Step 4: Generate Migration Name

Ask the user for a migration name, or generate one automatically:

Option 1: User provides name

• Prompt: "Enter a migration name (e.g., 'AddBacktestJobsTable'):"
• Use the provided name

Option 2: Auto-generate name

• Analyze model changes to suggest a descriptive name
• Format: Add[Entity]Table, Update[Entity]Field, Remove[Entity]Field, etc.
• Examples:
  • AddBacktestJobsTable
  • AddJobTypeToBacktestJobs
  • UpdateUserTableSchema
• Ask user to confirm or modify the suggested name

Step 5: Create Migration

Create the migration using EF Core:

Run: cd src/Managing.Infrastructure.Database && dotnet ef migrations add "<migration-name>" --startup-project ../Managing.Api

If migration creation succeeds:

• Show: "✅ Migration created successfully: "
• Show the migration file path
• Continue to Step 6

If migration creation fails:

• Show error details
• Common issues:
  • Database connection issues
  • Model configuration errors
  • Missing design-time factory
• Try to fix automatically:
  • Check connection string in DesignTimeDbContextFactory.cs
  • Verify database is running
  • Check model configurations
• If errors can be fixed:
  • Fix the errors
  • Re-run migration creation
  • If succeeds, continue to Step 6
• If errors cannot be fixed:
  • Show detailed error messages
  • Explain what needs to be fixed
  • STOP: Do not proceed until migration is created

Step 6: Review Migration File (Optional)

Show the user the generated migration file:

Run: cat src/Managing.Infrastructure.Database/Migrations/<timestamp>_<migration-name>.cs

Ask: "Review the migration file above. Does it look correct? (y/n)"

If user confirms:

• Continue to Step 7

If user wants to modify:

• Allow user to edit the migration file
• After editing, ask to confirm again
• Continue to Step 7

Step 7: Apply Migration to Local Database

Apply the migration to the local database:

Run: cd src/Managing.Infrastructure.Database && dotnet ef database update --startup-project ../Managing.Api

If update succeeds:

• Show: "✅ Migration applied successfully to local database"
• Show: "Database schema updated: "
• Continue to Step 8

If update fails:

• Show error details
• Common issues:
  • Database connection issues
  • Migration conflicts
  • Database schema conflicts
  • Constraint violations
• Try to fix automatically:
  • Check database connection
  • Check for conflicting migrations
  • Verify database state
• If errors can be fixed:
  • Fix the errors
  • Re-run database update
  • If succeeds, continue to Step 8
• If errors cannot be fixed:
  • Show detailed error messages
  • Explain what needs to be fixed
  • Suggest: "You may need to manually fix the database or rollback the migration"
  • STOP: Do not proceed until migration is applied

Step 8: Verify Migration Status

Verify that the migration was applied successfully:

Run: cd src/Managing.Infrastructure.Database && dotnet ef migrations list --startup-project ../Managing.Api

If migration is listed as applied:

• Show: "✅ Migration status verified"
• Show the list of applied migrations
• Success message: "✅ Migration created and applied successfully!"

If migration is not listed or shows as pending:

• Warn: "⚠️ Migration may not have been applied correctly"
• Show migration list
• Suggest checking the database manually

Error Handling

If build fails:

• STOP immediately - Do not create migrations for broken code
• Show build errors in detail
• Try to fix common errors automatically:
  • C# compilation errors
  • Import path errors
  • Syntax errors
  • Missing imports
• If errors can be fixed:
  • Fix them automatically
  • Re-run build
  • If build succeeds, continue
  • If build still fails, show errors and ask for help
• If errors cannot be fixed:
  • Show detailed error messages
  • Explain what needs to be fixed
  • STOP: Do not proceed until build succeeds

If database connection fails:

• Check if PostgreSQL is running: pg_isready or psql -h localhost -U postgres -c "SELECT 1"
• Verify connection string in DesignTimeDbContextFactory.cs
• Check if database exists: psql -h localhost -U postgres -lqt | cut -d \| -f 1 | grep -qw managing
• If database doesn't exist, create it: createdb -h localhost -U postgres managing
• Retry migration creation

If migration conflicts:

• Check existing migrations: cd src/Managing.Infrastructure.Database && dotnet ef migrations list --startup-project ../Managing.Api
• If migration already exists with same name, suggest a different name
• If database schema conflicts, suggest reviewing the migration file

If database update fails:

• Check database state: psql -h localhost -U postgres -d managing -c "\dt"
• Check applied migrations: psql -h localhost -U postgres -d managing -c "SELECT * FROM \"__EFMigrationsHistory\";"
• If migration partially applied, may need to rollback or fix manually
• Suggest: "Review the error and fix the database state, or rollback the migration"

Example Execution

User input: /migration-local

AI execution:

1. Verify structure: Check src/Managing.Infrastructure.Database exists ✅
2. Build solution: dotnet build src/Managing.sln → ✅ Build successful!
3. Check pending changes: dotnet ef migrations add --dry-run ... → ⚠️ Pending changes detected
4. Generate name: Analyze changes → Suggest "AddBacktestJobsTable"
5. Confirm name: "Migration name: 'AddBacktestJobsTable'. Proceed? (y/n)" → User confirms
6. Create migration: dotnet ef migrations add "AddBacktestJobsTable" ... → ✅ Migration created
7. Review file: Show migration file → User confirms
8. Apply migration: dotnet ef database update ... → ✅ Migration applied
9. Verify status: dotnet ef migrations list ... → ✅ Migration verified
10. Success: "✅ Migration created and applied successfully!"

If build fails:

1-2. Same as above 3. Build: dotnet build src/Managing.sln → ❌ Build failed 4. Analyze errors: C# compilation error in JobEntity.cs 5. Fix errors: Update type definitions 6. Re-run build: dotnet build src/Managing.sln → ✅ Build successful! 7. Continue with migration creation

If database connection fails:

1-5. Same as above 6. Create migration: dotnet ef migrations add ... → ❌ Connection failed 7. Check database: pg_isready → Database not running 8. Inform user: "PostgreSQL is not running. Please start PostgreSQL and try again." 9. STOP: Wait for user to start database

Important Notes

• ✅ Always build before creating migrations - ensures code compiles correctly
• ✅ Review migration file before applying - verify it matches your intent
• ✅ Backup database before applying - migrations can modify data
• ✅ Use descriptive migration names - helps track schema changes
• ⚠️ Migration is applied to local database only - use other tools for production
• ⚠️ Ensure PostgreSQL is running - connection will fail if database is down
• 📦 Database project: src/Managing.Infrastructure.Database
• 🔧 Startup project: src/Managing.Api
• 🗄️ Local connection: Host=localhost;Port=5432;Database=managing;Username=postgres;Password=postgres
• 📁 Migrations folder: src/Managing.Infrastructure.Database/Migrations