How to make embedded-postgres use persistent data across runs?

Set the DataPath to a directory outside RuntimePath, as RuntimePath is erased on each Start(). The README explains this to avoid data loss and enable reuse.

embedded-postgres vs Docker for PostgreSQL testing in Go?

embedded-postgres is lighter with no Docker daemon, ideal for quick integration tests, while Docker offers better isolation and version flexibility. Choose based on setup complexity and resource needs.

Does embedded-postgres work on Apple Silicon Macs without Rosetta?

Yes, but only with version 18.3.0 or higher, which includes universal binaries. Older versions require Rosetta 2, as stated in the README's installation notes.

How to configure custom PostgreSQL parameters like max_connections?

Use the StartParameters map in the configuration to override defaults, as shown in the example with max_connections set to 200, allowing tailored database settings.

What happens if the Maven repository is down during binary download?

The library will fail to start unless binaries are already cached in CachePath. The README's reliance on BinaryRepositoryURL means offline setups require pre-downloaded binaries.

Can I test with multiple PostgreSQL versions in the same Go project?

Yes, but you must manage separate RuntimePath and BinaryPath directories per version to avoid conflicts, as the library doesn't handle concurrent version checks automatically.

Open-Awesome

embedded-postgres

MITGov2.0.1

A Go library that runs a real PostgreSQL database locally as part of your application or tests.

GitHub

1.3k stars105 forks0 contributors

What is embedded-postgres?

embedded-postgres is a Go library that allows you to run a real PostgreSQL database locally as part of your Go application or test suite. It solves the problem of needing a realistic database environment for testing without requiring external PostgreSQL installations or relying on less accurate in-memory alternatives.

Target Audience

Go developers who need to test applications with PostgreSQL integration, particularly those writing integration tests or requiring a local database instance for development.

Value Proposition

Developers choose embedded-postgres because it provides a real PostgreSQL instance with zero external dependencies, offering higher testing confidence than in-memory alternatives while being easy to configure and integrate into Go projects.

Overview

Run a real Postgres database locally on Linux, OSX or Windows as part of another Go application or test

Use Cases

Best For

Integration testing Go applications with PostgreSQL
Running local PostgreSQL instances for development without system installation
Testing database migrations and queries with a real PostgreSQL engine
CI/CD pipelines requiring isolated PostgreSQL instances
Educational projects demonstrating PostgreSQL usage in Go
Prototyping applications that depend on PostgreSQL features

Not Ideal For

Projects requiring non-standard PostgreSQL configurations beyond the library's default overrides
Environments with no internet access, as it depends on downloading binaries from Maven repositories
Teams preferring in-memory databases for ultra-fast, low-resource unit tests over integration testing
Applications needing to run multiple PostgreSQL versions concurrently in the same test suite without manual path management

Pros & Cons

Pros

Real PostgreSQL Engine

Uses an actual PostgreSQL instance, not an in-memory simulation, providing higher testing confidence for queries, migrations, and features.

Zero External Dependencies

Only requires Go; no separate PostgreSQL installation is needed, simplifying setup and CI/CD pipelines as highlighted in the README.

Cross-Platform Compatibility

Works on Linux, macOS (with native Apple Silicon support in version 18.3.0+), and Windows, ensuring broad usability across development environments.

Automatic Binary Management

Downloads and caches PostgreSQL binaries automatically from Maven, reducing manual setup, though it relies on external repositories.

Cons

Binary Download Dependency

Requires internet access for initial binary downloads from Maven, which can fail in offline or restricted network environments, breaking test setups.

Limited Version Control

If binaries are pre-cached, no version check is performed, risking version mismatches without clear errors, as noted in the README's BinaryPath handling.

Apple Silicon Quirks

Versions before 18.3.0 require Rosetta 2 on Apple Silicon Macs, adding complexity and potential performance overhead, which the README explicitly warns about.

Frequently Asked Questions

Related Projects

Testify

A toolkit with common assertions and mocks that plays nicely with the standard library

Stars26,233

Forks1,871

Last commit6 days ago

Keploy

Open-source platform for creating safe, isolated production sandboxes for API, integration, and E2E testing.

Stars18,752

Forks2,429

Last commit6 hours ago

GoConvey

Go testing in the browser. Integrates with `go test`. Write behavioral tests in Go.

Stars8,399

Forks558

Last commit2 years ago

testcontainers-go

Testcontainers for Go is a Go package that makes it simple to create and clean up container-based dependencies for automated integration/smoke tests. The clean, easy-to-use API enables developers to programmatically define containers that should be run as part of a test and clean up those resources when the test is done.

Stars5,017

Forks654