mz-deploy

mz-deploy

mz-deploy は Materialize 向けの宣言型 SQL プロジェクトツールです。プロジェクトは、Materialize 環境の望ましい状態を記述した .sql ファイルを含む、Git で追跡されるディレクトリです。mz-deploy はプロジェクトをコンパイルし、オフラインで型チェックを行い、ローカルコンテナでテストしたうえで、ステージング後にプロモートするアトミックなライフサイクルを通じて変更をデプロイします。

brew install materializeinc/materialize/mz-deploy

実行前に確認する

CLI は自己文書化されており、ヘルプテキストが信頼できる情報源です。コマンド名、フラグ、引数の順序を推測しないでください。

1. mz-deploy help — 用途別に分類されたすべてのコマンドです。
2. mz-deploy help <command> — 1 つのコマンドの詳細な使い方ガイドです。動作、すべてのフラグ、例、エラーからの復旧方法、終了コードが記載されています。
3. mz-deploy help profiles — 設定に関するトピックガイドです（プロファイル、変数、サフィックス、ファイルのオーバーライド、TLS）。

このスキルでは、どのコマンドを使うべきかがわかるよう、概念とワークフローの概要を説明します。実行する前に、そのコマンドの help でフラグを確認してください。

コマンドはプロジェクトのルートから実行するか、-d <path> を指定してください。知っておくと便利なグローバルオプション：-p/--profile は接続プロファイルを選択し、--output json は機械可読な出力を指定します（ほとんどのコマンドでサポートされており、CI で便利です）。-v は詳細なデバッグ情報を出力し、-q は情報メッセージを抑制します。

プロジェクトの構成

project.toml              # project config: mz_version, dependencies, per-profile settings
profiles.toml             # connection profiles (also resolved from ~/.mz)
.mzprofile                # gitignored per-checkout default profile
types.lock                # cached schemas of external dependencies, for offline type checking
target/                   # gitignored local build cache (safe to delete; see `clean`)
models/
  <database>/
    <schema>.sql          # schema mod file — schema-level statements (see below)
    <schema>/
      <object>.sql        # one view, materialized view, table, source, sink, connection, or secret
clusters/<name>.sql       # cluster definitions (+ their GRANTs)
roles/<name>.sql          # role definitions
network-policies/<name>.sql

パスによって、オブジェクトの完全修飾名が決まります。models/materialize/catalog/clusters.sql にある MV の名前は materialize.catalog.clusters です。スキーマ修正ファイル — <schema>/ ディレクトリと同じ階層に置く <schema>.sql — には、SET api = stable など、スキーマ全体に適用されるステートメントを記述します。

mz-deploy new <name> は新しいディレクトリにこの構成を作成し、init は現在のディレクトリに同じ構成を作成します。

コマンド一覧

グループ	コマンド
はじめに	new、init、profile（list/set/current）、setup、debug
開発	compile、clean、test、explain、dev、lsp、sql、mcp
インフラストラクチャ	lock、apply、delete
デプロイ	stage、wait、promote、abort、describe、list、log

初回のブートストラップでは、mz-deploy setup によって _mz_deploy 追跡データベース、そのテーブル、_mz_deploy_server クラスター、3 つのロールが作成されます。RBAC が有効な場合、システム権限を付与するため、スーパーユーザーが実行する必要があります。 その後はすべて通常のユーザーとして実行できます。

ワークフロー

mz-deploy compile              # parse, resolve dependencies, type-check offline
mz-deploy test                 # run unit tests in a local Materialize container
mz-deploy apply                # converge infrastructure (see below)
mz-deploy stage                # deploy changed views/MVs to suffixed staging schemas
mz-deploy wait <DEPLOY_ID>     # watch clusters hydrate until ready
mz-deploy promote <DEPLOY_ID>  # atomic swap into production

compile はデータベース接続を必要としないため、すべてのコミットで CI に組み込めます。compile が成功すれば、SQL の解析段階で stage と apply が失敗することはありません。なお、--profile に関係なくすべてのプロファイルバリアントが検証されるため、foo#staging.sql に構文エラーがあると、compile --profile production も失敗します。

補足：list はプロモートされていないデプロイを表示し（git branch のようなものです）、describe <ID> はその詳細を表示し、log はプロモーションの履歴を表示します（git log のようなものです）。また、abort <ID> はステージング中のデプロイをプロモートせずに破棄します。

主な概念

apply はインフラを管理し、stage はビューを管理します。 apply は宣言型で、差分ベースかつ冪等です。クラスター、ロール、ネットワークポリシー、シークレット、接続、ソース、テーブルを依存関係の順に収束させます。stage はビューとマテリアライズドビューを処理します。テーブルとソースが stage によって作成されることは決してありません。すでに存在している必要があるため、先に apply を実行します。delete <type> <name> は apply の逆の操作で、オブジェクトを 1 つ CASCADE なしで削除し、対応するプロジェクトファイルも削除します。

デプロイ ID とステージングサフィックス。 各デプロイには ID が割り当てられます。デフォルトでは現在のコミット SHA の先頭 7 文字が使われ、スキーマとクラスターのサフィックスとして付与されます（public → public_abc123）。ステージングクラスターは、対応する本番クラスターの設定（自動スケーリング戦略を含む）を複製するため、ステージングオブジェクトは本番と同じようにハイドレートされます。ステージングは本番と並行して独立して実行されます。

変更の検出はハッシュベースです。 stage は各オブジェクトの SQL ハッシュを最後に昇格したスナップショットと比較し、変更されたものと、その変更の下流にあるものだけをデプロイします。変更のないオブジェクトは再作成されません。--redeploy-schema <db.schema> または --redeploy-all で上書きできます。

昇格はアトミックで、再開できます。 promote は単一のトランザクション内でスキーマとクラスターに対して ALTER … SWAP を実行し、その後、遅延されたシンクの作成、置換 MV の適用、シンクの新しい本番オブジェクトへの付け替え、古いリソースの削除を行います。処理の途中で失敗した場合、同じコマンドを再実行すると、スワップ後の状態を検出してクリーンアップを再開します。

シンクの作成は promote まで保留されます。 デプロイが有効になるまでシンクがデータ生成を開始してはならないため、stage はシンクを記録し、promote が作成します。

競合検出はスキーマとクラスター単位で行われます。 スキーマ全体を 1 つの単位としてスワップするため、異なるオブジェクトを変更する場合でも、同じスキーマまたはクラスターに少しでも変更を加える 2 つのデプロイは競合します。先に昇格したデプロイが優先され、後のデプロイは拒否されるため、現在の本番環境を基に再度ステージングする必要があります。--force を指定するとチェックを省略できますが、その場合、他のデプロイ担当者のスキーマが削除されます。スキーマはマージされず、全体がスワップされるためです。その作業を上書きする意図がある場合に限り使用してください。

安定した API スキーマ。 デフォルトでは、変更されたオブジェクトはステージングで再作成され、スキーマ全体がスワップされます。これにより、プロジェクト内の依存オブジェクトは自動的に再デプロイされますが、他の mz-deploy プロジェクトにあるコンシューマーは動作しなくなります。スキーマの mod ファイルに SET api = stable を追加すると、そのスキーマが API 境界として扱われます。変更された MV は ALTER MATERIALIZED VIEW … APPLY REPLACEMENT によってインプレースで更新され、オブジェクトの ID が維持されます。どのプロジェクトにある場合でも、下流のコンシューマーを再デプロイする必要はありません。制約：安定したスキーマに含められるのはマテリアライズドビューのみです。また、置換された MV の変更によって依存オブジェクトに変更が伝播することはありません。

型チェックはオフラインで行われます。 compile と test は、types.lock から外部依存関係のスキーマを読み込みます。外部オブジェクトは project.toml で dependencies = ["db.schema.table"] として宣言し、mz-deploy lock を実行してファイルを更新します。CREATE TABLE FROM SOURCE によって作成されたソーステーブルは自動検出されるため、宣言は不要です。apply tables を実行するとロックファイルが自動的に再生成されます。

ロール。 setup は materialize_deployer（stage、promote、abort）、materialize_developer（読み取り専用のデプロイ状態と dev オーバーレイ）、materialize_monitor を作成します。各ユーザーは必ず 1 つだけに所属する必要があります。複数のロールを保持するとエラーになります。デプロイ、開発、監視には、それぞれ異なるユーザーを使った個別のプロファイルを使用してください。

プロファイルとプロファイルごとの設定

プロファイルは、profiles.toml で指定する名前付き接続先です。--profiles-dir、MZ_DEPLOY_PROFILES_DIR、~/.mz の順に解決されます。アクティブなプロファイルは、--profile、MZ_DEPLOY_PROFILE、プロジェクトルートにある Git の追跡対象外ファイル .mzprofile（mz-deploy profile set によって書き込まれます）の順に解決されます。組み込みの emulator プロファイルは常に存在するため、ローカルの Materialize エミュレーターは設定なしですぐに動作します。

パスワードでは ${VAR} による置換を利用でき、MZ_PROFILE_<NAME>_PASSWORD で上書きできます。sslmode は PostgreSQL の用語に準じ、ループバックホストでは prefer、それ以外では require がデフォルトです。Materialize Cloud では verify-full を使用してください。

プロファイルの役割は、接続先ホストの選択だけではありません。コンパイル時に次の項目も選択します。

• profile_suffix（project.toml 内）— IN CLUSTER の参照を含め、すべてのデータベース名とクラスター名に追加されます。区切り文字は自分で指定します。"staging" ではなく "_staging" とします。ステージング用のサフィックスは重ねて追加されます（foo → foo_staging → foo_staging_a）。
• SQL 変数 — project.toml の [<profile>.variables] で指定し、psql の構文で任意の .sql ファイルから参照できます。:name（そのまま）、:'name'（引用符で囲んだ文字列）、:"name"（引用符で囲んだ識別子）を使用します。未定義の変数を参照するとコンパイルに失敗します。
• ファイルのオーバーライド — プロファイルがアクティブな場合、name#<profile>.sql が name.sql を置き換えます。アクティブなプロファイルにかかわらず、すべてのバリアントがコンパイル時に検証され、同じプライマリ文タイプである必要があります。ビューとマテリアライズドビューではファイルのオーバーライドを使用できません。代わりに SQL 変数を使用してください。

ロールバック

ロールバック用のコマンドはありません。プロジェクトで変更を元に戻し、その結果を昇格させてください。

git revert <commit>
mz-deploy stage
mz-deploy promote <DEPLOY_ID>

promote はアトミックに切り替えるため、ロールバックの昇格処理自体もアトミックです。1 回のトランザクションで本番環境が元の状態に戻ります。

ユニットテスト

mz-deploy test は、対象のビューと同じ .sql ファイル内に記述されたテストを、モックした依存関係を使って EXECUTE UNIT TEST で実行します。この構文は mz-deploy 固有で、ほかでは文書化されていません。構文全体、実例、失敗するケースについては、references/unit-tests.md を参照してください。

注意事項

• stage を実行するには、Git の作業ツリーがクリーンである必要があります。 コミットするか、スタッシュするか、--allow-dirty を指定してください。
• RBAC では、setup にスーパーユーザーが必要です。 必要なのは初回のみです。
• test と explain の実行には Docker が必要です。 ホスト上の複数回の実行で、mz-deploy-sandbox という名前のコンテナーを共有します。再利用はイメージではなく 名前 に基づくため、docker rm -f mz-deploy-sandbox を実行するまで --docker-image は反映されません。
• delete はカスケード削除を行いません。 依存関係がある場合は失敗し、プロジェクトファイルはそのまま残ります。
• dev の対象に本番クラスターは指定できません。 専用の開発クラスターを用意してください。
• プロファイルの cluster オプションは無視されます。 mz-deploy はすべての接続先を内部の _mz_deploy_server クラスターに固定します。必要に応じて、標準的な ALTER CLUSTER でサイズを変更してください。
• stage が失敗すると自動的にロールバックされます。 デバッグ用に部分的なデプロイを残すには --no-rollback を指定し、その後 abort でクリーンアップしてください。
• 古い target/ キャッシュが原因で、コンパイルエラーや型エラーが分かりにくくなることがあります。mz-deploy clean を実行してください。