Configuration Guide
Configuration is managed through the Config
struct. You can start with a sensible set of defaults using DefaultConfig()
and then chain methods to customize the instance.
Default Configuration
The default configuration is as follows:
Configuration | Default Value |
---|---|
Version | V17 (17.5.0 ) |
Port | 5432 |
Database | postgres |
Username | postgres |
Password | postgres |
StartTimeout | 15 Seconds |
CachePath | ~/.embedded-postgres-go/ |
RuntimePath | ~/.embedded-postgres-go/extracted |
DataPath | RuntimePath/data |
BinariesPath | RuntimePath |
BinaryRepositoryURL | https://repo1.maven.org/maven2 |
Logger | os.Stdout |
Customization Example
Here is an example of creating a custom configuration:
config := embeddedpostgres.DefaultConfig().
Version(embeddedpostgres.V16).
Port(5433).
Database("my_app_db").
Username("my_user").
Password("secret").
StartTimeout(30 * time.Second)
postgres := embeddedpostgres.NewDatabase(config)
err := postgres.Start()
Configuration Options
All configuration methods return a new Config
struct, allowing them to be chained together.
-
Version(version PostgresVersion)
: Sets the PostgreSQL binary version. See available versions below.go config := DefaultConfig().Version(embeddedpostgres.V15)
-
Port(port uint32)
: Sets the runtime port for PostgreSQL.go config := DefaultConfig().Port(9876)
-
Database(database string)
: Sets the name of the initial database to be created.go config := DefaultConfig().Database("my_database")
-
Username(username string)
: Sets the username for the database connection.go config := DefaultConfig().Username("my_user")
-
Password(password string)
: Sets the password for the database connection.go config := DefaultConfig().Password("strong_password")
-
RuntimePath(path string)
: Sets the directory where binaries are extracted and PostgreSQL runs. This directory is cleared on everyStart()
call.go config := DefaultConfig().RuntimePath("/tmp/pg_runtime")
-
CachePath(path string)
: Sets the directory for storing downloaded PostgreSQL binary archives. Defaults to~/.embedded-postgres-go
.go config := DefaultConfig().CachePath("/tmp/pg_cache")
-
DataPath(path string)
: Sets the directory for the PostgreSQL data files (PGDATA
). If you set this to a path outside ofRuntimePath
, the data will persist between restarts.go config := DefaultConfig().DataPath("/tmp/pg_data_persistent")
-
BinariesPath(path string)
: Sets the path to pre-downloaded and extracted PostgreSQL binaries. If this is set, the library will skip downloading.go config := DefaultConfig().BinariesPath("./postgres-binaries")
-
Locale(locale string)
: Sets the default locale forinitdb
.go config := DefaultConfig().Locale("en_US.UTF-8")
-
Encoding(encoding string)
: Sets the default character set encoding forinitdb
.go config := DefaultConfig().Encoding("UTF8")
-
StartParameters(parameters map[string]string)
: Sets run-time parameters (e.g.,max_connections
) passed to thepostgres
command via the-c
flag.go config := DefaultConfig().StartParameters(map[string]string{"max_connections": "200"})
-
StartTimeout(timeout time.Duration)
: Sets the maximum time to wait for the PostgreSQL process to start and become available.go config := DefaultConfig().StartTimeout(45 * time.Second)
-
Logger(logger io.Writer)
: Sets the writer for PostgreSQL'sstdout
andstderr
logs.go config := DefaultConfig().Logger(os.Stderr)
-
BinaryRepositoryURL(url string)
: Overrides the default Maven repository URL for downloading binaries.go config := DefaultConfig().BinaryRepositoryURL("https://my-proxy.com/maven2")
Supported PostgreSQL Versions
The library provides constants for tested PostgreSQL versions:
const (
V17 = PostgresVersion("17.5.0")
V16 = PostgresVersion("16.9.0")
V15 = PostgresVersion("15.13.0")
V14 = PostgresVersion("14.18.0")
V13 = PostgresVersion("13.21.0")
V12 = PostgresVersion("12.22.0")
V11 = PostgresVersion("11.22.0")
V10 = PostgresVersion("10.23.0")
V9 = PostgresVersion("9.6.24")
)
Connection URL Helper
The Config
struct includes a helper method to generate a standard PostgreSQL connection URL, which can be useful for database drivers.
config := DefaultConfig().Database("mydb").Username("myuser").Password("mypass")
// Returns: "postgresql://myuser:mypass@localhost:5432/mydb"
connectionURL := config.GetConnectionURL()