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	12.1.0
RuntimePath	$USER_HOME/.embedded-postgres-go/extracted
Port	5432
StartTimeout	15 Seconds

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

postgres := NewDatabase(DefaultConfig().
            Username("beer").
            Password("wine").
            Database("gin").
            Version(V12).
            RuntimePath("/tmp").
            Port(9876).
            StartTimeout(45 * time.Second))
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
• type CacheLocator
• type Config
  • func DefaultConfig() Config
  • func (c Config) Database(database string) Config
  • func (c Config) Locale(locale string) 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) 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) CreateDatabase() error
  • func (ep *EmbeddedPostgres) Install() error
  • func (ep *EmbeddedPostgres) IsStarted() bool
  • func (ep *EmbeddedPostgres) Start() error
  • func (ep *EmbeddedPostgres) Stop() error
• type PostgresVersion
• type RemoteFetchStrategy
• type VersionStrategy

Constants

const (
	V13 = PostgresVersion("13.1.0")
	V12 = PostgresVersion("12.1.0-1")
	V11 = PostgresVersion("11.6.0-1")
	V10 = PostgresVersion("10.11.0-1")
	V9  = PostgresVersion("9.6.16-1")
)

Predefined supported Postgres versions.

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: 12 Port: 5432 Database: postgres Username: postgres Password: postgres StartTimeout: 15 Seconds

func (Config) Database

func (c Config) Database(database string) Config

Database sets the database name that will be created.

func (Config) Locale

func (c Config) Locale(locale string) Config

Locale sets the default locale for initdb

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 and data directory.

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

func (ep *EmbeddedPostgres) CreateDatabase() error

CreateDatabase will issue the "CREATE DATABASE" command on a running server

func (*EmbeddedPostgres) Install

func (ep *EmbeddedPostgres) Install() error

Install will make filesystem modifications, retrieving and extracting the PostgreSQL binaries into the configured directory.

func (*EmbeddedPostgres) IsStarted

func (ep *EmbeddedPostgres) IsStarted() bool

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.