testcontainers::modules::PostgreSQLImage Class Reference

A reusable, copyable description of a PostgreSQL test database: image, credentials, init scripts, and server configuration. More...

#include <testcontainers/modules/PostgreSQL.hpp>

Public Member Functions
	PostgreSQLImage ()
	A config ready to start(): image postgres:16-alpine, credentials test/test/test, port 5432 exposed, pg_isready readiness probe.
PostgreSQLImage &	with_image (const std::string &reference)
	Override the pinned image with a full reference "name[:tag]" (tag defaults to "latest").
PostgreSQLImage &	with_username (std::string username)
	Superuser name the database is initialized with (POSTGRES_USER).
PostgreSQLImage &	with_password (std::string password)
	Superuser password (POSTGRES_PASSWORD).
PostgreSQLImage &	with_database (std::string database)
	Name of the database created at first boot (POSTGRES_DB). Default "test".
PostgreSQLImage &	with_init_script (std::filesystem::path host_path)
	Queue a host file for /docker-entrypoint-initdb.d — SQL or shell the server runs ONCE, at first boot, before it accepts TCP connections (the default readiness probe therefore also waits for every init script to finish).
PostgreSQLImage &	with_init_script (const std::string &name, std::string content)
	In-memory variant: queue content under the given file name (a bare name, no directories; same extension rules and ordering as above).
PostgreSQLImage &	with_config_option (std::string key, std::string value)
	Append a server configuration parameter, passed as postgres -c key=value on the container command line — e.g.
PostgreSQLImage &	with_env (std::string key, std::string value)
	Set an extra environment variable — the image's own knobs (POSTGRES_INITDB_ARGS, POSTGRES_HOST_AUTH_METHOD, PGDATA, ...).
PostgreSQLImage &	with_label (std::string key, std::string value)
PostgreSQLImage &	with_network (std::string network)
	Join a user-defined network; peers resolve this container by name/alias at <alias>:5432 (kPort, not the mapped host port).
PostgreSQLImage &	with_network (const Network &network)
PostgreSQLImage &	with_network_alias (std::string alias)
PostgreSQLImage &	with_reuse (bool reuse=true)
	Enable container reuse (effective only when reuse is also enabled globally — see GenericImage::with_reuse for the full semantics).
PostgreSQLImage &	with_wait (WaitFor wait)
	REPLACE the default readiness probe with a custom strategy (the first call drops the module's pg_isready probe; repeatable — further waits run in order under the same timeout).
PostgreSQLImage &	with_startup_timeout (std::chrono::milliseconds timeout)
	Budget for the whole readiness phase (default: 60s).
PostgreSQLImage &	with_startup_attempts (int n)
	Retry the whole create→start→wait sequence up to n times.
PostgreSQLImage &	with_customizer (std::function< void(GenericImage &)> customize)
	Register a callback that customizes the underlying GenericImage — the channel for every option this module does not surface (mounts, shm size, pull policy, ...).
const std::string &	username () const noexcept
const std::string &	password () const noexcept
const std::string &	database () const noexcept
GenericImage	to_generic () const
	Render the full configuration — credentials env, init-script copies, config-option command line, readiness probe, customizers — into a plain GenericImage: the drop-down escape hatch when you need a raw core Container (or run-level tweaks) instead of a PostgreSQLContainer.
PostgreSQLContainer	start () const
	Create, start, and wait until the server accepts TCP connections (by which point every init script has run).

Static Public Attributes
static constexpr std::string_view	kDefaultImage = "postgres:16-alpine"
	The pinned default image.
static constexpr std::uint16_t	kPort = 5432
	The server port INSIDE the container.

Detailed Description

A reusable, copyable description of a PostgreSQL test database: image, credentials, init scripts, and server configuration.

start() runs it and returns a PostgreSQLContainer whose getters hand out ready-to-paste connection strings.

Defaults: postgres:16-alpine, user/password/database all "test", port 5432 published on an ephemeral host port, readiness = an in-container pg_isready -h 127.0.0.1 probe (immune to the image's initialization restart — the temporary init server never listens on TCP, so TCP readiness also proves every init script finished).

The with_* builders mutate in place and return *this, so a named config can be configured incrementally and started many times. Core options the module does not surface are reached through with_customizer; to_generic() drops down to a plain GenericImage entirely.

Constructor & Destructor Documentation

PostgreSQLImage()

testcontainers::modules::PostgreSQLImage::PostgreSQLImage

(

)

A config ready to start(): image postgres:16-alpine, credentials test/test/test, port 5432 exposed, pg_isready readiness probe.

Member Function Documentation

with_image()

PostgreSQLImage & testcontainers::modules::PostgreSQLImage::with_image

(

const std::string &

reference

)

Override the pinned image with a full reference "name[:tag]" (tag defaults to "latest").

with_username()

PostgreSQLImage & testcontainers::modules::PostgreSQLImage::with_username

(

std::string

username

)

Superuser name the database is initialized with (POSTGRES_USER).

Default "test".

with_password()

PostgreSQLImage & testcontainers::modules::PostgreSQLImage::with_password

(

std::string

password

)

Superuser password (POSTGRES_PASSWORD).

Default "test". The postgres image refuses to boot with an EMPTY password, so start() throws immediately in that case — unless with_env("POSTGRES_HOST_AUTH_METHOD", "trust") was also set to run a deliberately passwordless server. Test credentials only: the value is visible via inspect.

with_database()

PostgreSQLImage & testcontainers::modules::PostgreSQLImage::with_database

(

std::string

database

)

Name of the database created at first boot (POSTGRES_DB). Default "test".

with_init_script() [1/2]

PostgreSQLImage & testcontainers::modules::PostgreSQLImage::with_init_script

(

std::filesystem::path

host_path

)

Queue a host file for /docker-entrypoint-initdb.d — SQL or shell the server runs ONCE, at first boot, before it accepts TCP connections (the default readiness probe therefore also waits for every init script to finish).

Repeatable; scripts run in REGISTRATION order — the module prefixes each container-side name with a zero-padded index ("0000-schema.sql", "0001-seed.sql") because the entrypoint runs files in name order. The extension picks the execution mode and must be one the entrypoint knows — .sql, .sql.gz, .sql.xz, .sql.zst, or .sh (anything else throws here rather than being silently ignored in the container). .sh files are shipped executable so they run as standalone scripts. The file is read when start() copies it.

A reused (adopted) container does NOT re-run init scripts — its data dir is already initialized, which is the point of reuse; editing a script changes the reuse hash, so the next start() builds a fresh container with the new schema.

with_init_script() [2/2]

PostgreSQLImage & testcontainers::modules::PostgreSQLImage::with_init_script	(	const std::string &	name,
		std::string	content )

In-memory variant: queue content under the given file name (a bare name, no directories; same extension rules and ordering as above).

with_config_option()

PostgreSQLImage & testcontainers::modules::PostgreSQLImage::with_config_option	(	std::string	key,
		std::string	value )

Append a server configuration parameter, passed as postgres -c key=value on the container command line — e.g.

with_config_option("fsync", "off") (the classic test-suite speedup) or "wal_level"/"logical" for CDC tests. Repeatable; for a key given twice the server applies the LAST value. Setting "port" or "listen_addresses" breaks the module's port getter and readiness probe — leave those alone.

with_env()

PostgreSQLImage & testcontainers::modules::PostgreSQLImage::with_env	(	std::string	key,
		std::string	value )

Set an extra environment variable — the image's own knobs (POSTGRES_INITDB_ARGS, POSTGRES_HOST_AUTH_METHOD, PGDATA, ...).

The credential trio belongs to with_username/with_password/with_database: the module applies those env keys last, so they win over raw duplicates set here.

with_label()

PostgreSQLImage & testcontainers::modules::PostgreSQLImage::with_label	(	std::string	key,
		std::string	value )

with_network() [1/2]

PostgreSQLImage & testcontainers::modules::PostgreSQLImage::with_network

(

std::string

network

)

Join a user-defined network; peers resolve this container by name/alias at <alias>:5432 (kPort, not the mapped host port).

with_network() [2/2]

PostgreSQLImage & testcontainers::modules::PostgreSQLImage::with_network

(

const Network &

network

)

with_network_alias()

PostgreSQLImage & testcontainers::modules::PostgreSQLImage::with_network_alias

(

std::string

alias

)

with_reuse()

PostgreSQLImage & testcontainers::modules::PostgreSQLImage::with_reuse

(

bool

reuse = true

)

Enable container reuse (effective only when reuse is also enabled globally — see GenericImage::with_reuse for the full semantics).

The natural fit for a seeded database that should survive across test runs: same config, and the next run adopts the running server with its data intact.

with_wait()

PostgreSQLImage & testcontainers::modules::PostgreSQLImage::with_wait

(

WaitFor

wait

)

REPLACE the default readiness probe with a custom strategy (the first call drops the module's pg_isready probe; repeatable — further waits run in order under the same timeout).

Note a plain pg_isready WITHOUT "-h 127.0.0.1" checks the unix socket and reads ready during the image's initialization window — keep the "-h".

with_startup_timeout()

PostgreSQLImage & testcontainers::modules::PostgreSQLImage::with_startup_timeout

(

std::chrono::milliseconds

timeout

)

Budget for the whole readiness phase (default: 60s).

Raise it when init scripts do real work or CI I/O is slow; image pull time does not count against it.

with_startup_attempts()

PostgreSQLImage & testcontainers::modules::PostgreSQLImage::with_startup_attempts

(

int

n

)

Retry the whole create→start→wait sequence up to n times.

with_customizer()

PostgreSQLImage & testcontainers::modules::PostgreSQLImage::with_customizer

(

std::function< void(GenericImage &)>

customize

)

Register a callback that customizes the underlying GenericImage — the channel for every option this module does not surface (mounts, shm size, pull policy, ...).

Customizers run when the config is rendered (start() / to_generic()), in registration order, AFTER the module's own rendering — what they set wins over the module. A wait added here runs IN ADDITION to the default probe (unlike with_wait, which replaces it). Do not set the POSTGRES_* credential env here: it would desync the credential getters, the DSNs, and exec_sql, and the empty-password check does not see it — use with_username/with_password/with_database (and with_env for trust auth) instead.

username()

const std::string & testcontainers::modules::PostgreSQLImage::username ( ) const

inlinenoexcept

password()

const std::string & testcontainers::modules::PostgreSQLImage::password ( ) const

inlinenoexcept

database()

const std::string & testcontainers::modules::PostgreSQLImage::database ( ) const

inlinenoexcept

to_generic()

GenericImage testcontainers::modules::PostgreSQLImage::to_generic

(

)

const

Render the full configuration — credentials env, init-script copies, config-option command line, readiness probe, customizers — into a plain GenericImage: the drop-down escape hatch when you need a raw core Container (or run-level tweaks) instead of a PostgreSQLContainer.

Throws Error on an invalid config (empty username/database; empty password without trust auth) before any daemon contact.

start()

PostgreSQLContainer testcontainers::modules::PostgreSQLImage::start

(

)

const

Create, start, and wait until the server accepts TCP connections (by which point every init script has run).

Throws Error on config errors before touching the daemon; DockerError / StartupTimeoutError from the run itself, like GenericImage::start().

Member Data Documentation

kDefaultImage

std::string_view testcontainers::modules::PostgreSQLImage::kDefaultImage = "postgres:16-alpine"

staticconstexpr

The pinned default image.

Override with with_image; any postgres-derived image that keeps the official entrypoint contract (POSTGRES_* env, /docker-entrypoint-initdb.d, pg_isready on PATH) works — e.g. "pgvector/pgvector:pg16" or "timescale/timescaledb". Note the alpine pin runs with a C locale; for collation-sensitive tests use "postgres:16" (Debian) or POSTGRES_INITDB_ARGS.

kPort

std::uint16_t testcontainers::modules::PostgreSQLImage::kPort = 5432

staticconstexpr

The server port INSIDE the container.

Peers on a shared docker network connect to <alias-or-name>:kPort; the test process itself uses PostgreSQLContainer::port() (the mapped host port) instead.