Implementation:MaterializeInc Materialize Scenario Run

Knowledge Sources	misc/python/materialize/checks/scenarios.py, misc/python/materialize/checks/mzcompose_actions.py
Domains	Upgrade Testing, Orchestration, Python API
Last Updated	2026-02-08

Overview

Concrete execution engine for upgrade scenarios provided by Scenario.run() and the StartMz/KillMz/WaitReadyMz action classes in the Materialize platform-checks framework.

Description

The execution implementation consists of two cooperating components:

1. Scenario.run() (in scenarios.py, lines 86–111):

The run() method retrieves the action list from self.actions() and performs implicit enrichment before executing:

• If the first action is not a StartMz, a ConfigureMz action is prepended (for cloud scenarios).
• After every StartMz action (that does not use a deploy generation), a ConfigureMz action and a SetupSqlServerTesting action are inserted to set system limits, grant permissions, and configure test connections.
• After every ReplaceEnvironmentdStatefulSet action, a ConfigureMz is inserted.

It then iterates through the enriched action list, calling action.execute(self.executor) followed by action.join(self.executor) for each action in strict sequential order.

2. StartMz (in mzcompose_actions.py, lines 35–139):

The StartMz action launches a Materialize instance through the mzcompose composition framework. It:

• Constructs a Materialized service configuration with the specified Docker image tag, system parameters, healthcheck, deploy generation, and other options.
• Calls c.up() to start the Docker container.
• If a deploy generation is set (preflight/0dt mode), returns immediately without connecting.
• Otherwise, sets up SSH tunnel test connections and verifies that the running Materialize version matches the expected tag or the current cargo version.
• Updates e.current_mz_version on the executor so downstream actions know the active version.

3. KillMz (in mzcompose_actions.py, lines 219–235):

Stops a running Materialize instance via c.kill(), optionally capturing logs before shutdown (important for preserving pre-upgrade logs that would otherwise be lost when the container is replaced).

4. WaitReadyMz (in mzcompose_actions.py, lines 366–375):

Waits for a Materialize instance started in preflight mode to reach READY_TO_PROMOTE status, polling the deployment status API.

Usage

Use Scenario.run() as the top-level entry point for executing any upgrade scenario. The method handles all orchestration details internally. Use StartMz, KillMz, and WaitReadyMz when composing custom scenario action lists.

Code Reference

Source Location

• misc/python/materialize/checks/scenarios.py, lines 86–111 (Scenario.run()).
• misc/python/materialize/checks/mzcompose_actions.py, lines 35–139 (StartMz), lines 219–235 (KillMz), lines 366–375 (WaitReadyMz).

Signature

Scenario.run():

class Scenario:
    def run(self) -> None: ...

StartMz:

class StartMz(MzcomposeAction):
    def __init__(
        self,
        scenario: "Scenario",
        tag: MzVersion | None = None,
        environment_extra: list[str] = [],
        system_parameter_defaults: dict[str, str] | None = None,
        additional_system_parameter_defaults: dict[str, str] = {},
        system_parameter_version: MzVersion | None = None,
        mz_service: str | None = None,
        platform: str | None = None,
        healthcheck: list[str] | None = None,
        deploy_generation: int | None = None,
        restart: str | None = None,
        force_migrations: str | None = None,
        publish: bool | None = None,
    ) -> None: ...

    def execute(self, e: Executor) -> None: ...

KillMz:

class KillMz(MzcomposeAction):
    def __init__(
        self,
        mz_service: str = "materialized",
        capture_logs: bool = False,
    ) -> None: ...

    def execute(self, e: Executor) -> None: ...

WaitReadyMz:

class WaitReadyMz(MzcomposeAction):
    def __init__(self, mz_service: str = "materialized") -> None: ...

    def execute(self, e: Executor) -> None: ...

Import

from materialize.checks.scenarios import Scenario
from materialize.checks.mzcompose_actions import StartMz, KillMz, WaitReadyMz

I/O Contract

Inputs

Parameter	Type	Description
scenario (on StartMz)	Scenario	The parent scenario, used to access features (e.g., Azurite) and base version.
tag (on StartMz)	None	Docker image tag for the version to start. None means use the current source build.
capture_logs (on KillMz)	bool	Whether to capture container logs before killing (prevents log loss on container replacement).
deploy_generation (on StartMz)	None	If set, starts Materialize in preflight/read-only mode at this generation number.

Outputs

Method	Side Effect	Description
Scenario.run()	Executes all actions	Runs the complete scenario from start to finish; raises on failure.
StartMz.execute()	Starts Mz container, updates e.current_mz_version	Launches Materialize and verifies version identity.
KillMz.execute()	Stops Mz container	Kills the Materialize process and optionally captures logs.
WaitReadyMz.execute()	Blocks until ready	Polls the deployment status API until READY_TO_PROMOTE.

Usage Examples

Running a complete upgrade scenario:

from materialize.checks.scenarios_upgrade import UpgradeEntireMz
from materialize.checks.executors import MzcomposeExecutor

executor = MzcomposeExecutor(composition)
scenario = UpgradeEntireMz(
    checks=all_check_classes,
    executor=executor,
    features=features,
)
scenario.run()  # Executes: StartMz(old) -> Initialize -> Manipulate(1) -> KillMz -> StartMz(new) -> Manipulate(2) -> Validate -> ...

Using StartMz in a zero-downtime upgrade:

from materialize.checks.mzcompose_actions import StartMz, KillMz, WaitReadyMz
from materialize.checks.scenarios_upgrade import start_mz_read_only

actions = [
    StartMz(self, tag=old_version),
    Initialize(self),
    KillMz(capture_logs=True),
    start_mz_read_only(self, tag=None, deploy_generation=1),
    WaitReadyMz(),
    PromoteMz(),
    Validate(self),
]

Related Pages

Implements Principle

• Principle:MaterializeInc_Materialize_Upgrade_Scenario_Execution