Binary Management

embedded-postgres automates the process of fetching and managing PostgreSQL binaries, so you don't have to install them manually. Here’s how it works.

Downloading Binaries

By default, the library downloads pre-compiled PostgreSQL binaries from Maven Central. The download URL is constructed based on your operating system, CPU architecture, and the chosen PostgreSQL version.

For example, for PostgreSQL 16.9.0 on macOS with an M1/M2 chip, it might fetch from a URL similar to this:

https://repo1.maven.org/maven2/io/zonky/test/postgres/embedded-postgres-binaries-darwin-arm64v8/16.9.0/embedded-postgres-binaries-darwin-arm64v8-16.9.0.jar

The downloaded file is a .jar archive which contains a compressed .txz file with the actual binaries.

Using a Maven Proxy

If your network requires you to use a proxy or a private Maven repository, you can override the default URL with the BinaryRepositoryURL configuration:

config := DefaultConfig().
    BinaryRepositoryURL("https://my-internal-artifactory/maven2")

Caching

To avoid re-downloading the binaries on every run, they are cached locally.

  • Default Cache Location: ~/.embedded-postgres-go

When Start() is called, it first checks this cache for the required binary archive. If found, it uses the cached file; otherwise, it proceeds with the download.

You can specify a custom cache directory using CachePath:

// Useful for CI environments where the home directory may not be writable.
config := DefaultConfig().CachePath("/tmp/pg_cache")

Using Pre-fetched Binaries

In environments without internet access or for faster setup, you can bypass the download and cache mechanism entirely by providing a path to already-extracted binaries using BinariesPath.

  1. Prepare the binaries: First, run embedded-postgres once on a machine with internet to download and extract the binaries. The extracted folder will be in the RuntimePath. Copy this folder to a location in your project or CI environment.

  2. Configure BinariesPath: Point the configuration to this directory.

// The library will use the binaries from this directory directly.
config := DefaultConfig().
    BinariesPath("./pre-fetched-postgres-16")

postgres := embeddedpostgres.NewDatabase(config)
// This Start() call will not perform any network requests.
err := postgres.Start()

Platform and Version Strategy

The library contains logic to select the correct binary for a wide range of platforms. It automatically detects the operating system (Linux, Windows, macOS) and architecture (amd64, arm64). It also includes special handling for:

  • Apple Silicon (arm64): It correctly selects arm64v8 binaries for supported PostgreSQL versions (14.2+). For older versions, it falls back to amd64 binaries, which can run under Rosetta 2.
  • Linux ARM: It detects arm32v6, arm32v7, and arm64v8 variants.
  • Alpine Linux: It can detect if it's running inside an Alpine container and appends -alpine to the architecture to download the correct musl-linked binaries.

This intelligent selection is handled by the internal VersionStrategy and ensures the library works out-of-the-box in most environments.