`verify` - スキーマ変更の検証

v1.24.0で追加

スキーマの更新や不適切に書かれたクエリは、本番データベースをダウンさせることがよくあります。これは良くありません。

デフォルトでは、sqlc generateはこれらの問題の一部をキャッチします。sqlc/db-prepareルールを使用してsqlc vetを実行すると、より微妙な問題をキャッチします。しかし、現在のスキーマとクエリだけを見ていては、sqlcが防げない問題の大きなクラスが存在します。

例えば、スキーマ変更が提案された場合、本番環境で実行されている既存のクエリとコードは、スキーマ変更が適用されると失敗する可能性があります。sqlc verifyの登場です。これは、既存のクエリを新しいスキーマ変更に対して分析し、問題がある場合はエラーを出します。

例を見てみましょう。本番環境にこれら2つのテーブルがあると仮定します。

CREATE TABLE users (
  id UUID PRIMARY KEY
);

CREATE TABLE user_actions (
  id UUID PRIMARY KEY,
  user_id UUID NOT NULL,
  action TEXT,
  created_at TIMESTAMP
);

あなたのアプリケーションには、usersテーブルに対してuser actionsを結合する以下のクエリが含まれています。

-- name: GetUserActions :many
SELECT * FROM users u
JOIN user_actions ua ON u.id = ua.user_id
ORDER BY created_at;

これまでは良好です。次に、このスキーマ変更を提案するとします：

ALTER TABLE users ADD COLUMN created_at TIMESTAMP;

この変更でsqlc generateを実行すると、column reference "created_at" is ambiguousエラーが返されて失敗します。問題を修正するためにクエリを更新します。

-- name: GetUserActions :many
SELECT * FROM users u
JOIN user_actions ua ON u.id = ua.user_id
ORDER BY u.created_at;

この変更は問題を修正しますが、本番環境の停止が待ち受けています。スキーマ変更が適用されると、既存のGetUserActionsクエリが失敗し始めます。これを修正する正しい方法は、スキーママイグレーションを適用する前に更新されたクエリをデプロイすることです。

マイグレーションが安全にデプロイできることを確認するために、現在のスキーマとクエリをsqlc cloudに送信します。そこで、最新のプッシュに対するクエリを新しいスキーマ変更に対して実行します。このチェックは、既存のクエリに対する後方互換性のないスキーマ変更をキャッチします。

ここで、sqlc verifyはORDER BY “created_at"があいまいであることを警告します。

$ sqlc verify
FAIL: app query.sql

=== Failed
=== FAIL: app query.sql GetUserActions
    ERROR: column reference "created_at" is ambiguous (SQLSTATE 42702)

ちなみに、このシナリオは作り話ではありません！数週間前に私たちに起こったことです。私たちは過去2週間、verifyの初期バージョンを幸せにテストしており、それ以来問題は発生していません。

この種の検証は始まりに過ぎません。あなたのアプリケーションが顧客によってオンプレミスでデプロイされている場合、verifyは、スキーママイグレーションが実行された後でも、顧客がアプリケーションの古いバージョンにロールバックすることが安全かどうかを知らせることができます。

sqlc verifyを使用するには、アプリケーションのリリースにタグを付けるときにクエリとスキーマをプッシュする必要があります。私たちは継続的にコミットを本番環境にデプロイするため、mainへのすべてのプッシュで実行しています。

認証

sqlcは、SQLC_AUTH_TOKEN環境変数の値で有効な認証トークンを見つけることを期待しています。認証トークンはダッシュボード経由で作成できます。

export SQLC_AUTH_TOKEN=sqlc_xxxxxxxx

期待されるワークフロー

sqlc verifyを使用するには、クエリとスキーマをsqlc Cloudにプッシュする必要があります。アプリケーションの新しいバージョンをリリースするときは、スキーマとクエリもプッシュする必要があります。例えば、私たちは本番環境にすべてのコミットをデプロイするため、Githubのmainブランチへのあらゆる変更がマージされた後にsqlc pushを実行しています。

$ sqlc push --tag main

ローカルでまたはプルリクエストで、sqlc verifyを実行して、既存のクエリが現在のデータベーススキーマで引き続き動作することを確認します。

$ sqlc verify --against main

タグの選択

against引数なしでは、verifyは最も最近プッシュされたクエリを使用して、提供されたスキーマの分析を実行します。比較のために明示的にクエリのセットを選択するために、against引数を使用することをお勧めします。

$ sqlc verify --against [tag]

原文：https://docs.sqlc.dev/en/latest/howto/verify.html

push - プロジェクトのアップロード `vet` - クエリのリンティング