Get started with the DuckDB integration

⭐ Community Toolkit

DuckDB is an in-process analytical database for SQL queries over local data, including Parquet and CSV files. The Aspire Community Toolkit provides a hosting resource that describes a database file and a .NET integration that registers an ADO.NET connection.

Why use DuckDB with Aspire

• Describe the database directory and filename once in the AppHost.
• Pass the same connection string to each app that references the resource.
• Configure a read-only connection for an existing analytical dataset.
• Register scoped or keyed DuckDBConnection services with a database health check.

How the pieces fit together

The 📦 CommunityToolkit.Aspire.Hosting.DuckDB package models a file resource. It starts no database server or container. The consuming process loads DuckDB and opens the file.

The 📦 CommunityToolkit.Aspire.DuckDB.NET.Data package registers DuckDB.NET.Data.DuckDBConnection in a .NET app. It reads the connection string supplied by the AppHost.

flowchart LR
    AppHost[AppHost file resource] -->|Connection string| App[Consuming process]
    App --> Engine[Embedded DuckDB engine]
    Engine --> File[Database file]

Attention

A resource reference passes a file path, not the file itself. The consuming process must have access to that path. Plan file mounts separately for containerized apps. Follow DuckDB concurrency guidance before opening the same file from multiple processes.

Prerequisites

• Complete the Aspire prerequisites.
• Create an AppHost and a consuming .NET app. The examples use an ASP.NET Core project named Api, referenced by the AppHost.
• Select a writable database directory, or provide an existing file for read-only access.

No container runtime is needed for the DuckDB resource itself.

Set up the integration

1. Install the hosting package, add a resource named analytics, and reference it from the consuming app. See DuckDB hosting integration for AppHost examples and file-lifecycle details.

2. Install the client package in the .NET app and register AddDuckDBConnection("analytics"). Open the injected connection before executing SQL. See Connect with the DuckDB integration.

3. Run aspire run and call the consuming app. DuckDB creates a new database file when the first writable connection opens.

See also

• DuckDB documentation
• DuckDB.NET
• DuckDB hosting integration
• Connect with the DuckDB integration