1<p align="center">
2 <img src="https://raw.githubusercontent.com/fergusstrange/embedded-postgres/master/gopher.png" width="150">
3</p>
4
5<p align="center">
6<a href="https://godoc.org/github.com/fergusstrange/embedded-postgres"><img src="https://godoc.org/github.com/fergusstrange/embedded-postgres?status.svg" alt="Godoc" /></a>
7<a href='https://coveralls.io/github/fergusstrange/embedded-postgres?branch=master'><img src='https://coveralls.io/repos/github/fergusstrange/embedded-postgres/badge.svg?branch=master' alt='Coverage Status' /></a>
8<a href="https://github.com/fergusstrange/embedded-postgres/actions"><img src="https://github.com/fergusstrange/embedded-postgres/workflows/Embedded%20Postgres/badge.svg" alt="Build Status" /></a>
9<a href="https://app.circleci.com/pipelines/github/fergusstrange/embedded-postgres"><img src="https://circleci.com/gh/fergusstrange/embedded-postgres.svg?style=shield" alt="Build Status" /></a>
10<a href="https://goreportcard.com/report/github.com/fergusstrange/embedded-postgres"><img src="https://goreportcard.com/badge/github.com/fergusstrange/embedded-postgres" alt="Go Report Card" /></a>
11</p>
12
13# embedded-postgres
14
15Run a real Postgres database locally on Linux, OSX or Windows as part of another Go application or test.
16
17When testing this provides a higher level of confidence than using any in memory alternative. It also requires no other
18external dependencies outside of the Go build ecosystem.
19
20Heavily inspired by Java projects [zonkyio/embedded-postgres](https://github.com/zonkyio/embedded-postgres)
21and [opentable/otj-pg-embedded](https://github.com/opentable/otj-pg-embedded) and reliant on the great work being done
22by [zonkyio/embedded-postgres-binaries](https://github.com/zonkyio/embedded-postgres-binaries) in order to fetch
23precompiled binaries
24from [Maven](https://mvnrepository.com/artifact/io.zonky.test.postgres/embedded-postgres-binaries-bom).
25
26## Installation
27
28embedded-postgres uses Go modules and as such can be referenced by release version for use as a library. Use the
29following to add the latest release to your project.
30
31```bash
32go get -u github.com/fergusstrange/embedded-postgres
33```
34
35## How to use
36
37This library aims to require as little configuration as possible, favouring overridable defaults
38
39| Configuration | Default Value |
40|---------------------|-------------------------------------------------|
41| Username | postgres |
42| Password | postgres |
43| Database | postgres |
44| Version | 12.1.0 |
45| CachePath | $USER_HOME/.embedded-postgres-go/ |
46| RuntimePath | $USER_HOME/.embedded-postgres-go/extracted |
47| DataPath | $USER_HOME/.embedded-postgres-go/extracted/data |
48| BinariesPath | $USER_HOME/.embedded-postgres-go/extracted |
49| BinaryRepositoryURL | https://repo1.maven.org/maven2 |
50| Port | 5432 |
51| StartTimeout | 15 Seconds |
52
53The *RuntimePath* directory is erased and recreated at each `Start()` and therefore not suitable for persistent data.
54
55If a persistent data location is required, set *DataPath* to a directory outside *RuntimePath*.
56
57If the *RuntimePath* directory is empty or already initialized but with an incompatible postgres version, it will be
58removed and Postgres reinitialized.
59
60Postgres binaries will be downloaded and placed in *BinaryPath* if `BinaryPath/bin` doesn't exist.
61*BinaryRepositoryURL* parameter allow overriding maven repository url for Postgres binaries.
62If the directory does exist, whatever binary version is placed there will be used (no version check
63is done).
64If your test need to run multiple different versions of Postgres for different tests, make sure
65*BinaryPath* is a subdirectory of *RuntimePath*.
66
67A single Postgres instance can be created, started and stopped as follows
68
69```go
70postgres := embeddedpostgres.NewDatabase()
71err := postgres.Start()
72
73// Do test logic
74
75err := postgres.Stop()
76```
77
78or created with custom configuration
79
80```go
81logger := &bytes.Buffer{}
82postgres := NewDatabase(DefaultConfig().
83Username("beer").
84Password("wine").
85Database("gin").
86Version(V12).
87RuntimePath("/tmp").
88BinaryRepositoryURL("https://repo.local/central.proxy").
89Port(9876).
90StartTimeout(45 * time.Second).
91StartParameters(map[string]string{"max_connections": "200"}).
92Logger(logger))
93err := postgres.Start()
94
95// Do test logic
96
97err := postgres.Stop()
98```
99
100It should be noted that if `postgres.Stop()` is not called then the child Postgres process will not be released and the
101caller will block.
102
103## Examples
104
105There are a number of realistic representations of how to use this library
106in [examples](https://github.com/fergusstrange/embedded-postgres/tree/master/examples).
107
108## Credits
109
110- [Gopherize Me](https://gopherize.me) Thanks for the awesome logo template.
111- [zonkyio/embedded-postgres-binaries](https://github.com/zonkyio/embedded-postgres-binaries) Without which the
112 precompiled Postgres binaries would not exist for this to work.
113
114## Contributing
115
116View the [contributing guide](CONTRIBUTING.md).
117
View as plain text