Add mz-deploy documentation by sjwiesman · Pull Request #37052 · MaterializeInc/materialize

sjwiesman · 2026-06-15T20:04:59Z

Adds user-facing documentation for mz-deploy, the declarative SQL project
deployment tool, under doc/user/content/manage/mz-deploy/.

What's here

Get started — quickstart covering project creation, connection profiles, compile, and the deploy lifecycle.
Installation — macOS/Linux tabs that download the latest release tarball from binaries.materialize.com and extract it into /usr/local, following the existing mz-debug install pattern. The architecture is resolved at runtime via uname -m, so a single command covers Apple Silicon (arm64) and Intel macs as well as x86_64/aarch64 Linux.
Project structure, infrastructure, local development, deployments, stable APIs, profiles — reference pages for the full workflow.
Editor setup — VS Code, Neovim, and Helix integration.
AI agent setup — Claude Code and Codex configuration, including a new Claude Code on the web section explaining how to install mz-deploy into the Anthropic-managed cloud sandbox via its Setup script field. The sandbox is always Linux and runs as root, so the script uses the unknown-linux-gnu build, resolves the architecture at runtime, and needs no sudo. The section also notes the Trusted vs None network-mode constraint and points users at committing .claude/settings.json so the language server carries over to cloud sessions.

Notes

Documentation only — no code changes, so no Rust/Python lint or test steps apply.

🤖 Generated with Claude Code

Replace the placeholder installation note in the mz-deploy get-started guide with real instructions: macOS/Linux tabs that download the latest release tarball from binaries.materialize.com and extract it into /usr/local, following the existing mz-debug install pattern. Resolve the architecture at runtime via `uname -m` so a single command covers both Apple Silicon (arm64) and Intel macs as well as x86_64/aarch64 Linux. Add a "Claude Code on the web" section to the AI agent setup guide covering how to install mz-deploy into the Anthropic-managed cloud sandbox via its Setup script field. The sandbox is always Linux and runs as root, so the script uses the unknown-linux-gnu build, resolves the architecture at runtime, and needs no sudo. Also note the Trusted vs None network-mode constraint and point users at committing the existing .claude/settings.json so the language server carries over to cloud sessions. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

kay-kim · 2026-06-15T21:14:59Z

 `client_encoding`                           | `UTF8`                    | The client's character set encoding. The only supported value is `UTF-8`.                                                                                              | Yes
 `client_min_messages`                       | `notice`                  | The message levels that are sent to the client. <br/><br/> Accepts values: `debug5`, `debug4`, `debug3`, `debug2`, `debug1`, `log`, `notice`, `warning`, `error`. Each level includes all the levels that follow it. | Yes
 `datestyle`                                 | `ISO, MDY`                | The display format for date and time values. The only supported value is `ISO, MDY`.                                                                                   | Yes
-`default_timestamp_interval`                | `1s`                      | The interval at which timestamps are assigned to data ingested from sources and tables. New sources are created with this value unless overridden by the `TIMESTAMP INTERVAL` option of [`CREATE SOURCE`](/sql/create-source/). Accepts positive [interval](/sql/types/interval/) values (e.g. `'500ms'`, `'1s'`). This setting applies only when creating sources; changing this value does not affect existing sources. For existing sources, see [`ALTER SOURCE`](/sql/alter-source/). | [Contact support]


Hey Seth -- did you mean to remove this? and below max/min time intervals? Or was it a need to git pull --rebase to get the latest main?

I definitely need a rebase

kay-kim · 2026-06-15T21:15:13Z


        display: flex;
        overflow-x: auto;
-        overflow-y: hidden;


Hey Seth -- did you mean to remove this? Or was it a need to git pull --rebase to get the latest main?

kay-kim · 2026-06-15T21:15:21Z

    padding: var(--x-small) rem(2);
    position: sticky;
    top: 0;
+    overflow-y: auto;


kay-kim · 2026-06-15T21:19:17Z

+    name: "Manage with mz-deploy"
+---
+
+`mz-deploy` is a CLI that manages your Materialize deployment from plain SQL


Do we want to mention not recommended for production?

kay-kim · 2026-06-15T21:19:35Z

+    name: "Get started"
+---
+
+`mz-deploy` is a deployment tool that gives you compile-time validation, unit


Do we want to mention that it's not recommended for production?

maheshwarip · 2026-06-15T21:22:01Z

@sjwiesman let's include a note that this is a v0.1 and not recommended for production use yet

kay-kim · 2026-06-15T21:25:19Z

+
+```sql
+-- clusters/orders.sql
+CREATE CLUSTER orders (SIZE = 'xsmall');


Just wondering if we should be using the xsmall or the cc sizes?

@maheshwarip

- Add v0.1 / not-recommended-for-production warning to the mz-deploy index and get-started pages (per @maheshwarip and @kay-kim). - Drop unrelated SCSS, layout, baseof.html, and configuration-parameter changes that leaked onto the branch (per @kay-kim). - Use current `cc` cluster sizes instead of legacy t-shirt sizes in examples (per @kay-kim). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

- Recommend `brew install materializeinc/materialize/mz-deploy` for macOS and Linux in the get-started guide. - Document installing the VS Code extension from the Marketplace (link + `code --install-extension MaterializeInc.mz-deploy`). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

sjwiesman · 2026-06-15T22:02:29Z

Updates:

rebased
moved to cc sizes for examples
added vscode installation instructions
added homebrew install instructions.

kay-kim

per discussion w product, we can publish this when you feel ready. I'll do a more thorough vetting tomorrow.

`dev` deploys a personal, throwaway copy of changed views to a remote Materialize for validation against production data — it is not a local inner-loop command (that is `compile`). Fix three inaccuracies in the deployments doc: - Reframe from "inner-loop command" to a per-developer scratch deployment against the remote instance. - Add the required `<CLUSTER>` positional argument to the examples; the CLI rejects `dev` without it (unless `--down`). - Correct the claim that `IN CLUSTER` clauses pass through unchanged. `dev` rewrites every overlay MV/index to the cluster you pass and refuses a cluster hosting a promoted deployment. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

The mz-deploy language server exposes a single SQL LSP; the separate Codex configuration block duplicated the Claude Code example without adding distinct guidance. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Correct several doc claims that contradicted the CLI implementation: - `debug` prints profile, Docker status, environment ID, and server cluster health — not Materialize version and current role. - Fix the unit-test example: no comma separates the final MOCK clause from EXPECTED, so the example now parses. - Role table no longer implies `apply` is gated by materialize_deployer; `apply` performs no role check. Spell out which commands enforce which roles. - Document the `promote --allowed-lag` flag (default 300s). - Note that `setup` creates the deployment server cluster, and that access-control roles are only created when RBAC is enabled. - Replace `sudo echo` with `sudo -v` in the install snippets, and note that `mz-deploy sql` requires psql on PATH. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Document EXECUTE UNIT TEST as a SQL command reference page with its full grammar, alongside the other SQL command pages. The statement defines an inline unit test for a view: it mocks the view's dependencies, runs the view against fixed input, and compares the result to expected rows. The page carries a public-preview banner and clearly calls out that the statement is executed only by mz-deploy — the Materialize server parses it but rejects it during planning. Link the mz-deploy local-development guide to the new reference. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

sjwiesman and others added 2 commits June 15, 2026 13:11

mz-deploy docs

a13b32d

kay-kim reviewed Jun 15, 2026

View reviewed changes

sjwiesman and others added 2 commits June 15, 2026 16:53

kay-kim approved these changes Jun 15, 2026

View reviewed changes

sjwiesman marked this pull request as ready for review June 15, 2026 22:33

sjwiesman requested a review from a team as a code owner June 15, 2026 22:33

sjwiesman and others added 2 commits June 15, 2026 18:31

show install on first page

46f4a2d

sjwiesman force-pushed the mz-deploy-docs branch from f22ad70 to 881790d Compare June 15, 2026 23:40

sjwiesman and others added 3 commits June 15, 2026 19:20

Remove Codex LSP configuration section

b8c1f03

The mz-deploy language server exposes a single SQL LSP; the separate Codex configuration block duplicated the Claude Code example without adding distinct guidance. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

sjwiesman merged commit e6caffc into MaterializeInc:main Jun 16, 2026
15 checks passed

kay-kim removed the request for review from a team July 3, 2026 18:20

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add mz-deploy documentation#37052

Add mz-deploy documentation#37052
sjwiesman merged 9 commits into
MaterializeInc:mainfrom
sjwiesman:mz-deploy-docs

sjwiesman commented Jun 15, 2026

Uh oh!

kay-kim Jun 15, 2026

Uh oh!

sjwiesman Jun 15, 2026

Uh oh!

kay-kim Jun 15, 2026

Uh oh!

kay-kim Jun 15, 2026

Uh oh!

kay-kim Jun 15, 2026

Uh oh!

kay-kim Jun 15, 2026

Uh oh!

maheshwarip commented Jun 15, 2026

Uh oh!

kay-kim Jun 15, 2026

Uh oh!

sjwiesman commented Jun 15, 2026

Uh oh!

kay-kim left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

sjwiesman commented Jun 15, 2026

What's here

Notes

Uh oh!

kay-kim Jun 15, 2026

Choose a reason for hiding this comment

Uh oh!

sjwiesman Jun 15, 2026

Choose a reason for hiding this comment

Uh oh!

kay-kim Jun 15, 2026

Choose a reason for hiding this comment

Uh oh!

kay-kim Jun 15, 2026

Choose a reason for hiding this comment

Uh oh!

kay-kim Jun 15, 2026

Choose a reason for hiding this comment

Uh oh!

kay-kim Jun 15, 2026

Choose a reason for hiding this comment

Uh oh!

maheshwarip commented Jun 15, 2026

Uh oh!

kay-kim Jun 15, 2026

Choose a reason for hiding this comment

Uh oh!

sjwiesman commented Jun 15, 2026

Uh oh!

kay-kim left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants