microsoft / microsoft/aspire

EF migration bundle docs say WaitFor(db) waits for database health, but Docker Compose publish uses service_started

Open
#18,334 2 comments 0 reactions 0 assignees View on GitHub
area-integrations triage:bot-seen
Dominant language
C#
Stars
6.3k
Forks
991
Avg merge
2d 15h
Merged PRs (30d)
196

Description

## Summary

The EF Core migration bundle documentation says that, when using `PublishAsMigrationBundle(publishContainer: true)`, `.WaitFor(db)` ensures the database is healthy before the migration container starts.

However, when publishing to Docker Compose, the generated compose file uses `depends_on.condition: service_started` for the database dependency, and the PostgreSQL service does not get a generated Docker Compose `healthcheck`. That means the migration container can start before PostgreSQL is ready to accept connections.

## Documentation involved

EF Core migrations docs:

https://aspire.dev/integrations/databases/efcore/migrations/

The documented pattern is:

```csharp
var db = builder.AddPostgres("pg").AddDatabase("appdb");
var api = builder.AddProject("api").WithReference(db);

var apiMigrations = api.AddEFMigrations("api-migrations")
.WithReference(db)
.WaitFor(db)
.PublishAsMigrationBundle(publishContainer: true);
```

The docs state that `.WithReference(db)` provides the connection string source, and `.WaitFor(db)` ensures the database is healthy before the migration container starts.

The Docker Compose reference maps `.WaitFor(db)` to `condition: service_started`:

https://aspire.dev/app-host/docker-compose-to-apphost-reference/#dependencies-and-ordering

## Repro

Use an AppHost shape like this:

```csharp
builder.AddDockerComposeEnvironment("compose");

var postgres = builder.AddPostgres("postgres");
var db = postgres.AddDatabase("appdb");

var api = builder.AddProject("api")
.WithReference(db);

api.AddEFMigrations("api-migrations")
.WithReference(db)
.WaitFor(db)
.PublishAsMigrationBundle(publishContainer: true)
.PublishAsDockerComposeService((_, service) => service.Restart = "no");
```

Then run:

```powershell
aspire publish --apphost path\to\AppHost.csproj --output-path .\aspire-output --non-interactive --nologo
```

## Actual result

The generated Docker Compose output uses `service_started` for the database dependency:

```yaml
api-migrations:
depends_on:
postgres:
condition: "service_started"
```

The generated `postgres` service does not include a Docker Compose `healthcheck`.

## Expected result

Given the EF migration bundle documentation, I expected one of these outcomes:

1. Docker Compose publish translates the database readiness requirement into a generated healthcheck plus `depends_on.condition: service_healthy`, at least for database integrations that already have built-in health checks in Aspire local orchestration.
2. Or the EF migration bundle documentation clarifies that Docker Compose publish only emits `service_started`, and users need to manually customize the Compose healthcheck and dependency condition if they need database readiness before a migration container starts.

## Workaround

For PostgreSQL, this can be worked around by explicitly adding a Compose healthcheck and overriding the migration service dependency:

```csharp
postgres.PublishAsDockerComposeService((_, service) => {
service.Healthcheck = new Healthcheck {
Test = ["CMD-SHELL", "pg_isready -U \"$$POSTGRES_USER\""]
};
});

apiMigrations.PublishAsDockerComposeService((_, service) => {
service.Restart = "no";
service.DependsOn["postgres"] = new ServiceDependency {
Condition = "service_healthy"
};
});
```

## Version info

Observed with:

- Aspire CLI: `13.4.5+73114e86c64aeb9f3f3c7da8e37df1ae4281b27e`
- `Aspire.Hosting.Docker`: `13.4.5`
- `Aspire.Hosting.PostgreSQL`: `13.4.5`
- `Aspire.Hosting.EntityFrameworkCore`: `13.4.5-preview.1.26316.12`
- .NET SDK: `11.0.100-preview.5.26302.115`

I searched existing issues for combinations of `PublishAsMigrationBundle`, `WaitFor`, `Docker Compose`, `service_started`, and `service_healthy`, and did not find a matching issue.

## Note

This issue body was drafted with assistance from OpenAI Codex and reviewed before submission.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.