embedded-postgres

Understanding the relationship between RuntimePath and DataPath is critical for data persistence:

• RuntimePath: This directory is erased and recreated at every Start(). It is not suitable for persistent data.
• DataPath: To ensure data persists between runs, set DataPath to a directory located outside of the RuntimePath.
• Binary Management: Postgres binaries are downloaded to BinariesPath. If the directory already exists, the library uses whatever version is present without performing a version check. To run multiple Postgres versions in different tests, ensure BinariesPath is a subdirectory of RuntimePath.

Add the latest release of embedded-postgres to your Go project using the following command:

go get -u github.com/fergusstrange/embedded-postgres

The library uses a default cache location if no specific directory is provided.

1. If cacheDirectory is empty, it defaults to .embedded-postgres-go in the user's home directory.
2. It constructs the filename using the pattern: embedded-postgres-binaries-{operatingSystem}-{architecture}-{version}.txz.
3. It uses a VersionStrategy to resolve the operating system, architecture, and version string.

While defaultCacheLocator is an internal implementation detail, you can achieve similar behavior by providing a CacheLocator that follows this path construction logic.

The Config struct manages the runtime configuration for the Postgres process. You should initialize a configuration using DefaultConfig() and then use its builder methods to customize settings.

Key configuration areas include:

• Connection details: Port, Database, Username, and Password.
• Filesystem paths: RuntimePath (extracted runtime), CachePath (binary archives, defaults to ~/.go-embedded-postgres), DataPath (Postgres data directory), and BinariesPath (pre-downloaded binaries).
• Postgres settings: Version, Locale, Encoding, and StartParameters (passed via -c to override postgres.conf).
• Lifecycle: StartTimeout (max time to wait for startup) and Logger (output destination).

You can retrieve a connection string for your application using GetConnectionURL().

If you are using Apple Silicon (M1/M2/M3 chips):

• Postgres versions < 18.3.0: Require Rosetta 2 because upstream binaries are x86_64-only.
• Postgres versions 18.3.0+: Include universal binaries that work natively on Apple Silicon.

To start a single Postgres instance using default settings, use embeddedpostgres.NewDatabase() and call Start(). Remember to call Stop() to release the child Postgres process and prevent blocking.

postgres := embeddedpostgres.NewDatabase()
err := postgres.Start()

// Do test logic

err := postgres.Stop()

You can customize the Postgres instance by using NewDatabase with a configuration object generated from DefaultConfig(). This allows you to override credentials, version, paths, and connection parameters.

logger := &bytes.Buffer{}
postgres := NewDatabase(DefaultConfig().
Username("beer").
Password("wine").
Database("gin").
Version(V12).
RuntimePath("/tmp").
BinaryRepositoryURL("https://repo.local/central.proxy").
Port(9876).
StartTimeout(45 * time.Second).
StartParameters(map[string]string{"max_connections": "200"}).
Logger(logger))
err := postgres.Start()

// Do test logic

err := postgres.Stop()

The RemoteFetchStrategy is a function type used to define how Postgres binaries are retrieved and made available for use. By implementing this type, you can control the source of the binaries (e.g., a local mirror, a specific S3 bucket, or a custom URL structure) instead of relying on the default behavior.

To use it, define a function that matches the signature func() error and provide it to the configuration that requires a fetching strategy.

The Start() method attempts to download/extract the required Postgres binaries, initialize the data directory, and launch the Postgres process.

If an error occurs during startup, Start() will attempt to call Stop() to ensure no orphaned sub-processes are left running. It also performs a health check to ensure the database is ready for connections.

Errors returned:

• ErrServerAlreadyStarted: If the server is already running.
• Various errors related to port availability, binary downloading, or database initialization.

The Stop() method gracefully shuts down the running Postgres process.

Errors returned:

• ErrServerNotStarted: If the server is not currently running.

Use the StartParameters(parameters map[string]string) method to pass custom configuration settings to the Postgres process at startup. These parameters are passed via the -c flag. This allows you to override default values in postgres.conf.

Example: To set max_connections to 100:

config.StartParameters(map[string]string{
    "max_connections": "100",
})