Implementation:MaterializeInc Materialize CLI Workload Capture
| Knowledge Sources | |
|---|---|
| Domains | CLI, Testing, Workload Analysis |
| Last Updated | 2026-02-08 00:00 GMT |
Overview
The CLI Workload Capture tool connects to a live Materialize instance and captures its complete workload definition (schemas, objects, queries, source statistics) into a YAML file for replay testing.
Description
This module provides the mz-workload-capture CLI that introspects a running Materialize instance via SQL queries to capture its full workload fingerprint. It extracts database schemas, table definitions with column types and defaults, source configurations, connection details, cluster layouts, materialized views, sinks, and recent query patterns. The captured workload is enriched with source statistics and serialized to a YAML file compatible with the workload replay framework. Query execution supports configurable timeouts with cancel timers.
Usage
Use this tool to capture a snapshot of a Materialize environment's workload for subsequent replay testing, performance benchmarking, or regression analysis.
Code Reference
Source Location
- Repository: MaterializeInc_Materialize
- File: misc/python/materialize/cli/mz_workload_capture.py
Signature
def main() -> int: ...
def query(
conn: psycopg.Connection,
sql: LiteralString | bytes | SQL | Composed,
timeout: int | None = None,
) -> list[Any]: ...
def attach_source_statistics(conn: psycopg.Connection, workload: dict) -> None: ...
def to_sql_string(q: bytes | SQL | Composable | LiteralString, conn) -> str: ...
@contextmanager
def timed(label: str, *, width: int = 52): ...
Import
from materialize.cli.mz_workload_capture import main
I/O Contract
| Input | Type | Description |
|---|---|---|
| Materialize connection | psycopg.Connection |
Live connection to a Materialize instance |
| --verbose | bool |
Enable verbose SQL logging |
| --timeout | int |
Query timeout in seconds |
| Output | Type | Description |
|---|---|---|
| workload.yml | YAML file | Complete workload definition including databases, schemas, tables, sources, queries, and statistics |
Usage Examples
# Capture workload from a Materialize instance
mz-workload-capture --host localhost --port 6875 -o workload.yml