Implementation:MaterializeInc Materialize Zero Downtime Upgrader
| Knowledge Sources | |
|---|---|
| Domains | Upgrade Management, Testing, High Availability |
| Last Updated | 2026-02-08 00:00 GMT |
Overview
The Zero Downtime Upgrader module generates and executes zero-downtime (0dt) upgrade paths between Materialize versions using alternating service instances with shared metadata stores.
Description
This module provides utilities for testing zero-downtime upgrades of Materialize. The generate_materialized_upgrade_args() function constructs a list of MaterializedUpgradeArgs typed dicts that configure alternating mz_1 and mz_2 services with incrementing deploy generations, shared external metadata stores, and on-failure restart policies. The generate_random_upgrade_path() function creates randomized upgrade sequences between version lists. The UpgradeStep dataclass pairs a new service with its predecessor and an upgrade callable. System parameter defaults are derived from the first (oldest) version to avoid backwards-compatibility issues with cutting-edge features.
Usage
Use this module when testing Materialize version upgrade paths, particularly zero-downtime upgrades that cycle between two service instances sharing a common metadata store. It is used by mzcompose-based upgrade test scenarios.
Code Reference
Source Location
- Repository: MaterializeInc_Materialize
- File: misc/python/materialize/mz_0dt_upgrader.py
Signature
class MaterializedUpgradeArgs(TypedDict):
name: str
image: str | None
deploy_generation: int
system_parameter_defaults: dict[str, str]
external_metadata_store: bool
restart: str
@dataclass
class UpgradeStep:
new_service: Materialized
previous_service: Materialized
upgrade: Callable[[], None]
def generate_materialized_upgrade_args(
versions: list[MzVersion | None],
) -> list[MaterializedUpgradeArgs]: ...
def generate_random_upgrade_path(
versions: list[MzVersion],
rng: Random | None = None,
) -> list[MzVersion]: ...
Import
from materialize.mz_0dt_upgrader import (
generate_materialized_upgrade_args,
generate_random_upgrade_path,
MaterializedUpgradeArgs,
UpgradeStep,
)
I/O Contract
| Input | Type | Description |
|---|---|---|
| versions | None] | Ordered list of Materialize versions (None for current source build)
|
| rng | None | Optional random number generator for path randomization |
| Output | Type | Description |
|---|---|---|
| upgrade_args | list[MaterializedUpgradeArgs] |
Service configurations alternating between mz_1 and mz_2 with incrementing generations |
| upgrade_path | list[MzVersion] |
Randomized version sequence for upgrade testing |
Usage Examples
from materialize.mz_0dt_upgrader import generate_materialized_upgrade_args
from materialize.mz_version import MzVersion
versions = [MzVersion.parse_mz("v0.78.0"), MzVersion.parse_mz("v0.79.0"), None]
args = generate_materialized_upgrade_args(versions)
# args[0]: mz_1, generation=0, image="materialize/materialized:v0.78.0"
# args[1]: mz_2, generation=1, image="materialize/materialized:v0.79.0"
# args[2]: mz_1, generation=2, image=None (current source)