Skip to content

DuckDB

DuckDB is a fast, in-process analytical database. It runs embedded within a host process and stores data in a single database file.

Add the following dependency to your project file:

NuGet
1
dotnet add package Testcontainers.DuckDb

You can start a DuckDB container instance from any .NET application. This example uses xUnit.net's IAsyncLifetime interface to manage the lifecycle of the container. The container is started in the InitializeAsync method before the test method runs, ensuring that the environment is ready for testing. After the test completes, the container is removed in the DisposeAsync method.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
public sealed class DuckDbContainerExample : IAsyncLifetime
{
    private readonly DuckDbContainer _duckDbContainer = new DuckDbBuilder(TestSession.GetImageFromDockerfile()).Build();

    public async ValueTask InitializeAsync()
    {
        await _duckDbContainer.StartAsync(TestContext.Current.CancellationToken)
            .ConfigureAwait(false);
    }

    public async ValueTask DisposeAsync()
    {
        await _duckDbContainer.DisposeAsync()
            .ConfigureAwait(false);
    }
}

Execute a SQL script:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
[Fact]
[Trait(nameof(DockerCli.DockerPlatform), nameof(DockerCli.DockerPlatform.Linux))]
public async Task ExecScriptReturnsSuccessful()
{
    // Given
    const string scriptContent = "SELECT 1;";

    // When
    var execResult = await _duckDbContainer.ExecScriptAsync(scriptContent, TestContext.Current.CancellationToken)
        .ConfigureAwait(true);

    // Then
    Assert.True(0L.Equals(execResult.ExitCode), execResult.Stderr);
    Assert.Empty(execResult.Stderr);
}

Note

DuckDB is an embedded database — the duckdb/duckdb image ships the DuckDB CLI, not a database server. The container keeps an in-memory DuckDB CLI process running to stay alive, and ExecScriptAsync(string) runs SQL scripts against the configured database file (default: /database.duckdb, created on first use). The database state persists across script executions. Use WithDatabase(string) to configure a different database file path, and GetDatabaseFilePath() together with ReadFileAsync(string) to copy the database file to the test host.

The test example uses the following NuGet dependencies:

1
2
3
4
<PackageReference Include="Microsoft.NET.Test.Sdk"/>
<PackageReference Include="coverlet.collector"/>
<PackageReference Include="xunit.runner.visualstudio"/>
<PackageReference Include="xunit.v3"/>

To execute the tests, use the command dotnet test from a terminal.

Tip

For the complete source code of this example and additional information, please refer to our test projects.