testcontainers::modules::MySQLImage Class Reference

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

#include <testcontainers/modules/MySQL.hpp>

Public Member Functions
	MySQLImage ()
	A config ready to start(): image mysql:8.4, credentials test/test/test, port 3306 exposed, a TCP-forced mysqladmin ping readiness probe, and a 120s startup budget (a first boot initializes the data directory and routinely takes tens of seconds on CI).
MySQLImage &	with_image (const std::string &reference)
	Override the pinned image with a full reference "name[:tag]" (tag defaults to "latest").
MySQLImage &	with_username (std::string username)
	The user the server is provisioned with (default "test"), created on first boot with full privileges on database().
MySQLImage &	with_password (std::string password)
	The password (default "test").
MySQLImage &	with_database (std::string database)
	The database created on first boot (default "test"); username() is granted all privileges on it.
MySQLImage &	with_init_script (std::filesystem::path host_path)
	Queue a host file for /docker-entrypoint-initdb.d.
MySQLImage &	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).
MySQLImage &	with_command_arg (std::string arg)
	Append one server option to the container command, e.g.
MySQLImage &	with_command_args (std::vector< std::string > args)
	Append several server options at once — the batch twin of with_command_arg.
MySQLImage &	with_config_file (std::filesystem::path host_cnf)
	Copy a configuration file into /etc/mysql/conf.d, which the image's my.cnf includes.
MySQLImage &	with_env (std::string key, std::string value)
	Set an extra environment variable — image switches beyond the typed setters.
MySQLImage &	with_label (std::string key, std::string value)
MySQLImage &	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).
MySQLImage &	with_network (const Network &network)
MySQLImage &	with_network_alias (std::string alias)
MySQLImage &	with_reuse (bool reuse=true)
	Enable container reuse (effective only when reuse is also enabled globally — see GenericImage::with_reuse).
MySQLImage &	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).
MySQLImage &	with_startup_timeout (std::chrono::milliseconds timeout)
	Replace the default 120s startup budget.
MySQLImage &	with_startup_attempts (int n)
	Retry the whole create→start→wait sequence up to n times.
MySQLImage &	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, memory limits, 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 matrix, staged copies, command args, 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 MySQLContainer.
MySQLContainer	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 = "mysql:8.4"
	The pinned default image (the LTS line).
static constexpr std::uint16_t	kPort = 3306
	The server port INSIDE the container.

Detailed Description

A reusable, copyable description of a MySQL server container.

start() returns a MySQLContainer handle that owns the running container and exposes the connection getters (host, port, credentials, URL).

Out of the box the server is provisioned with user "test" / password "test" / database "test" (root shares the same password), publishes port 3306 on an ephemeral host port, and start() returns only once the server accepts TCP connections — by which point any registered init scripts have already run, so the data they create is visible from the first query.

The with_* builders mutate in place and return *this by reference, 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.

Constructor & Destructor Documentation

MySQLImage()

testcontainers::modules::MySQLImage::MySQLImage

(

)

A config ready to start(): image mysql:8.4, credentials test/test/test, port 3306 exposed, a TCP-forced mysqladmin ping 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()

MySQLImage & testcontainers::modules::MySQLImage::with_image

(

const std::string &

reference

)

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

with_username()

MySQLImage & testcontainers::modules::MySQLImage::with_username

(

std::string

username

)

The user the server is provisioned with (default "test"), created on first boot with full privileges on database().

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

with_password()

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

inline

The password (default "test").

The SAME value also becomes the root password, so tests always hold a known superuser. An empty password is only valid together with with_username("root") (passwordless root); any other user with an empty password makes start() throw up front instead of booting an image that would refuse to start. Test credentials only: the value is visible via inspect.

with_database()

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

inline

The database created on first boot (default "test"); username() is granted all privileges on it.

An empty name creates no database (and drops the path segment from connection_string()) — connect as root and manage schemas yourself.

with_init_script() [1/2]

MySQLImage & testcontainers::modules::MySQLImage::with_init_script

(

std::filesystem::path

host_path

)

Queue a host file for /docker-entrypoint-initdb.d.

Init scripts run ONCE, on the container's first boot, in REGISTRATION order (the module prefixes each container-side name with a zero-padded index — the image runs files in name order), and they complete before start() returns. The extension picks the execution mode and must be one the image knows — .sql, .sql.gz, .sql.xz, .sql.zst, or .sh (anything else throws here rather than being silently skipped). .sh ships executable so it runs as a standalone script. 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]

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

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

inline

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

with_command_arg("--character-set-server=utf8mb4"). The image's entrypoint forwards option arguments (starting with '-') to mysqld. Do not change --port here: the readiness probe and port() assume the in-container port stays 3306. Note for pre-8.0-era client stacks: MySQL 8.4 disables the mysql_native_password plugin by default — re-enable it with with_command_arg("--mysql-native-password=ON") plus an init script altering your user to that plugin.

with_command_args()

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

MySQLImage & testcontainers::modules::MySQLImage::with_config_file

(

std::filesystem::path

host_cnf

)

Copy a configuration file into /etc/mysql/conf.d, which the image's my.cnf includes.

The file name must end in ".cnf" (the include glob; anything else throws here). Copied with mode 0644 — the server ignores world-writable config files. Add several to layer several.

with_env()

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

inline

Set an extra environment variable — image switches beyond the typed setters.

The managed MYSQL_* credential keys belong to with_username/with_password/with_database: the module applies them last, so they win over raw duplicates set here.

with_label()

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

inline

with_network() [1/2]

MySQLImage & testcontainers::modules::MySQLImage::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]

MySQLImage & testcontainers::modules::MySQLImage::with_network

(

const Network &

network

)

with_network_alias()

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

inline

with_reuse()

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

MySQLImage & testcontainers::modules::MySQLImage::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).

Note 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()

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

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

inline

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

with_customizer()

MySQLImage & testcontainers::modules::MySQLImage::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 (mounts, memory limits, 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. Do not set the managed MYSQL_* credential env here: it would desync the credential getters, the DSN, and the readiness probe.

username()

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

inlinenoexcept

password()

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

inlinenoexcept

database()

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

inlinenoexcept

to_generic()

GenericImage testcontainers::modules::MySQLImage::to_generic

(

)

const

Render the full configuration — credential env matrix, staged copies, command args, 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 MySQLContainer.

Throws Error on an invalid config (empty username; empty password with a non-root user) before any daemon contact.

start()

MySQLContainer testcontainers::modules::MySQLImage::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, DockerError on daemon failures, and StartupTimeoutError when readiness never arrives — which is also how a FAILING init script surfaces (the server exits and the budget runs out); check the container logs when diagnosing one.

Member Data Documentation

kDefaultImage

std::string_view testcontainers::modules::MySQLImage::kDefaultImage = "mysql:8.4"

staticconstexpr

The pinned default image (the LTS line).

Override with with_image; any image honoring the official env contract (MYSQL_ROOT_PASSWORD / MYSQL_USER / MYSQL_PASSWORD / MYSQL_DATABASE, /docker-entrypoint-initdb.d) works too, e.g. percona variants.

kPort

std::uint16_t testcontainers::modules::MySQLImage::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 MySQLContainer::port() (the mapped host port) instead.