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: <migration-name>"
- 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: <migration-name>"
- 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`