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.
```
config := DefaultConfig().Version(embeddedpostgres.V15)
```
Port(port uint32):
Sets the runtime port for PostgreSQL.
```
config := DefaultConfig().Port(9876)
```
Database(database string):
Sets the name of the initial database to be created.
```
config := DefaultConfig().Database("my_database")
```
Username(username string):
Sets the username for the database connection.
```
config := DefaultConfig().Username("my_user")
```
Password(password string):
Sets the password for the database connection.
```
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.
```
config := DefaultConfig().RuntimePath("/tmp/pg_runtime")
```
CachePath(path string):
Sets the directory for storing downloaded PostgreSQL binary archives. Defaults to ~/.embedded-postgres-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.
```
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.
```
config := DefaultConfig().BinariesPath("./postgres-binaries")
```
Locale(locale string):
Sets the default locale for initdb.
```
config := DefaultConfig().Locale("en_US.UTF-8")
```
Encoding(encoding string): Sets the default character set encoding for initdb.
```
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.
```
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.
```
config := DefaultConfig().StartTimeout(45 * time.Second)
```
Logger(logger io.Writer):
Sets the writer for PostgreSQL's stdout and stderr logs.
```
config := DefaultConfig().Logger(os.Stderr)
```
BinaryRepositoryURL(url string):
Overrides the default Maven repository URL for downloading binaries.
```
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()