chris-rock/embedded-postgres

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

embedded-postgres

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

When testing this provides a higher level of confidence than using any in memory alternative. It also requires no other external dependencies outside of the Go build ecosystem.

Heavily inspired by Java projects zonkyio/embedded-postgres and opentable/otj-pg-embedded and reliant on the great work being done by zonkyio/embedded-postgres-binaries in order to fetch precompiled binaries from Maven.

Installation

embedded-postgres uses Go modules and as such can be referenced by release version for use as a library. Use the following to add the latest release to your project.

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

How to use

This library aims to require as little configuration as possible, favouring overridable defaults

Configuration	Default Value
Username	postgres
Password	postgres
Database	postgres
Version	12.1.0
RuntimePath	$USER_HOME/.embedded-postgres-go/extracted
DataPath	$USER_HOME/.embedded-postgres-go/extracted/data
Port	5432
StartTimeout	15 Seconds

The RuntimePath directory is erased and recreated at each Start() and therefore not suitable for persistent data.

If a persistent data location is required, set DataPath to a directory outside RuntimePath.

If the RuntimePath directory is empty or already initialized but with an incompatible postgres version, it will be removed and Postgres reinitialized.

A single Postgres instance can be created, started and stopped as follows

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

// Do test logic

err := postgres.Stop()

or with created with custom configuration

logger := &bytes.Byffer{}
postgres := NewDatabase(DefaultConfig().
            Username("beer").
            Password("wine").
            Database("gin").
            Version(V12).
            RuntimePath("/tmp").
            Port(9876).
            StartTimeout(45 * time.Second).
            Logger(logger))
err := postgres.Start()

// Do test logic

err := postgres.Stop()

It should be noted that if postgres.Stop() is not called then the child Postgres process will not be released and the caller will block.

Examples

There are a number of realistic representations of how to use this library in examples.

Credits

• Gopherize Me Thanks for the awesome logo template.
• zonkyio/embedded-postgres-binaries Without which the precompiled Postgres binaries would not exist for this to work.

Contributing

View the contributing guide.