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 (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
- 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.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
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: 12 Port: 5432 Database: postgres Username: postgres Password: postgres StartTimeout: 15 Seconds
func (Config) RuntimePath ¶
RuntimePath sets the path that will be used for the extracted Postgres runtime and data directory.
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) 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.