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.
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
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.
There are a number of realistic representations of how to use this library in examples.
- 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.
View the contributing guide.