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 |
| 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 |
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 (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) 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
- type PostgresVersion
- type RemoteFetchStrategy
- type VersionStrategy
Constants ¶
const ( V16 = PostgresVersion("16.2.0") V15 = PostgresVersion("15.6.0") V14 = PostgresVersion("14.11.0") V13 = PostgresVersion("13.14.0") V12 = PostgresVersion("12.17.0") V11 = PostgresVersion("11.22.0") V10 = PostgresVersion("10.23.0") V9 = PostgresVersion("9.6.24") )
Predefined supported Postgres versions.
Variables ¶
This section is empty.
Functions ¶
func TestGetConnectionURL ¶ added in v1.22.0
Types ¶
type CacheLocator ¶
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: 15 Port: 5432 Database: postgres Username: postgres Password: postgres StartTimeout: 15 Seconds
func (Config) BinariesPath ¶ added in v1.10.0
BinariesPath sets the path of the pre-downloaded postgres binaries. If this option is left unset, the binaries will be downloaded.
func (Config) BinaryRepositoryURL ¶ added in v1.15.0
BinaryRepositoryURL set BinaryRepositoryURL to fetch PG Binary in case of Maven proxy
func (Config) CachePath ¶ added in v1.24.0
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 ¶ added in v1.4.0
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) GetConnectionURL ¶ added in v1.22.0
func (Config) RuntimePath ¶
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 ¶ added in v1.23.0
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 ¶
StartTimeout sets the max timeout that will be used when starting the Postgres process and creating the initial database.
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.
Source Files
Directories