PostgreSQL

PostgreSQL is a powerful, open-source relational database management system (RDBMS) used to store, manage, and retrieve structured data.

Add the following dependency to your project file:

dotnet add package Testcontainers.PostgreSql

You can start a PostgreSQL container instance from any .NET application. To create and start a container instance with the default configuration, use the module-specific builder as shown below:

Start a PostgreSQL Container

var postgreSqlContainer = new PostgreSqlBuilder("postgres:15.1").Build();
await postgreSqlContainer.StartAsync();

The following example utilizes the xUnit.net module to reduce overhead by automatically managing the lifecycle of the dependent container instance. It creates and starts the container using the module-specific builder and injects it as a shared class fixture into the test class.

Usage Example

[Fact]
[Trait(nameof(DockerCli.DockerPlatform), nameof(DockerCli.DockerPlatform.Linux))]
public void ConnectionStateReturnsOpen()
{
    // Given
    using DbConnection connection = fixture.CreateConnection();

    // When
    connection.Open();

    // Then
    Assert.Equal(ConnectionState.Open, connection.State);
    Assert.Equal(fixture.Container.GetConnectionString(), fixture.Container.GetConnectionString(ConnectionMode.Host));
}

[Fact]
[Trait(nameof(DockerCli.DockerPlatform), nameof(DockerCli.DockerPlatform.Linux))]
public async Task ExecScriptReturnsSuccessful()
{
    // Given
    const string scriptContent = "SELECT 1;";

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

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

SSL

Use WithSsl to enable TLS and map the server certificates. Configure the client connection string with SslMode and (for validation) the CA certificate.

Note

When SSL is enabled, Testcontainers does not set the SSL mode for the connection string. You will need to choose the SslMode and configure it yourself.

Note

When SSL is enabled, Testcontainers overrides the entrypoint to copy the certificates for the user that runs PostgreSQL and then runs docker-entrypoint.sh, not an entrypoint defined by a custom image. If you set an entrypoint with WithEntrypoint, Testcontainers does not override it. You will need to copy the certificates from /etc/ssl/postgresql to /var/run/postgresql/ssl yourself and make sure only the PostgreSQL user can access them.

protected override PostgreSqlBuilder Configure()
    => base.Configure().WithSsl(ServerCertificateFilePath, ServerCertificateKeyFilePath, CaCertificateFilePath);

var connectionStringBuilder = new NpgsqlConnectionStringBuilder(base.ConnectionString);
connectionStringBuilder.SslMode = SslMode.VerifyCA;
connectionStringBuilder.RootCertificate = CaCertificateFilePath;
return connectionStringBuilder.ConnectionString;

VerifyFull and SANs

SslMode=VerifyFull additionally validates that the host in the connection string matches a subject alternative name (SAN) of the server certificate. Testcontainers usually resolves the container host to the IP address 127.0.0.1. The certificate must include a matching IP SAN, for example IP:127.0.0.1:

var connectionStringBuilder = new NpgsqlConnectionStringBuilder(base.ConnectionString);
connectionStringBuilder.SslMode = SslMode.VerifyFull;
connectionStringBuilder.RootCertificate = CaCertificateFilePath;
return connectionStringBuilder.ConnectionString;

The test example uses the following NuGet dependencies:

Package References

<PackageReference Include="Microsoft.NET.Test.Sdk"/>
<PackageReference Include="coverlet.collector"/>
<PackageReference Include="xunit.runner.visualstudio"/>
<PackageReference Include="xunit.v3"/>
<PackageReference Include="Npgsql"/>

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.