Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/fergusstrange/embedded-postgres
Run a real Postgres database locally on Linux, OSX or Windows as part of another Go application or test
https://github.com/fergusstrange/embedded-postgres
Last synced: about 2 months ago
JSON representation
Run a real Postgres database locally on Linux, OSX or Windows as part of another Go application or test
- Host: GitHub
- URL: https://github.com/fergusstrange/embedded-postgres
- Owner: fergusstrange
- License: mit
- Created: 2019-11-16T23:49:40.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2024-08-26T10:25:32.000Z (4 months ago)
- Last Synced: 2024-08-27T12:57:21.183Z (4 months ago)
- Language: Go
- Homepage:
- Size: 393 KB
- Stars: 810
- Watchers: 8
- Forks: 83
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-go - embedded-postgres - Run a real Postgres database locally on Linux, OSX or Windows as part of another Go application or test. (Testing / Testing Frameworks)
- zero-alloc-awesome-go - embedded-postgres - Run a real Postgres database locally on Linux, OSX or Windows as part of another Go application or test. (Testing / HTTP Clients)
- awesome-go-extra - embedded-postgres - 11-16T23:49:40Z|2022-08-09T00:27:04Z| (Testing / Testing Frameworks)
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](https://github.com/zonkyio/embedded-postgres)
and [opentable/otj-pg-embedded](https://github.com/opentable/otj-pg-embedded) and reliant on the great work being done
by [zonkyio/embedded-postgres-binaries](https://github.com/zonkyio/embedded-postgres-binaries) in order to fetch
precompiled binaries
from [Maven](https://mvnrepository.com/artifact/io.zonky.test.postgres/embedded-postgres-binaries-bom).
## 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.
```bash
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
```go
postgres := embeddedpostgres.NewDatabase()
err := postgres.Start()
// Do test logic
err := postgres.Stop()
```
or created with custom configuration
```go
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](https://github.com/fergusstrange/embedded-postgres/tree/master/examples).
## Credits
- [Gopherize Me](https://gopherize.me) Thanks for the awesome logo template.
- [zonkyio/embedded-postgres-binaries](https://github.com/zonkyio/embedded-postgres-binaries) Without which the
precompiled Postgres binaries would not exist for this to work.
## Contributing
View the [contributing guide](CONTRIBUTING.md).