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
.
-
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 theRuntimePath
. Copy this folder to a location in your project or CI environment. -
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 toamd64
binaries, which can run under Rosetta 2. - Linux ARM: It detects
arm32v6
,arm32v7
, andarm64v8
variants. - Alpine Linux: It can detect if it's running inside an Alpine container and appends
-alpine
to the architecture to download the correctmusl
-linked binaries.
This intelligent selection is handled by the internal VersionStrategy
and ensures the library works out-of-the-box in most environments.