Postgres.Embedded 1.0.0

Postgres.Embedded

Run a real PostgreSQL database locally on Linux, macOS, or Windows as part of another .NET application or test.

This library provides a higher level of confidence than using any in-memory alternative when testing. It requires no other external dependencies outside of the .NET build ecosystem.

Heavily inspired by Go project fergusstrange/embedded-postgres and Java projects zonkyio/embedded-postgres and opentable/otj-pg-embedded.

Features

• ✅ Fluent Builder API - Modern, chainable configuration
• ✅ Synchronous-first design - Blocking methods aligned with Go version
• ✅ Auto-restart on second start - User-friendly lifecycle management
• ✅ Global port registry - Prevents concurrent conflicts within process
• ✅ WeakReference cleanup - Automatic garbage collection of failed instances
• ✅ Cross-platform support - Windows, Linux, macOS (x64 & ARM64)
• ✅ Multiple PostgreSQL versions - From 9.6 to 18.3
• ✅ Npgsql integration - Seamless connection with Npgsql driver

Installation

dotnet add package Postgres.Embedded

Quick Start

using Postgres.Embedded;

// Basic usage with defaults
using var postgres = new EmbeddedPostgresBuilder()
    .WithPort(5432)
    .Build();

postgres.Start();

var connectionString = postgres.GetConnectionString();

// Use Npgsql to connect
using var conn = new NpgsqlConnection(connectionString);
conn.Open();

using var cmd = new NpgsqlCommand("SELECT version()", conn);
var version = cmd.ExecuteScalar();

Console.WriteLine($"PostgreSQL version: {version}");

postgres.Stop();

Configuration

Custom Configuration Example

using var loggerFactory = LoggerFactory.Create(builder => 
{
    builder.AddConsole().SetMinimumLevel(LogLevel.Debug);
});

var logger = loggerFactory.CreateLogger<EmbeddedPostgres>();

using var postgres = new EmbeddedPostgresBuilder()
    .WithVersion(PostgresVersion.V16)
    .WithPort(5433)
    .WithUsername("myuser")
    .WithPassword("mypassword")
    .WithDatabase("mydb")
    .WithLocale("en_US.UTF-8")
    .WithEncoding("UTF8")
    .WithStartTimeout(TimeSpan.FromSeconds(30))
    .WithStartParameters(new Dictionary<string, string>
    {
        ["max_connections"] = "200",
        ["shared_buffers"] = "256MB"
    })
    .WithLogger(logger)
    .Build();

postgres.Start();

Supported PostgreSQL Versions

Platform Support

Note: PostgreSQL versions before 14.2 on macOS ARM64 require Rosetta 2 due to upstream binaries being x86_64-only. Version 14.2+ includes universal binaries that work natively on Apple Silicon.

Concurrent Control

The library uses a global port registry to prevent concurrent conflicts:

• ✅ Prevents multiple instances on the same port within a process
• ✅ Auto-restarts when calling Start() twice on the same instance
• ✅ Throws PortConflictException if port is occupied by another instance
• ✅ Automatic cleanup of failed instances using WeakReference

Exception Handling

try
{
    postgres.Start();
}
catch (PortConflictException ex)
{
    Console.WriteLine($"Port {ex.Port} is already in use");
    // Choose a different port or stop the conflicting instance
}
catch (ProcessStartException ex)
{
    Console.WriteLine($"Failed to start PostgreSQL: {ex.Message}");
}
catch (EmbeddedPostgresException ex)
{
    Console.WriteLine($"General error: {ex.Message}");
}

Usage in Tests

xUnit Example

public class DatabaseTests : IDisposable
{
    private readonly EmbeddedPostgres _postgres;
    
    public DatabaseTests()
    {
        _postgres = new EmbeddedPostgresBuilder()
            .WithPort(5433)
            .WithDatabase("testdb")
            .Build();
        
        _postgres.Start();
    }
    
    [Fact]
    public void Test_InsertAndQuery()
    {
        var connectionString = _postgres.GetConnectionString();
        
        using var conn = new NpgsqlConnection(connectionString);
        conn.Open();
        
        conn.Execute("CREATE TABLE users (id SERIAL, name TEXT)");
        conn.Execute("INSERT INTO users (name) VALUES ('Alice')");
        
        var users = conn.Query<User>("SELECT * FROM users").ToList();
        
        Assert.Single(users);
        Assert.Equal("Alice", users[0].Name);
    }
    
    public void Dispose()
    {
        _postgres?.Stop();
        _postgres?.Dispose();
    }
}

Multiple Instances

var instance1 = new EmbeddedPostgresBuilder()
    .WithPort(5432)
    .WithDatabase("db1")
    .Build();

var instance2 = new EmbeddedPostgresBuilder()
    .WithPort(5433)
    .WithDatabase("db2")
    .Build();

instance1.Start();
instance2.Start();

// Run two databases simultaneously

instance1.Stop();
instance2.Stop();

Credits

• zonkyio/embedded-postgres-binaries - Precompiled PostgreSQL binaries
• fergusstrange/embedded-postgres - Original Go implementation

License

GNU Affero General Public License v3.0 (AGPL-3.0) - See LICENSE file for details.

This is a strong copyleft license that ensures:

• ✅ Free to use, modify, and distribute
• ✅ Modifications must be shared under the same license
• ✅ Network use (SaaS) requires providing source code to users
• ✅ Commercial use allowed but requires source code availability

For more information, see: https://www.gnu.org/licenses/agpl-3.0.html

Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues at: https://github.com/DotNet-AGPL/Postgres.Embedded/issues

Roadmap

• Docker container support
• Entity Framework Core integration
• Test framework extensions (xUnit, NUnit)
• Connection pool management
• Async API improvements

Project Status

Repository: https://github.com/DotNet-AGPL/Postgres.Embedded
License: AGPL-3.0
Status: Active Development