feat: Add DuckDB Aspire integration (hosting + client)

[lqdev]

Overview

Adds first-class Aspire integration for DuckDB using DuckDB.NET, following the embedded database pattern established by the SQLite integration.

DuckDB is a high-performance, in-process OLAP database — ideal for analytics, data science, and ETL workloads within Aspire applications.

New Packages

Package	NuGet Name	Description
Hosting	CommunityToolkit.Aspire.Hosting.DuckDB	AddDuckDB(), WithReadOnly(), dashboard integration
Client	CommunityToolkit.Aspire.DuckDB.NET.Data	AddDuckDBConnection(), health checks, DI registration

Usage

AppHost (Hosting)

var builder = DistributedApplication.CreateBuilder(args);

var duckdb = builder.AddDuckDB("analytics");

builder.AddProject<Projects.MyApi>("api")
    .WithReference(duckdb);

API Service (Client)

builder.AddDuckDBConnection("analytics");

// Then inject DuckDBConnection via DI
app.MapGet("/query", async (DuckDBConnection db) =>
{
    await db.OpenAsync();
    using var cmd = db.CreateCommand();
    cmd.CommandText = "SELECT * FROM my_table";
    // ...
});

Design Decisions

• Embedded database pattern (like SQLite) — no container, file-based resource, appears in dashboard as Running
• DuckDB creates its own database file on first connection (unlike SQLite, DuckDB cannot open an empty pre-created file)
• Uses DuckDB.NET.Data.Full which bundles native DuckDB libraries for all platforms (win/linux/mac, x64/arm64)
• Custom inline health check (SELECT 1) since no community AspNetCore.HealthChecks.DuckDB package exists
• No EF Core integration — no official DuckDB EF Core provider exists, and DuckDB's OLAP nature is a poor fit for EF's change-tracking model
• WithReadOnly() appends Access Mode=ReadOnly to connection string for read-only scenarios

What's Included

Source (src/)

• CommunityToolkit.Aspire.Hosting.DuckDB — DuckDBResource, DuckDBResourceBuilderExtensions
• CommunityToolkit.Aspire.DuckDB.NET.Data — AspireDuckDBExtensions, DuckDBConnectionSettings

Examples (examples/duckdb/)

• AppHost, API (analytics endpoints with seed data), ServiceDefaults

Tests (tests/)

• Hosting: 16 tests — null guards, resource state, paths, connection strings, read-only mode, integration tests
• Client: 31 tests — connection registration, configuration binding, conformance tests

CI

• Updated tests.yaml with Hosting.DuckDB.Tests and DuckDB.NET.Data.Tests

Test Results

• Hosting: 16/16 passed (unit + integration)
• Client: 13/13 passed, 18 skipped (conformance tests for unsupported features like metrics/tracing)

[github-actions]

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/CommunityToolkit/Aspire/main/eng/scripts/dogfood-pr.sh | bash -s -- 1245

Or

• Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/CommunityToolkit/Aspire/main/eng/scripts/dogfood-pr.ps1) } 1245"

[lqdev]

cc: @Giorgi @HowardvanRooijen

[Copilot]

Pull request overview

Adds a new DuckDB integration to the Aspire Community Toolkit, providing both an AppHost (hosting) resource and a client library (DuckDB.NET.Data) registration pattern aligned with the existing embedded DB (SQLite) approach.

Changes:

• Introduces AddDuckDB() hosting resource + WithReadOnly() support with dashboard state integration.
• Adds AddDuckDBConnection() / AddKeyedDuckDBConnection() client registration with an inline DuckDB health check.
• Adds DuckDB example AppHost/API projects plus new hosting/client test projects and wires them into the solution and CI workflow.

Reviewed changes

Copilot reviewed 27 out of 27 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/CommunityToolkit.Aspire.Hosting.DuckDB.Tests/CommunityToolkit.Aspire.Hosting.DuckDB.Tests.csproj	Adds hosting DuckDB test project references (src + example AppHost + testing helpers).
tests/CommunityToolkit.Aspire.Hosting.DuckDB.Tests/AppHostTests.cs	Adds integration tests validating resource health, connection string shape, and example API endpoints.
tests/CommunityToolkit.Aspire.Hosting.DuckDB.Tests/AddDuckDBTests.cs	Adds unit tests for hosting resource defaults, manifest behavior, and read-only mode connection string.
tests/CommunityToolkit.Aspire.DuckDB.NET.Data.Tests/DuckDBConnectionTests.cs	Adds client DI registration tests (keyed/non-keyed) using configuration connection strings.
tests/CommunityToolkit.Aspire.DuckDB.NET.Data.Tests/ConformanceTests.cs	Adds Aspire conformance-test harness coverage for the DuckDB client integration.
tests/CommunityToolkit.Aspire.DuckDB.NET.Data.Tests/ConfigurationTests.cs	Adds client configuration tests (Aspire section + missing connection string behavior).
tests/CommunityToolkit.Aspire.DuckDB.NET.Data.Tests/CommunityToolkit.Aspire.DuckDB.NET.Data.Tests.csproj	Adds DuckDB client test project references.
src/CommunityToolkit.Aspire.Hosting.DuckDB/README.md	Documents hosting package usage (AddDuckDB, WithReadOnly).
src/CommunityToolkit.Aspire.Hosting.DuckDB/DuckDBResourceBuilderExtensions.cs	Implements AddDuckDB resource creation + initial snapshot and pre-start directory/permission setup.
src/CommunityToolkit.Aspire.Hosting.DuckDB/DuckDBResource.cs	Defines DuckDB resource + connection string expression and connection properties.
src/CommunityToolkit.Aspire.Hosting.DuckDB/CommunityToolkit.Aspire.Hosting.DuckDB.csproj	Adds hosting package project definition and test visibility.
src/CommunityToolkit.Aspire.DuckDB.NET.Data/README.md	Documents client package usage (DI registration + injecting DuckDBConnection).
src/CommunityToolkit.Aspire.DuckDB.NET.Data/DuckDBConnectionSettings.cs	Adds client settings model (connection string + health check toggle).
src/CommunityToolkit.Aspire.DuckDB.NET.Data/CommunityToolkit.Aspire.DuckDB.NET.Data.csproj	Adds DuckDB.NET.Data.Full dependency + shared validation/healthcheck utilities linkage.
src/CommunityToolkit.Aspire.DuckDB.NET.Data/AspireDuckDBExtensions.cs	Implements DI registration, config binding precedence, and inline DuckDB health check.
examples/duckdb/CommunityToolkit.Aspire.DuckDB.ServiceDefaults/Extensions.cs	Adds example service-defaults wiring (OTel, health checks, service discovery).
examples/duckdb/CommunityToolkit.Aspire.DuckDB.ServiceDefaults/CommunityToolkit.Aspire.DuckDB.ServiceDefaults.csproj	Adds example ServiceDefaults project dependencies.
examples/duckdb/CommunityToolkit.Aspire.DuckDB.AppHost/Properties/launchSettings.json	Adds example AppHost launch profiles.
examples/duckdb/CommunityToolkit.Aspire.DuckDB.AppHost/Program.cs	Adds example AppHost wiring DuckDB resource to the API project reference.
examples/duckdb/CommunityToolkit.Aspire.DuckDB.AppHost/CommunityToolkit.Aspire.DuckDB.AppHost.csproj	Adds example DuckDB AppHost project setup and references.
examples/duckdb/CommunityToolkit.Aspire.DuckDB.AppHost/appsettings.json	Adds example AppHost logging configuration.
examples/duckdb/CommunityToolkit.Aspire.DuckDB.Api/Properties/launchSettings.json	Adds example API launch profiles.
examples/duckdb/CommunityToolkit.Aspire.DuckDB.Api/Program.cs	Adds example API endpoints executing DuckDB queries plus seeding logic.
examples/duckdb/CommunityToolkit.Aspire.DuckDB.Api/CommunityToolkit.Aspire.DuckDB.Api.csproj	Adds example API project references to client + ServiceDefaults.
Directory.Packages.props	Centralizes DuckDB.NET.Data.Full package version.
CommunityToolkit.Aspire.slnx	Adds new DuckDB src/test/example projects to the solution.
.github/workflows/tests.yaml	Adds the new hosting/client DuckDB test projects to CI test matrix.

[lqdev]

This PR was automatically closed without being reviewed. Please reopen.

cc: @aaronpowell

[aaronpowell]

Need to bump the apphost SDK to 13.3.0 to correct the CI issues.

[lqdev]

Thanks @aaronpowell — confirmed and fixed in ee3c023.

Root cause (verified from the failing CI log): after the recent merge with main brought in Aspire.Hosting.Testing 13.3.0, the transitive constraint Aspire.Hosting.Testing 13.3.0 → Aspire.Hosting.AppHost (>= 13.3.0) clashed with the DuckDB AppHost example still pinned at Aspire.AppHost.Sdk/13.2.0, producing NU1605 (package downgrade) on the Windows restore. Bumping the example SDK to 13.3.0 resolves it.

Also done in this push:

• Merged latest upstream/main into the branch so CI runs against the actual to-be-merged state (9 new commits beyond our previous merge; none touched DuckDB).
• Re-ran locally: 16/16 hosting tests pass, 13/13 client tests pass (18 conformance skipped as designed).

Out of scope (FYI): the other red windows-latest jobs in this PR's CI (Hosting.Bun.Tests, Hosting.Ollama.Tests, MassTransit.RabbitMQ.Tests) all fail with "failed to connect to the docker API at npipe:////./pipe/docker_engine" — a pre-existing Docker-on-Windows runner environment issue unrelated to this PR. Happy to file a separate issue if useful.