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 every Start() 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 of RuntimePath, 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 for initdb. go config := DefaultConfig().Locale("en_US.UTF-8")

  • Encoding(encoding string): Sets the default character set encoding for initdb. go config := DefaultConfig().Encoding("UTF8")

  • StartParameters(parameters map[string]string): Sets run-time parameters (e.g., max_connections) passed to the postgres 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's stdout and stderr 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()