services/projection-api/Projection.ReadModel/ServiceCollectionExtensions.cs

@@ -19,12 +19,46 @@ public static class ServiceCollectionExtensions
         return services;
     }
 
+    // A fixed application-scoped key for the migration advisory lock (any stable 64-bit constant).
+    private const long MigrationAdvisoryLockKey = 727501;
+
     /// <summary>Apply any pending EF migrations. Called once on service start so a fresh stack
-    /// reaches a usable schema without a manual migration step (DoD: compose up reaches green).</summary>
+    /// reaches a usable schema without a manual migration step (DoD: compose up reaches green).
+    ///
+    /// The Event Subscriber and the projection-api share this DB and both migrate on start. EF's
+    /// migrations-history lock is released between individual migrations, so with more than one pending
+    /// migration two migrators can interleave and one re-applies a migration the other just did
+    /// ("column already exists"). Hold a Postgres session <c>pg_advisory_lock</c> across the whole
+    /// sequence so it runs exactly once; the second migrator then finds nothing pending.</summary>
     public static async Task MigrateProjectionAsync(this IServiceProvider services, CancellationToken ct = default)
     {
         await using var scope = services.CreateAsyncScope();
         var db = scope.ServiceProvider.GetRequiredService<ProjectionDbContext>();
-        await db.Database.MigrateAsync(ct);
+        var connection = db.Database.GetDbConnection();
+
+        await connection.OpenAsync(ct);
+        try
+        {
+            await ExecuteAsync(connection, $"SELECT pg_advisory_lock({MigrationAdvisoryLockKey})", ct);
+            try
+            {
+                await db.Database.MigrateAsync(ct);
+            }
+            finally
+            {
+                await ExecuteAsync(connection, $"SELECT pg_advisory_unlock({MigrationAdvisoryLockKey})", ct);
+            }
+        }
+        finally
+        {
+            await connection.CloseAsync();
+        }
+    }
+
+    private static async Task ExecuteAsync(System.Data.Common.DbConnection connection, string sql, CancellationToken ct)
+    {
+        await using var command = connection.CreateCommand();
+        command.CommandText = sql;
+        await command.ExecuteNonQueryAsync(ct);
     }
 }

services/projection-api/ProjectionApi.Api/Program.cs

@@ -10,8 +10,9 @@ builder.Services.AddProjectionReadModel(connectionString);
 
 var app = builder.Build();
 
-// Ensure the schema exists before serving reads. EF serialises concurrent migrators via the
-// migrations-history lock, so it is safe that the Event Subscriber migrates too.
+// Ensure the schema exists before serving reads. The Event Subscriber migrates this shared DB too;
+// MigrateProjectionAsync serialises concurrent migrators with a session advisory lock so the whole
+// migration sequence runs exactly once (see ServiceCollectionExtensions).
 await app.Services.MigrateProjectionAsync();
 
 app.MapGet("/health", () => "Healthy");