Overview

embedded-postgres is a Go library that allows you to run a real, temporary PostgreSQL database locally on Linux, macOS, or Windows as part of another Go application or test suite. This provides a high-fidelity testing environment without requiring external dependencies like Docker or a pre-installed PostgreSQL instance.

It is heavily inspired by Java projects like zonkyio/embedded-postgres and opentable/otj-pg-embedded, and it relies on zonkyio/embedded-postgres-binaries to fetch pre-compiled PostgreSQL binaries from Maven Central.

Why Use embedded-postgres?

• High-Fidelity Testing: Test your application against a real PostgreSQL database, ensuring that your queries and database logic behave exactly as they would in production.
• Zero External Dependencies: No need for users or CI/CD systems to have PostgreSQL or Docker installed. The required binaries are downloaded automatically.
• Hermetic & Parallel Tests: Each test suite can spin up its own isolated PostgreSQL instance on a different port, allowing tests to run in parallel without interfering with each other.
• Simple API: The library provides a clean and straightforward API to start, stop, and configure the database instance.

Key Features

• Cross-Platform: Works on Linux, macOS (Intel & Apple Silicon), and Windows.
• Automatic Binary Fetching: Downloads and caches the required PostgreSQL binaries for your specific OS and architecture.
• Configurable: Easily configure the PostgreSQL version, port, database name, user, password, and other startup parameters.
• Extensible: Supports custom log outputs, allowing integration with structured logging libraries like zap.