testcontainers::modules::ClickHouseImage Class Reference

A reusable, copyable description of a ClickHouse test server: image, credentials, init scripts, and server-config drop-ins. More...

#include <testcontainers/modules/ClickHouse.hpp>

Public Member Functions
	ClickHouseImage ()
	A config ready to start(): image clickhouse:26.3, credentials test/test/test, ports 8123 + 9000 exposed, and the ordered handover → /ping → SELECT 1 readiness triple.
ClickHouseImage &	with_image (const std::string &reference)
	Override the pinned image with a full reference "name[:tag]" (tag defaults to "latest").
ClickHouseImage &	with_username (std::string username)
	Account provisioned at first boot (CLICKHOUSE_USER).
ClickHouseImage &	with_password (std::string password)
	Password for the provisioned account (CLICKHOUSE_PASSWORD).
ClickHouseImage &	with_database (std::string database)
	Database created at first boot (CLICKHOUSE_DB). Default "test".
ClickHouseImage &	with_init_script (std::filesystem::path host_path)
	Queue a host file for /docker-entrypoint-initdb.d — SQL or shell the image's provisioning server runs ONCE, at first boot, before the real server listens (the default readiness probes therefore also wait for every init script to finish).
ClickHouseImage &	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).
ClickHouseImage &	with_config_file (std::filesystem::path host_config)
	Ship a server-configuration drop-in into /etc/clickhouse-server/config.d under its own file name.
ClickHouseImage &	with_env (std::string key, std::string value)
	Set an extra environment variable — the image's own knobs, e.g.
ClickHouseImage &	with_label (std::string key, std::string value)
ClickHouseImage &	with_network (std::string network)
	Join a user-defined network; peers resolve this container by name/alias at <alias>:8123 / <alias>:9000 (the in-container ports), using the same provisioned credentials.
ClickHouseImage &	with_network (const Network &network)
ClickHouseImage &	with_network_alias (std::string alias)
ClickHouseImage &	with_reuse (bool reuse=true)
	Enable container reuse (effective only when reuse is also enabled globally — see GenericImage::with_reuse).
ClickHouseImage &	with_wait (WaitFor wait)
	REPLACE the default readiness triple with a custom strategy (the first call drops the module's probes; repeatable — further waits run in order under the same timeout).
ClickHouseImage &	with_startup_timeout (std::chrono::milliseconds timeout)
	Budget for the whole readiness phase (default: 60s).
ClickHouseImage &	with_startup_attempts (int n)
	Retry the whole create→start→wait sequence up to n times.
ClickHouseImage &	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, ulimits, 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 — credential env, init-script and config-drop-in copies, 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 ClickHouseContainer.
ClickHouseContainer	start () const
	Create, start, and wait through the readiness triple: the entrypoint handed over to the real server (every init script done), /ping answers on the published HTTP port, and an in-container SELECT 1 succeeds over the native protocol.

Static Public Attributes
static constexpr std::string_view	kDefaultImage = "clickhouse:26.3"
	The pinned default image.
static constexpr std::uint16_t	kHttpPort = 8123
	The HTTP-interface port INSIDE the container.
static constexpr std::uint16_t	kNativePort = 9000
	The native-protocol port INSIDE the container (clickhouse-cpp, clickhouse-client).

Detailed Description

A reusable, copyable description of a ClickHouse test server: image, credentials, init scripts, and server-config drop-ins.

start() runs it and returns a ClickHouseContainer whose getters hand out the endpoints for both protocols.

Defaults: clickhouse:26.3, user/password/database all "test", ports 8123 (HTTP) and 9000 (native protocol) published on ephemeral host ports, and an ORDERED readiness triple: (1) the entrypoint has handed the container over to the real server (the image's first boot runs a TEMPORARY server for provisioning and init scripts that network probes cannot reliably tell apart from the real one — the entrypoint finishing by exec'ing the server over itself can); (2) HTTP /ping answering 200 through the published port; (3) an in-container SELECT 1 over the native protocol, which also proves the provisioned credentials. Every init script has finished by (1). The configured user is the ONLY account: the image removes its built-in default user when it provisions a custom one.

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

ClickHouseImage()

testcontainers::modules::ClickHouseImage::ClickHouseImage

(

)

A config ready to start(): image clickhouse:26.3, credentials test/test/test, ports 8123 + 9000 exposed, and the ordered handover → /ping → SELECT 1 readiness triple.

Member Function Documentation

with_image()

ClickHouseImage & testcontainers::modules::ClickHouseImage::with_image

(

const std::string &

reference

)

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

with_username()

ClickHouseImage & testcontainers::modules::ClickHouseImage::with_username

(

std::string

username

)

Account provisioned at first boot (CLICKHOUSE_USER).

Default "test". The provisioned user may connect from any address and REPLACES the image's built-in default user.

with_password()

ClickHouseImage & testcontainers::modules::ClickHouseImage::with_password

(

std::string

password

)

Password for the provisioned account (CLICKHOUSE_PASSWORD).

Default "test". Empty throws at start(): the image restricts a passwordless default user to the container's loopback, so the module's host-side getters could never be true — run a deliberately passwordless server through to_generic() instead. Test credentials only: the value is visible via inspect.

with_database()

ClickHouseImage & testcontainers::modules::ClickHouseImage::with_database

(

std::string

database

)

Database created at first boot (CLICKHOUSE_DB). Default "test".

with_init_script() [1/2]

ClickHouseImage & testcontainers::modules::ClickHouseImage::with_init_script

(

std::filesystem::path

host_path

)

Queue a host file for /docker-entrypoint-initdb.d — SQL or shell the image's provisioning server runs ONCE, at first boot, before the real server listens (the default readiness probes therefore also wait for every init script to finish).

Repeatable; scripts run in REGISTRATION order — the module prefixes each container-side name with a zero-padded index because the entrypoint runs files in name order. The extension must be one the entrypoint executes — .sql, .sql.gz, or .sh (anything else throws here rather than being silently ignored in the container). .sh files are shipped executable. The file is read when start() copies it.

Two entrypoint contracts to know: scripts run with NO default database — qualify names (CREATE TABLE test.t ...) or open with USE <db>; (the client runs in multiquery mode) — and a FAILING script aborts the whole boot, so start() fails loudly (the wait times out; the container's log carries the script's error).

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

with_init_script() [2/2]

ClickHouseImage & testcontainers::modules::ClickHouseImage::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_file()

ClickHouseImage & testcontainers::modules::ClickHouseImage::with_config_file

(

std::filesystem::path

host_config

)

Ship a server-configuration drop-in into /etc/clickhouse-server/config.d under its own file name.

The name must end in .xml, .yaml, or .yml — the server merges only those (anything else throws here). Do not remap http_port / tcp_port / listen_host: that breaks the module's port getters and the readiness probe.

with_env()

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

Set an extra environment variable — the image's own knobs, e.g.

CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1 to allow SQL CREATE USER/GRANT from the provisioned account. 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. Leave CLICKHOUSE_SKIP_USER_SETUP unset — it disables the provisioning the getters describe.

with_label()

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

with_network() [1/2]

ClickHouseImage & testcontainers::modules::ClickHouseImage::with_network

(

std::string

network

)

Join a user-defined network; peers resolve this container by name/alias at <alias>:8123 / <alias>:9000 (the in-container ports), using the same provisioned credentials.

with_network() [2/2]

ClickHouseImage & testcontainers::modules::ClickHouseImage::with_network

(

const Network &

network

)

with_network_alias()

ClickHouseImage & testcontainers::modules::ClickHouseImage::with_network_alias

(

std::string

alias

)

with_reuse()

ClickHouseImage & testcontainers::modules::ClickHouseImage::with_reuse

(

bool

reuse = true

)

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

The natural fit for a seeded analytics database that should survive across test runs; an adopted server keeps its data, and init scripts are not re-run.

with_wait()

ClickHouseImage & testcontainers::modules::ClickHouseImage::with_wait

(

WaitFor

wait

)

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

Mind the first-boot provisioning server: network and loopback probes read ready against it (even through the published port on Docker Desktop) — gate on wait_for::successful_shell_command("grep -q clickhouse /proc/1/comm") first, as the default triple does.

with_startup_timeout()

ClickHouseImage & testcontainers::modules::ClickHouseImage::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()

ClickHouseImage & testcontainers::modules::ClickHouseImage::with_startup_attempts

(

int

n

)

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

with_customizer()

ClickHouseImage & testcontainers::modules::ClickHouseImage::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, ulimits, 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 CLICKHOUSE_* credential env here: it would desync the credential getters, the DSN, and exec_sql — use the typed setters instead.

username()

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

inlinenoexcept

password()

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

inlinenoexcept

database()

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

inlinenoexcept

to_generic()

GenericImage testcontainers::modules::ClickHouseImage::to_generic

(

)

const

Render the full configuration — credential env, init-script and config-drop-in copies, 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 ClickHouseContainer.

Throws Error on an invalid config (empty username, password, or database) before any daemon contact.

start()

ClickHouseContainer testcontainers::modules::ClickHouseImage::start

(

)

const

Create, start, and wait through the readiness triple: the entrypoint handed over to the real server (every init script done), /ping answers on the published HTTP port, and an in-container SELECT 1 succeeds over the native protocol.

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::ClickHouseImage::kDefaultImage = "clickhouse:26.3"

staticconstexpr

The pinned default image.

Override with with_image; any image that keeps the official entrypoint contract (CLICKHOUSE_* env, /docker-entrypoint-initdb.d, clickhouse-client on PATH) works.

kHttpPort

std::uint16_t testcontainers::modules::ClickHouseImage::kHttpPort = 8123

staticconstexpr

The HTTP-interface port INSIDE the container.

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

kNativePort

std::uint16_t testcontainers::modules::ClickHouseImage::kNativePort = 9000

staticconstexpr

The native-protocol port INSIDE the container (clickhouse-cpp, clickhouse-client).

Host side: ClickHouseContainer::native_port().