Module script 

Executes a text command script against clusterd.

Instead of recompiling a Rust scenario, a test (or an agent) writes a crate::text script: a sequence of commands, each with an expected output block (----) that is the assertion. The coarse orchestration verbs map almost directly to Driver calls; define carries arbitrary MIR (as pretty-form specs parsed by mz-expr-parser, the .spec test syntax) over the full DataflowBuilder surface, including index imports, while define_index stays as sugar for the common single-index shape. Explicit write_rows payloads are typed against the schema token-by-token via cell_from_token (reusing mz_repr::strconv) rather than Row’s opaque serde.

Execution

run parses the script, executes each command, and compares its golden output to the expected block — failing the run on a mismatch, or rewriting the file when REWRITE is set. A command that fails renders as error: <message>, so an expected failure is asserted by its golden block. Assertions are level-triggered waits on monotonic frontiers, so a single sequential script is deterministic regardless of how the dataflows interleave.

Shards are referenced by a string alias; the first command naming an alias allocates a fresh ShardId for it. Object ids are raw u64s mapped to GlobalId::User.

Structs

BuildSpec

A MIR object to build in a define command.

ColumnSpec

A column declaration in a define_schema command.

ConfigSetting

A single dyncfg update in an update-configuration command: a config name, a type tag selecting how value is parsed (bool/u32/usize/f64/string/ duration), and the value. Typed against mz_dyncfg at execution.

IndexEntry 🔒

What the registry remembers about an exported index, so a later define import or count assertion can reconstruct the import without re-declaring it.

ScriptState

Mutable state threaded through a script run.

Enums

Command

A command read from the script stream.

ExportSpec

An export in a create-dataflow command, mirroring the export kinds a real dataflow produces (see mz_compute_types::sinks::ComputeSinkConnection). copy-to is intentionally absent: the parser rejects it as unimplemented.

ImportSpec

A collection to import in a define command: a persist source or an existing index. Externally tagged: {"source": {…}} or {"index": {…}}.

Constants

DEFAULT_ROW_BYTES 🔒

The default payload padding (bytes) for synthetic rows when a command omits it.

DEFAULT_TIMEOUT_SECS 🔒

The default timeout (seconds) for await_frontier when a command omits it.

INTERNAL_ID_BASE 🔒

The base for ephemeral global ids the count sugar allocates. Far above any id a script would use, so its dataflows never collide with user objects.

Functions

cell_from_token 🔒

Type a raw row-value token against its column into an owned Cell.

parse_config_val 🔒

Parse a configuration value string into a ConfigVal, selecting the variant by a type tag. Each numeric/bool/duration type reuses mz_dyncfg’s own ConfigType::parse (so the accepted syntax — e.g. on/off for bool, humantime for duration — matches the rest of the codebase); string is taken verbatim.

register_catalog_object 🔒

Register a referenceable object in the parser catalog under its global-id name (e.g. u1000), recording the name-to-id mapping so the parsed Gets — which carry the catalog’s own assigned ids — can be remapped back to the script’s ids.

relation_desc 🔒

Build a RelationDesc from column specs.

remap_gets 🔒

Rewrite every global Get in expr from the catalog’s assigned id back to the script’s id, looked up by the object’s name.

render_rows 🔒

Render peeked rows as deterministic golden text: each row’s datums joined by spaces, with the rows sorted so the output is independent of arrangement order.

render_updates 🔒

Render a subscribe’s updates as golden text: <ts> <diff> <datums> per line. Updates are consolidated by (time, row) — so split batches and retractions collapse — net-zero rows dropped, and the lines sorted for determinism.

rows_from_tokens 🔒

Pack explicit row tokens against desc, validating arity per row.

run

Run a script: parse content into stanzas, execute each command, and either compare its output to the stanza’s expected block or — when REWRITE is set and path is given — rewrite the file in place with the actual outputs.

scalar_type_from_str 🔒

Map a JSON type name to a SqlScalarType. The supported set is intentionally small and matches crate::data::Cell; extend both together.

unquote 🔒

Strip surrounding double quotes from a token, if present.

up_to_antichain 🔒

Convert an optional up_to timestamp into a sink’s exclusive upper antichain; None is the empty antichain (no bound — the sink runs indefinitely).