OpenParable
Skip to content
← Back to skills

Mz Run

Development
mz-run

Mz Run is an Agent Skill for development published in the MaterializeInc/materialize repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Trigger: "run Materialize locally", "start environmentd", "check compilation", "format code", "lint", "cargo check", "cargo fmt", "cargo clippy", "bin/fmt", "bin/lint", or mentions compiling, building, running, formatting, linting, log filters, jemalloc, CockroachDB setup in Materialize. Also "how do I run this" or "it won't compile".

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/MaterializeInc/materialize/blob/HEAD/.agents/skills/mz-run/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/mz-run, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Developing Materialize

Compiling

Check compilation with cargo check. Do not use cargo build or cargo run to build or run Materialize. Use bin/environmentd --build-only to build without running.

Running locally

Start Materialize using bin/environmentd --optimized. Pass --reset to delete data from prior runs (clears the mzdata directory and resets Postgres schemas), useful when testing catalog changes or starting fresh.

Access Materialize using psql:

  • psql -p 6875 -h localhost -U materialize for regular access.
  • psql -p 6877 -h localhost -U mz_system for system access.

If it fails because CockroachDB is not running, start it:

docker run --name=cockroach -d -p 26257:26257 -p 26258:8080 \
  cockroachdb/cockroach:latest start-single-node --insecure --store=type=mem,size=2G

If the container already exists, use docker start cockroach instead.

Other useful flags:

  • --tokio-console — activate the Tokio console for debugging async tasks.
  • --coverage — build with coverage instrumentation.
  • --sanitizer address|memory|thread — build with the specified sanitizer.

Formatting and linting

Format Rust, Python, and Protobuf files with bin/fmt. Takes no file arguments — it always formats the whole tree (only flag: --check). Run bin/lint to check for lint errors. Run cargo clippy --all-targets -- -D warnings to check for Rust-specific warnings.

Log filters

Set MZ_LOG_FILTER to a tracing-compatible filter expression. For example, mz_adapter::catalog::apply=trace,warn would enable trace logging for the mz-adapter crate's catalog::apply module, and warn for the rest of the system.

jemalloc

On Linux, we link against jemalloc by default. Compile with --no-default-features to use the system allocator.