Atlas & Prisma ORM を利用した高度なデータベーススキーマ管理

はじめに

Atlasは、CI/CD連携、スキーマ監視、バージョン管理などの高度なデータベーススキーマ管理ワークフローを可能にする、強力なデータモデリングおよびマイグレーションツールです。

このガイドでは、既存のPrisma ORMプロジェクトのPrisma MigrateをAtlasに置き換えることで、Atlasの高度なスキーマ管理およびマイグレーションワークフローを活用する方法を学びます。

そうすることで、Prisma ORMの直感的なデータモデルと型安全なクエリ機能を使いつつ、Atlasが提供する強化されたマイグレーション機能を活用できます。

このチュートリアルの例のリポジトリはGitHubで見つけることができます。このリポジトリには、本ガイドの各ステップに対応するブランチがあります。

Prisma Migrateの代わりにAtlasを使用する理由

Prisma Migrateは、アプリケーション開発者がデータベーススキーマを管理する上でほとんどのユースケースをカバーする強力なマイグレーションツールです。開発から本番への移行や、チームコラボレーションを念頭に置いたワークフローを提供します。

しかし、さらに多くの機能が必要な場合、以下のシナリオでAtlasのような専用ツールを使用してマイグレーションワークフローを強化することができます。

• 継続的インテグレーション (CI): Atlasを使用すると、堅牢なGitHub Actions、GitLab、およびCircleCI Orbsとの連携により、本番環境に到達する前に問題を特定できます。また、リスクの高いマイグレーションの検出、データマイグレーションのテスト、データベース関数のテストなども可能です。
• 継続的デリバリー (CD): Atlasはパイプラインに統合でき、デプロイメント機構 (例: Kubernetes Operator、Terraformなど) とのネイティブな連携を提供します。
• スキーマ監視: Atlasはデータベーススキーマを監視し、予期せぬ状態から逸脱した場合に警告を発することができます。
• 低レベルデータベース機能のサポート: ビュー、ストアドプロシージャ、トリガー、行レベルセキュリティなどの高度なデータベースオブジェクトの自動マイグレーション計画。

前提条件

このガイドを正常に完了するには、以下が必要です。

• 既存のPrisma ORMプロジェクト（prismaおよび@prisma/clientパッケージがインストールされていること）
• PostgreSQLデータベースとその接続文字列
• マシンにDockerがインストールされていること（Atlasの一時的な開発データベースを管理するため）

このガイドの目的のために、Prismaスキーマに、当社のドキュメント全体で主要な例として使用している標準的なUserおよびPostモデルが含まれていると仮定します。Prisma ORMプロジェクトをお持ちでない場合は、orm/scriptの例を使用してこのガイドを進めることができます。

このステップの開始点は、例のリポジトリのstartブランチです。

ステップ1: 既存のPrisma ORMプロジェクトにAtlasを追加する

このチュートリアルを開始するには、まずAtlas CLIをインストールします。

別のインストール方法（DockerやHomebrewなど）をご希望の場合は、こちらで見つけることができます。

次に、Prisma ORMを使用しているプロジェクトのルートディレクトリに移動し、atlas.hclという名前のメインのAtlasスキーマファイルを作成します。

次に、以下のコードを追加します。

Atlasスキーマファイルの構文ハイライトやその他の便利な機能を利用するには、Atlas VS Code拡張機能をインストールしてください。

上記のスニペットでは、2つのことを行っています。

• dataブロックを使用してprismaというexternal_schemaを定義します。Atlasは様々なソースからデータベーススキーマ定義を統合できます。このケースでは、programフィールドで指定されているprisma migrate diffコマンドによって生成されるSQLがソースとなります。
• envブロックを使用して、環境（localという名前）の詳細を指定します。
  • dev: シャドウデータベース（Atlasでは開発データベースと呼ばれます）を指します。Prisma Migrateと同様に、Atlasもマイグレーションの「ドライラン」にシャドウデータベースを使用します。ここで提供する接続は、PrismaスキーマのshadowDatabaseUrlに似ています。ただし、このケースでは、一時的なデータベースインスタンスを管理するためにDockerを使用しています。
  • schema: Prisma ORMがターゲットとするデータベースのデータベース接続URLを指します（ほとんどの場合、これはDATABASE_URL環境変数と同じになります）。
  • migration: Atlasマイグレーションファイルを保存したいファイルシステムのディレクトリを指します（prisma/migrationsフォルダーに似ています）。_prisma_migrationsがAtlasのマイグレーション履歴で追跡されないように除外している点に注意してください。

シャドウデータベースに加えて、AtlasのマイグレーションシステムとPrisma Migrateにはもう1つの共通点があります。どちらもデータベース内の専用テーブルを使用して、適用されたマイグレーションの履歴を追跡します。Prisma Migrateでは、このテーブルは_prisma_migrationsと呼ばれます。Atlasでは、atlas_schema_revisionsと呼ばれます。

Atlasに、データベースの現在の状態（既存のすべてのテーブルやその他のデータベースオブジェクトを含む）が、プロジェクトでマイグレーションを追跡するための開始点となることを伝えるために、最初のベースラインマイグレーションを行う必要があります。

そのためには、まず以下のコマンドを実行してAtlasのマイグレーションディレクトリを作成します。

このコマンドは、

1. local環境の現在の状態を確認し、Atlasスキーマで定義されたexternal_schemaに基づいてSQLマイグレーションファイルを生成します。
2. atlas/migrationsフォルダーを作成し、そこにSQLマイグレーションを配置します。

実行後、フォルダー構造は以下のようになります。

この時点では、Atlasはまだデータベースに対して何も行っていません。ローカルマシン上にファイルを作成しただけです。

次に、生成されたマイグレーションを適用して、これがAtlasのマイグレーション履歴の開始点となることをAtlasに伝える必要があります。そのためには、atlas migrate applyコマンドを実行しますが、今回は--baseline __TIMESTAMP__オプションを付けてください。

Atlasがatlas/migrations内に作成したファイル名からタイムスタンプをコピーし、次のスニペットの__TIMESTAMP__プレースホルダー値を置き換えます。同様に、__DATABASE_URL__プレースホルダーをデータベース接続文字列に置き換えます。

生成されたマイグレーションファイルが20241210094213.sqlという名前で、データベースがpostgresql://johndoe:mypassword42@localhost:5432/example-db?search_path=public&sslmode=disableで実行されていると仮定すると、コマンドは以下のようになります。

コマンドの出力は以下のようになります。

今、データベースを調べると、atlas_schema_revisionsテーブルが作成されており、Atlasマイグレーション履歴の開始を指定する2つのエントリが含まれていることがわかります。

プロジェクトは、例のリポジトリのstep-1ブランチに似た状態になっているはずです。

ステップ2: Atlasでマイグレーションを実行する

次に、Prismaスキーマを編集し、Atlasマイグレーションを使用してデータベースに変更を反映する方法を学びます。大まかには、プロセスは以下のようになります。

1. Prismaスキーマに変更を加える
2. atlas migrate diffを実行してマイグレーションファイルを作成する
3. atlas migrate applyを実行して、データベースに対してマイグレーションファイルを実行する
4. prisma generateを実行してPrisma Clientを更新する
5. Prisma Clientを介してアプリケーションコードで変更されたスキーマにアクセスする

このチュートリアルの目的のために、Postモデルとの多対多リレーションを持つTagモデルでPrismaスキーマを拡張します。

その変更が完了したら、次にマイグレーションファイルをマシン上に作成するコマンドを実行します。

以前と同様に、これによりatlas/migrationsフォルダー内に新しいファイル（例: 20241210132739.sql）が作成され、データモデルの変更を反映するSQLコードが含まれます。上記の変更の場合、以下のようになります。

次に、以前と同じatlas migrate applyコマンドでマイグレーションを適用できますが、今回は--baselineオプションは不要です（__DATABASE_URL__プレースホルダーを置き換えるのを忘れないでください）。

データベーススキーマは更新されましたが、node_modules/@prisma/client内の生成されたPrisma Clientはまだスキーマ変更を認識していません。そのため、Prisma CLIを使用して再生成する必要があります。

これで、アプリケーションコードに移動し、更新されたスキーマに対してクエリを実行できます。このケースでは、新しいTagモデルを含むクエリ、例えば以下のようになります。

プロジェクトは、例のリポジトリのstep-2ブランチに似た状態になっているはずです。

ステップ3: DBスキーマに部分インデックスを追加する

このセクションでは、Prismaスキーマでサポートされていない機能でデータベーススキーマを拡張する方法を学びます。例として、部分インデックスを使用します。

これを実現するためのワークフローは以下のとおりです。

1. atlasディレクトリ内に、希望する変更を反映するSQLファイルを作成する
2. AtlasがそのSQLファイルを認識するように、atlas.hclを更新して含める
3. atlas migrate diffを実行してマイグレーションファイルを作成する
4. atlas migrate applyを実行して、データベースに対してマイグレーションファイルを実行する

今回は、Prismaスキーマファイルを手動で編集しなかったため、Prisma Clientを再生成する必要はありません。

部分インデックスを追加しましょう！

まず、atlasディレクトリ内にpublished_posts_index.sqlという名前のファイルを作成します。

次に、以下のコードを追加します。

これは、publishedフィールドがtrueに設定されているPostレコードにインデックスを作成します。このクエリは、これらの公開された投稿をクエリする場合に役立ちます。例えば、以下のようになります。

次に、スキーマの新しいSQLスニペットを認識させるためにatlas.hclファイルを調整する必要があります。これはcomposite_schemaアプローチを使用することで行うことができます。atlas.hclファイルを以下のように調整してください。

composite_schemaはAtlas Proプランでのみ利用可能であり、atlas loginを介した認証が必要です。

これでAtlasはスキーマ変更を認識したため、以前と同様にマイグレーションファイルを生成できます。

atlas/migrationsディレクトリ内に再び新しいファイルが表示されます。以前と同じコマンドでマイグレーションを実行してください（__DATABASE_URL__をご自身の接続文字列に置き換えてください）。

おめでとうございます！データベースに部分インデックスが追加され、公開された投稿のクエリがより高速になります。

プロジェクトは、例のリポジトリのstep-3ブランチに似た状態になっているはずです。

まとめ

このチュートリアルでは、Atlasを既存のPrisma ORMプロジェクトに統合する方法を学びました。Atlasは、Prisma ORMを使用する際のスキーマ管理およびマイグレーションワークフローを強化するために使用できます。

このチュートリアルの最終結果をざっと確認したい場合は、例のリポジトリをご覧ください。