1# EF Core Migrations Deployment
2 
3Apply Entity Framework Core migrations to Azure SQL Database after deployment.
4 
5## Detection
6 
7EF Core projects contain `Migrations/` folder or `Microsoft.EntityFrameworkCore` package reference in `.csproj`.
8 
9```bash
10find . -type d -name "Migrations" 2>/dev/null
11find . -name "*.csproj" -exec grep -l "Microsoft.EntityFrameworkCore" {} \;
12```
13 
14**PowerShell:**
15```powershell
16Get-ChildItem -Recurse -Directory -Filter "Migrations" -ErrorAction SilentlyContinue
17Get-ChildItem -Recurse -Filter "*.csproj" | Select-String -List "Microsoft.EntityFrameworkCore" | Select-Object -ExpandProperty Path
18```
19 
20## Deployment Methods
21 
22### Method 1: azd Hook (Recommended)
23 
24Automate via `postprovision` hook in `azure.yaml`:
25 
26```yaml
27hooks:
28  postprovision:
29    posix:
30      shell: sh
31      run: ./scripts/apply-migrations.sh
32    windows:
33      shell: pwsh
34      run: ./scripts/apply-migrations.ps1
35```
36 
37**Copy the pre-built scripts** — Read [scripts/apply-migrations.sh](scripts/apply-migrations.sh) and [scripts/apply-migrations.ps1](scripts/apply-migrations.ps1) and write them verbatim to the project's `scripts/` folder. Adjust `APP_PROJECT_PATH` / `$AppProjectPath` in the script to the location of the `.csproj` directory.
38 
39Key behaviours of the scripts:
40- Loads `azd env get-values` safely (no `eval`)
41- Installs `dotnet-ef` automatically when not present; no-op when already installed
42- Fails on genuine install errors (network failure, missing SDK)
43- Adds `~/.dotnet/tools` to `PATH` so the tool is immediately available
44 
45> 💡 Make executable: `chmod +x scripts/*.sh`.
46 
47### Method 2: SQL Script (Production)
48 
49Generate idempotent script for review before applying:
50 
51> ⚠️ **Warning:** `az sql db query` requires the `rdbms-connect` extension: `az extension add --name rdbms-connect --yes`
52 
53```bash
54dotnet ef migrations script --idempotent --output migrations.sql
55az sql db query --server "$SQL_SERVER" --database "$SQL_DATABASE" \
56  --auth-mode ActiveDirectoryDefault --queries "$(cat migrations.sql)"
57```
58 
59**PowerShell:**
60```powershell
61dotnet ef migrations script --idempotent --output migrations.sql
62$MigrationsSql = Get-Content migrations.sql -Raw
63az sql db query --server $env:SQL_SERVER --database $env:SQL_DATABASE `
64  --auth-mode ActiveDirectoryDefault --queries $MigrationsSql
65```
66 
67### Method 3: Application Startup (Dev Only)
68 
69⚠️ **Development only** — production should use explicit migration steps.
70 
71```csharp
72// Program.cs
73if (app.Environment.IsDevelopment()) {
74    using var scope = app.Services.CreateScope();
75    scope.ServiceProvider.GetRequiredService<ApplicationDbContext>().Database.Migrate();
76}
77```
78 
79## Combined Hook: SQL Access + Migrations
80 
81Combine both steps in a single `postprovision` hook using the pre-built combined scripts:
82 
83```yaml
84hooks:
85  postprovision:
86    posix:
87      shell: sh
88      run: ./scripts/grant-and-migrate.sh
89    windows:
90      shell: pwsh
91      run: ./scripts/grant-and-migrate.ps1
92```
93 
94**Copy the pre-built scripts** — Read [scripts/grant-and-migrate.sh](scripts/grant-and-migrate.sh) and [scripts/grant-and-migrate.ps1](scripts/grant-and-migrate.ps1) and write them verbatim to the project's `scripts/` folder. Adjust `APP_PROJECT_PATH` / `$AppProjectPath` in the script to the location of the `.csproj` directory.
95 
96> 💡 Make executable: `chmod +x scripts/*.sh`
97 
98## Prerequisites
99 
100Install EF Core tools:
101 
102```bash
103dotnet tool install --global dotnet-ef
104dotnet ef --version  # Verify installation
105```
106 
107## Connection String
108 
109```
110Server=tcp:{server}.database.windows.net,1433;Database={database};Authentication=Active Directory Default;Encrypt=True;
111```
112 
113## Troubleshooting
114 
115| Error | Solution |
116|-------|----------|
117| Cannot open database | Check firewall rules: `az sql server firewall-rule list` |
118| Login failed | Grant SQL access per [sql-managed-identity.md](sql-managed-identity.md) |
119| Unable to create DbContext | Add `IDesignTimeDbContextFactory` implementation |
120| Hook fails but deployment continues | Remove `|| true` to make migrations block deployment |
121 
122**DbContext Factory Example:**
123 
124```csharp
125public class ApplicationDbContextFactory : IDesignTimeDbContextFactory<ApplicationDbContext> {
126    public ApplicationDbContext CreateDbContext(string[] args) {
127        var optionsBuilder = new DbContextOptionsBuilder<ApplicationDbContext>();
128        var connectionString = Environment.GetEnvironmentVariable("CONNECTION_STRING") 
129            ?? args.FirstOrDefault() ?? "Server=(localdb)\\mssqllocaldb;Database=MyDb;Trusted_Connection=True;";
130        optionsBuilder.UseSqlServer(connectionString);
131        return new ApplicationDbContext(optionsBuilder.Options);
132    }
133}
134```
135 
136## Best Practices
137 
138- Use `--idempotent` flag for production scripts
139- Version control Migrations/ folder
140- Test locally before deploying
141- Backup production databases before applying
142- Keep migrations small and focused
143 
144## References
145 
146- [SQL Managed Identity Access](sql-managed-identity.md)
147- [Post-Deployment Guide](post-deployment.md)
148- [EF Core Migrations](https://learn.microsoft.com/ef/core/managing-schemas/migrations/)
149