testcontainers::modules::ScyllaDBImage Class Reference

A reusable, copyable description of a single-node ScyllaDB server for tests: CQL on port 9042, developer mode, one shard, no authentication — the vendor-recommended CI shape, typically CQL-ready in seconds. More...

#include <testcontainers/modules/ScyllaDB.hpp>

Public Member Functions
	ScyllaDBImage ()
	A config ready to start(): pinned image, port 9042 exposed, managed flags --developer-mode=1 --overprovisioned=1 --smp 1 --memory 512M, readiness = the CQL-listening log line followed by an in-container cqlsh query, and a 120s startup budget (a first boot initializes the data directory).
ScyllaDBImage &	with_image (const std::string &reference)
	Override the pinned image with a full reference "name[:tag]" (tag defaults to "latest").
ScyllaDBImage &	with_smp (int shards)
	Number of CPU shards (--smp).
ScyllaDBImage &	with_memory (std::string amount)
	Total server memory (--memory), in Seastar's size format — "512M", "2G".
ScyllaDBImage &	with_datacenter (std::string name)
	Datacenter name the node reports (--dc; the flag also switches the node's snitch so the name takes effect).
ScyllaDBImage &	with_command_args (std::vector< std::string > args)
	Append entrypoint arguments (e.g.
ScyllaDBImage &	with_command_arg (std::string arg)
	Single-argument twin of with_command_args (same placement rules).
ScyllaDBImage &	with_init_script (std::filesystem::path host_path)
	Queue a .cql script the module runs through the in-container cqlsh AFTER the node is ready (ScyllaDB has no initdb.d), in REGISTRATION order.
ScyllaDBImage &	with_init_script (const std::string &name, std::string content)
	In-memory variant: queue content under the given file name (a bare .cql name, no directories; same ordering as above).
ScyllaDBImage &	with_env (std::string key, std::string value)
	Set an extra container environment variable (TZ and tooling — ScyllaDB's docker configuration is flag-based, so server options go through the typed setters and with_command_args).
ScyllaDBImage &	with_label (std::string key, std::string value)
ScyllaDBImage &	with_network (std::string network)
	Join a user-defined network; peers resolve this container by name/alias at <alias>:9042 (kPort, not the mapped host port).
ScyllaDBImage &	with_network (const Network &network)
ScyllaDBImage &	with_network_alias (std::string alias)
ScyllaDBImage &	with_reuse (bool reuse=true)
	Enable container reuse (effective only when reuse is also enabled globally — see GenericImage::with_reuse).
ScyllaDBImage &	with_wait (WaitFor wait)
	REPLACE the default readiness pair — the CQL-listening log line, then an in-container cqlsh query — with a custom strategy (the first call drops the module's probes; repeatable — further waits run in order under the same timeout).
ScyllaDBImage &	with_startup_timeout (std::chrono::milliseconds timeout)
	Budget for the readiness phase (default: 120s — a first boot initializes the data directory and routinely takes tens of seconds on loaded CI).
ScyllaDBImage &	with_startup_attempts (int n)
	Retry the whole create→start→wait sequence up to n times.
ScyllaDBImage &	with_customizer (std::function< void(GenericImage &)> customize)
	Register a callback that customizes the underlying GenericImage — the channel for options this module does not surface (mounts, extra ports such as the shard-aware 19042, pull policy, ...).
int	smp () const noexcept
const std::string &	memory () const noexcept
const std::string &	datacenter () const noexcept
	The datacenter the started node will report ("datacenter1" unless with_datacenter was called).
GenericImage	to_generic () const
	Render the full configuration — managed flags, init-script copies and their post-ready hook, readiness pair, customizers — into a plain GenericImage: the drop-down escape hatch when you need a raw core Container instead of a ScyllaDBContainer.
ScyllaDBContainer	start () const
	Create, start, wait until the node answers CQL, then run any init scripts.

Static Public Attributes
static constexpr std::string_view	kDefaultImage = "scylladb/scylla:2026.1"
	The pinned default image — the current LTS line (the tag floats over its patch releases).
static constexpr std::uint16_t	kPort = 9042
	The CQL port INSIDE the container: peers on a shared docker network connect to <alias-or-name>:kPort; the test process itself uses ScyllaDBContainer::port() (the mapped host port) instead.

Detailed Description

A reusable, copyable description of a single-node ScyllaDB server for tests: CQL on port 9042, developer mode, one shard, no authentication — the vendor-recommended CI shape, typically CQL-ready in seconds.

start() waits until the node answers CQL and returns a ScyllaDBContainer whose getters feed any Cassandra-compatible driver; no client library is required or linked.

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

ScyllaDBImage()

testcontainers::modules::ScyllaDBImage::ScyllaDBImage

(

)

A config ready to start(): pinned image, port 9042 exposed, managed flags --developer-mode=1 --overprovisioned=1 --smp 1 --memory 512M, readiness = the CQL-listening log line followed by an in-container cqlsh query, and a 120s startup budget (a first boot initializes the data directory).

Member Function Documentation

with_image()

ScyllaDBImage & testcontainers::modules::ScyllaDBImage::with_image

(

const std::string &

reference

)

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

with_smp()

ScyllaDBImage & testcontainers::modules::ScyllaDBImage::with_smp

(

int

shards

)

Number of CPU shards (--smp).

Default 1 — the CI-friendly shape; budget about 512M of with_memory per shard when raising it. Values below 1 throw at start(), before any daemon contact.

with_memory()

ScyllaDBImage & testcontainers::modules::ScyllaDBImage::with_memory

(

std::string

amount

)

Total server memory (--memory), in Seastar's size format — "512M", "2G".

Default "512M", fine for one shard. Empty throws at start().

with_datacenter()

ScyllaDBImage & testcontainers::modules::ScyllaDBImage::with_datacenter

(

std::string

name

)

Datacenter name the node reports (--dc; the flag also switches the node's snitch so the name takes effect).

Default: unset — the node reports "datacenter1". Useful when testing DC-aware load balancing; the started handle's datacenter() getter mirrors it. Empty throws at start().

with_command_args()

ScyllaDBImage & testcontainers::modules::ScyllaDBImage::with_command_args

(

std::vector< std::string >

args

)

Append entrypoint arguments (e.g.

{"--rack", "r1"}), placed AFTER the managed flags; the entrypoint keeps the LAST occurrence of a flag, so your value wins on a duplicate. Two flags belong elsewhere: --dc to with_datacenter (a raw duplicate desyncs the datacenter() getter), and --authenticator breaks the module's authless readiness probe — pair it with with_wait.

with_command_arg()

ScyllaDBImage & testcontainers::modules::ScyllaDBImage::with_command_arg

(

std::string

arg

)

Single-argument twin of with_command_args (same placement rules).

with_init_script() [1/2]

ScyllaDBImage & testcontainers::modules::ScyllaDBImage::with_init_script

(

std::filesystem::path

host_path

)

Queue a .cql script the module runs through the in-container cqlsh AFTER the node is ready (ScyllaDB has no initdb.d), in REGISTRATION order.

Only the .cql extension is accepted — anything else throws here. A failing script fails start(); each statement is bounded by cqlsh's own request timeout. The file is read when start() copies it.

A reused (adopted) container does NOT re-run scripts — its data is already seeded; an edited script changes the reuse hash, so the next start() builds a fresh container.

with_init_script() [2/2]

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

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

with_env()

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

Set an extra container environment variable (TZ and tooling — ScyllaDB's docker configuration is flag-based, so server options go through the typed setters and with_command_args).

with_label()

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

with_network() [1/2]

ScyllaDBImage & testcontainers::modules::ScyllaDBImage::with_network

(

std::string

network

)

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

with_network() [2/2]

ScyllaDBImage & testcontainers::modules::ScyllaDBImage::with_network

(

const Network &

network

)

with_network_alias()

ScyllaDBImage & testcontainers::modules::ScyllaDBImage::with_network_alias

(

std::string

alias

)

with_reuse()

ScyllaDBImage & testcontainers::modules::ScyllaDBImage::with_reuse

(

bool

reuse = true

)

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

An adopted node skips the boot and keeps its data; init scripts are not re-run.

with_wait()

ScyllaDBImage & testcontainers::modules::ScyllaDBImage::with_wait

(

WaitFor

wait

)

REPLACE the default readiness pair — the CQL-listening log line, then an in-container cqlsh query — with a custom strategy (the first call drops the module's probes; repeatable — further waits run in order under the same timeout).

with_startup_timeout()

ScyllaDBImage & testcontainers::modules::ScyllaDBImage::with_startup_timeout

(

std::chrono::milliseconds

timeout

)

Budget for the readiness phase (default: 120s — a first boot initializes the data directory and routinely takes tens of seconds on loaded CI).

Init scripts run after readiness through the exec transport and are not under this budget; image pull time does not count either.

with_startup_attempts()

ScyllaDBImage & testcontainers::modules::ScyllaDBImage::with_startup_attempts

(

int

n

)

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

with_customizer()

ScyllaDBImage & testcontainers::modules::ScyllaDBImage::with_customizer

(

std::function< void(GenericImage &)>

customize

)

Register a callback that customizes the underlying GenericImage — the channel for options this module does not surface (mounts, extra ports such as the shard-aware 19042, 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. A wait added here runs IN ADDITION to the default probe (unlike with_wait); a wholesale with_cmd drops the managed flags — prefer with_command_args.

smp()

int testcontainers::modules::ScyllaDBImage::smp ( ) const

inlinenoexcept

memory()

const std::string & testcontainers::modules::ScyllaDBImage::memory ( ) const

inlinenoexcept

datacenter()

const std::string & testcontainers::modules::ScyllaDBImage::datacenter ( ) const

inlinenoexcept

The datacenter the started node will report ("datacenter1" unless with_datacenter was called).

to_generic()

GenericImage testcontainers::modules::ScyllaDBImage::to_generic

(

)

const

Render the full configuration — managed flags, init-script copies and their post-ready hook, readiness pair, customizers — into a plain GenericImage: the drop-down escape hatch when you need a raw core Container instead of a ScyllaDBContainer.

Throws Error on an invalid config (smp below 1, empty memory or datacenter) before any daemon contact.

start()

ScyllaDBContainer testcontainers::modules::ScyllaDBImage::start

(

)

const

Create, start, wait until the node answers CQL, then run any init scripts.

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::ScyllaDBImage::kDefaultImage = "scylladb/scylla:2026.1"

staticconstexpr

The pinned default image — the current LTS line (the tag floats over its patch releases).

The image is source-available (free tier: 10 TB / 50 vCPUs per organization — a test container is far inside; CI and automated-testing use is explicitly permitted for commercial ScyllaDB customers too). Override with with_image; any tag with the same entrypoint contract works — scylladb/scylla:6.2 is the last AGPL-licensed open-source release.

kPort

std::uint16_t testcontainers::modules::ScyllaDBImage::kPort = 9042

staticconstexpr

The CQL port INSIDE the container: peers on a shared docker network connect to <alias-or-name>:kPort; the test process itself uses ScyllaDBContainer::port() (the mapped host port) instead.