embeddedpostgres

README

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	15.3.0
Encoding	UTF8
Locale	C
Version	15.3.0
CachePath	$USER_HOME/.embedded-postgres-go/
RuntimePath	$USER_HOME/.embedded-postgres-go/extracted
DataPath	$USER_HOME/.embedded-postgres-go/extracted/data
BinariesPath	$USER_HOME/.embedded-postgres-go/extracted
BinaryRepositoryURL	https://repo1.maven.org/maven2
Port	5432
StartTimeout	15 Seconds
StartParameters	map[string]string{"max_connections": "101"}

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.

Postgres binaries will be downloaded and placed in BinaryPath if BinaryPath/bin doesn't exist. BinaryRepositoryURL parameter allow overriding maven repository url for Postgres binaries. If the directory does exist, whatever binary version is placed there will be used (no version check is done).
If your test need to run multiple different versions of Postgres for different tests, make sure BinaryPath is a subdirectory of RuntimePath.

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 created with custom configuration

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()

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.

Documentation

Index

• Constants
• func TestGetConnectionURL(t *testing.T)
• type CacheLocator
• type Config
  • func DefaultConfig() Config
  • func (c Config) BinariesPath(path string) Config
  • func (c Config) BinaryRepositoryURL(binaryRepositoryURL string) Config
  • func (c Config) CachePath(path string) Config
  • func (c Config) DataPath(path string) Config
  • func (c Config) Database(database string) Config
  • func (c Config) Encoding(encoding string) Config
  • func (c Config) GetConnectionURL() string
  • func (c Config) Locale(locale string) Config
  • func (c Config) Logger(logger io.Writer) Config
  • func (c Config) Password(password string) Config
  • func (c Config) Port(port uint32) Config
  • func (c Config) RuntimePath(path string) Config
  • func (c Config) StartParameters(parameters map[string]string) Config
  • func (c Config) StartTimeout(timeout time.Duration) Config
  • func (c Config) Username(username string) Config
  • func (c Config) Version(version PostgresVersion) Config
• type EmbeddedPostgres
  • func NewDatabase(config ...Config) *EmbeddedPostgres
  • func (ep *EmbeddedPostgres) Start() error
  • func (ep *EmbeddedPostgres) Stop() error
• type PostgresVersion
• type RemoteFetchStrategy
• type VersionStrategy

Constants

const (
	V16 = PostgresVersion("16.4.0")
	V15 = PostgresVersion("15.8.0")
	V14 = PostgresVersion("14.13.0")
	V13 = PostgresVersion("13.16.0")
	V12 = PostgresVersion("12.20.0")
	V11 = PostgresVersion("11.22.0")
	V10 = PostgresVersion("10.23.0")
	V9  = PostgresVersion("9.6.24")
)

Predefined supported Postgres versions.

Functions

func TestGetConnectionURL

func TestGetConnectionURL(t *testing.T)

Types

type CacheLocator

type CacheLocator func() (location string, exists bool)

CacheLocator retrieves the location of the Postgres binary cache returning it to location. The result of whether this cache is present will be returned to exists.

type Config

type Config struct {
	// contains filtered or unexported fields
}

Config maintains the runtime configuration for the Postgres process to be created.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig provides a default set of configuration to be used "as is" or modified using the provided builders. The following can be assumed as defaults: Version: 16 Port: 5432 Database: postgres Username: postgres Password: postgres StartTimeout: 15 Seconds

func (Config) BinariesPath

func (c Config) BinariesPath(path string) Config

BinariesPath sets the path of the pre-downloaded postgres binaries. If this option is left unset, the binaries will be downloaded.

func (Config) BinaryRepositoryURL

func (c Config) BinaryRepositoryURL(binaryRepositoryURL string) Config

BinaryRepositoryURL set BinaryRepositoryURL to fetch PG Binary in case of Maven proxy

func (Config) CachePath

func (c Config) CachePath(path string) Config

CachePath sets the path that will be used for storing Postgres binaries archive. If this option is not set, ~/.go-embedded-postgres will be used.

func (Config) DataPath

func (c Config) DataPath(path string) Config

DataPath sets the path that will be used for the Postgres data directory. If this option is set, a previously initialized data directory will be reused if possible.

func (Config) Database

func (c Config) Database(database string) Config

Database sets the database name that will be created.

func (Config) Encoding

func (c Config) Encoding(encoding string) Config

Encoding sets the default character set for initdb

func (Config) GetConnectionURL

func (c Config) GetConnectionURL() string

func (Config) Locale

func (c Config) Locale(locale string) Config

Locale sets the default locale for initdb

func (Config) Logger

func (c Config) Logger(logger io.Writer) Config

Logger sets the logger for postgres output

func (Config) Password

func (c Config) Password(password string) Config

Password sets the password that will be used to connect.

func (Config) Port

func (c Config) Port(port uint32) Config

Port sets the runtime port that Postgres can be accessed on.

func (Config) RuntimePath

func (c Config) RuntimePath(path string) Config

RuntimePath sets the path that will be used for the extracted Postgres runtime directory. If Postgres data directory is not set with DataPath(), this directory is also used as data directory.

func (Config) StartParameters

func (c Config) StartParameters(parameters map[string]string) Config

StartParameters sets run-time parameters when starting Postgres (passed to Postgres via "-c").

These parameters can be used to override the default configuration values in postgres.conf such as max_connections=100. See https://www.postgresql.org/docs/current/runtime-config.html

func (Config) StartTimeout

func (c Config) StartTimeout(timeout time.Duration) Config

StartTimeout sets the max timeout that will be used when starting the Postgres process and creating the initial database.

func (Config) Username

func (c Config) Username(username string) Config

Username sets the username that will be used to connect.

func (Config) Version

func (c Config) Version(version PostgresVersion) Config

Version will set the Postgres binary version.

type EmbeddedPostgres

type EmbeddedPostgres struct {
	// contains filtered or unexported fields
}

EmbeddedPostgres maintains all configuration and runtime functions for maintaining the lifecycle of one Postgres process.

func NewDatabase

func NewDatabase(config ...Config) *EmbeddedPostgres

NewDatabase creates a new EmbeddedPostgres struct that can be used to start and stop a Postgres process. When called with no parameters it will assume a default configuration state provided by the DefaultConfig method. When called with parameters the first Config parameter will be used for configuration.

func (*EmbeddedPostgres) Start

func (ep *EmbeddedPostgres) Start() error

Start will try to start the configured Postgres process returning an error when there were any problems with invocation. If any error occurs Start will try to also Stop the Postgres process in order to not leave any sub-process running.

func (*EmbeddedPostgres) Stop

func (ep *EmbeddedPostgres) Stop() error

Stop will try to stop the Postgres process gracefully returning an error when there were any problems.

type PostgresVersion

type PostgresVersion string

PostgresVersion represents the semantic version used to fetch and run the Postgres process.

type RemoteFetchStrategy

type RemoteFetchStrategy func() error

RemoteFetchStrategy provides a strategy to fetch a Postgres binary so that it is available for use.

type VersionStrategy

type VersionStrategy func() (operatingSystem string, architecture string, postgresVersion PostgresVersion)

VersionStrategy provides a strategy that can be used to determine which version of Postgres should be used based on the operating system, architecture and desired Postgres version.