testcontainers::modules::MariaDBImage Class Reference

A reusable, copyable description of a MariaDB server container. More...

#include <testcontainers/modules/MariaDB.hpp>

Public Member Functions
	MariaDBImage ()
	A config ready to start(): image mariadb:11, credentials test/test/test, port 3306 exposed, the image's own healthcheck.sh readiness probe, and a 120s startup budget (a first boot initializes the data directory and routinely takes tens of seconds on CI).
MariaDBImage &	with_image (const std::string &reference)
	Override the pinned image with a full reference "name[:tag]" (tag defaults to "latest").
MariaDBImage &	with_username (std::string username)
	The user provisioned on first boot (default "test") with full privileges on database().
MariaDBImage &	with_password (std::string password)
	The password (default "test"); the same value becomes the root password.
MariaDBImage &	with_database (std::string database)
	The database created on first boot (default "test").
MariaDBImage &	with_init_script (std::filesystem::path host_path)
	Queue a host file for /docker-entrypoint-initdb.d — runs once, on first boot, in REGISTRATION order (a zero-padded index prefix pins it), before start() returns.
MariaDBImage &	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).
MariaDBImage &	with_command_arg (std::string arg)
	Append one server option to the container command, e.g.
MariaDBImage &	with_command_args (std::vector< std::string > args)
	Append several server options at once — the batch twin of with_command_arg.
MariaDBImage &	with_config_file (std::filesystem::path host_cnf)
	Copy a .cnf file into /etc/mysql/conf.d (included by the image's configuration; the name must end in ".cnf" or this throws).
MariaDBImage &	with_env (std::string key, std::string value)
	Set an extra environment variable (e.g.
MariaDBImage &	with_label (std::string key, std::string value)
MariaDBImage &	with_network (std::string network)
	Join a user-defined network; peers resolve this container by name/alias at <alias>:3306 (kPort, not the mapped host port).
MariaDBImage &	with_network (const Network &network)
MariaDBImage &	with_network_alias (std::string alias)
MariaDBImage &	with_reuse (bool reuse=true)
	Enable container reuse (effective only when reuse is also enabled globally — see GenericImage::with_reuse).
MariaDBImage &	with_wait (WaitFor wait)
	REPLACE the default readiness probe with a custom strategy (the first call drops the module's probe; repeatable — further waits run in order under the same timeout).
MariaDBImage &	with_startup_timeout (std::chrono::milliseconds timeout)
	Replace the default 120s startup budget.
MariaDBImage &	with_startup_attempts (int n)
	Retry the whole create→start→wait sequence up to n times.
MariaDBImage &	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.
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 into a plain GenericImage (the drop-down escape hatch); same contract and validation as MySQLImage::to_generic.
MariaDBContainer	start () const
	Create, start, and wait until the image's healthcheck reports the real server ready (init scripts complete).

Static Public Attributes
static constexpr std::string_view	kDefaultImage = "mariadb:11"
	The pinned default image (the rolling LTS line).
static constexpr std::uint16_t	kPort = 3306
	The server port INSIDE the container.

Detailed Description

A reusable, copyable description of a MariaDB server container.

start() returns a MariaDBContainer handle owning the running container and exposing the connection getters.

Defaults mirror the MySQL module: user "test" / password "test" / database "test" (root shares the password), port 3306 published on an ephemeral host port. Readiness uses the probe the image itself ships — healthcheck.sh --connect --innodb_initialized — which needs no credentials and only reports ready once the REAL server (not the bootstrap instance that runs init scripts) accepts TCP connections, so init-script data is visible when start() returns.

Configuration is provisioned through the MARIADB_* environment contract; builder semantics are identical to MySQLImage's.

Constructor & Destructor Documentation

MariaDBImage()

testcontainers::modules::MariaDBImage::MariaDBImage

(

)

A config ready to start(): image mariadb:11, credentials test/test/test, port 3306 exposed, the image's own healthcheck.sh readiness probe, and a 120s startup budget (a first boot initializes the data directory and routinely takes tens of seconds on CI).

Member Function Documentation

with_image()

MariaDBImage & testcontainers::modules::MariaDBImage::with_image

(

const std::string &

reference

)

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

with_username()

MariaDBImage & testcontainers::modules::MariaDBImage::with_username

(

std::string

username

)

The user provisioned on first boot (default "test") with full privileges on database().

"root" (any letter case — stored lowercase, since the real account is 'root') provisions no separate user; the credential getters then describe root itself.

with_password()

MariaDBImage & testcontainers::modules::MariaDBImage::with_password ( std::string password )

inline

The password (default "test"); the same value becomes the root password.

Empty is only valid with with_username("root") (passwordless root via MARIADB_ALLOW_EMPTY_ROOT_PASSWORD); any other user with an empty password makes start() throw up front. Test credentials only: the value is visible via inspect.

with_database()

MariaDBImage & testcontainers::modules::MariaDBImage::with_database ( std::string database )

inline

The database created on first boot (default "test").

An empty name creates none and drops the path from connection_string().

with_init_script() [1/2]

MariaDBImage & testcontainers::modules::MariaDBImage::with_init_script

(

std::filesystem::path

host_path

)

Queue a host file for /docker-entrypoint-initdb.d — runs once, on first boot, in REGISTRATION order (a zero-padded index prefix pins it), before start() returns.

Recognized extensions: .sql, .sql.gz, .sql.xz, .sql.zst, .sh (anything else throws here, since the image would silently skip it); .sh ships executable. A reused (adopted) container does not re-run init scripts; editing one changes the reuse hash, so a fresh container is created.

with_init_script() [2/2]

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

MariaDBImage & testcontainers::modules::MariaDBImage::with_command_arg ( std::string arg )

inline

Append one server option to the container command, e.g.

with_command_arg("--character-set-server=utf8mb4"). Option arguments (starting with '-') are forwarded to mariadbd by the entrypoint. Do not change --port (the probe and port() assume 3306 inside the container).

with_command_args()

MariaDBImage & testcontainers::modules::MariaDBImage::with_command_args ( std::vector< std::string > args )

inline

Append several server options at once — the batch twin of with_command_arg.

Repeatable; calls accumulate in order.

with_config_file()

MariaDBImage & testcontainers::modules::MariaDBImage::with_config_file

(

std::filesystem::path

host_cnf

)

Copy a .cnf file into /etc/mysql/conf.d (included by the image's configuration; the name must end in ".cnf" or this throws).

Copied with mode 0644 — the server ignores world-writable config files.

with_env()

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

inline

Set an extra environment variable (e.g.

MARIADB_AUTO_UPGRADE). The managed MARIADB_* credential keys belong to the typed setters: the module applies them last, so they win over raw duplicates set here.

with_label()

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

inline

with_network() [1/2]

MariaDBImage & testcontainers::modules::MariaDBImage::with_network ( std::string network )

inline

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

with_network() [2/2]

MariaDBImage & testcontainers::modules::MariaDBImage::with_network

(

const Network &

network

)

with_network_alias()

MariaDBImage & testcontainers::modules::MariaDBImage::with_network_alias ( std::string alias )

inline

with_reuse()

MariaDBImage & testcontainers::modules::MariaDBImage::with_reuse ( bool reuse = true )

inline

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

Init scripts do not re-run on an adopted container: its data directory is already initialized.

with_wait()

MariaDBImage & testcontainers::modules::MariaDBImage::with_wait ( WaitFor wait )

inline

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

The default probe forces TCP for a reason: the image's first boot runs a temporary socket-only server while init scripts execute.

with_startup_timeout()

MariaDBImage & testcontainers::modules::MariaDBImage::with_startup_timeout ( std::chrono::milliseconds timeout )

inline

Replace the default 120s startup budget.

Image pull time does not count against it.

with_startup_attempts()

MariaDBImage & testcontainers::modules::MariaDBImage::with_startup_attempts ( int n )

inline

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

with_customizer()

MariaDBImage & testcontainers::modules::MariaDBImage::with_customizer ( std::function< void(GenericImage &)> customize )

inline

Register a callback that customizes the underlying GenericImage — the channel for every option this module does not surface.

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. Do not set the managed MARIADB_* credential env here: it would desync the credential getters and the DSN.

username()

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

inlinenoexcept

password()

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

inlinenoexcept

database()

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

inlinenoexcept

to_generic()

GenericImage testcontainers::modules::MariaDBImage::to_generic

(

)

const

Render the full configuration into a plain GenericImage (the drop-down escape hatch); same contract and validation as MySQLImage::to_generic.

start()

MariaDBContainer testcontainers::modules::MariaDBImage::start

(

)

const

Create, start, and wait until the image's healthcheck reports the real server ready (init scripts complete).

Throws Error on config errors, DockerError on daemon failures, StartupTimeoutError when readiness never arrives — also the symptom of a failing init script (check the container logs).

Member Data Documentation

kDefaultImage

std::string_view testcontainers::modules::MariaDBImage::kDefaultImage = "mariadb:11"

staticconstexpr

The pinned default image (the rolling LTS line).

Override with with_image; any image honoring the official env contract (MARIADB_ROOT_PASSWORD / MARIADB_USER / MARIADB_PASSWORD / MARIADB_DATABASE, /docker-entrypoint-initdb.d) works.

kPort

std::uint16_t testcontainers::modules::MariaDBImage::kPort = 3306

staticconstexpr

The server port INSIDE the container.

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