用途：mz-deploy 是 Materialize 的声明式 SQL 项目工具。项目是一个由 git 跟踪的目录，内含描述 Materialize 环境目标状态的 .sql 文件；工具负责编译、离线类型检查、在本地容器中测试，并通过先 stage 后 promote 的原子生命周期部署变更。安装命令：brew install materializeinc/materialize/mz-deploy。
主要能力：命令按用途分组，包括入门（new、init、profile、setup、debug）、开发（compile、clean、test、explain、dev、lsp、sql、mcp）、基础设施（lock、apply、delete）、部署（stage、wait、promote、abort、describe、list、log）。compile 无需数据库连接，可在每次提交的 CI 中运行；test 在本地 Materialize 容器中运行单元测试。apply 以声明式、基于差异、幂等的方式收敛集群、角色、网络策略、密钥、连接、源和表；stage 处理视图和物化视图。变更检测基于哈希，仅部署变化对象及其下游。promote 在单个事务内对 schema 和集群执行 ALTER … SWAP，可恢复。
使用方式：从项目根目录运行命令，或传 -d <path>。全局选项有 -p/--profile 选择连接配置、--output json 输出机器可读结果、-v 详细调试、-q 抑制信息输出。CLI 自带文档，运行 mz-deploy help、mz-deploy help <command>、mz-deploy help profiles 查看权威用法。典型流程：compile、test、apply、stage、wait <DEPLOY_ID>、promote <DEPLOY_ID>。
适用场景与限制：适合用声明式 SQL 管理 Materialize 环境的团队。setup 在启用 RBAC 时需超级用户执行一次。stage 要求 git 工作树干净，否则需提交、暂存或传 --allow-dirty。test 和 explain 需要 Docker，并共用名为 mz-deploy-sandbox 的容器。delete 不会级联。dev 不会指向生产集群。没有回滚命令，需在项目中反向修改后重新 stage 并 promote。冲突检测以 schema 和集群为粒度，--force 会丢弃他人工作。稳定 API schema 需在 schema mod 文件中加 SET api = stable，且只能包含物化视图。单元测试语法见 references/unit-tests.md。