[Keystone] コマンドライン

backham
技術

コマンドライン

Keystone のコマンドラインインターフェイス (CLI) は、Keystone プロジェクトを開発、ビルド、展開するために設計されています。
keystone コマンドを使用することで、開発プロセスを開始し、アプリケーションをビルドして本番環境で実行し、スキーマが変更されるにつれてデータベースの構造を移行する方法を制御できます。

使い方

$ keystone [command]

Commands
  dev           開発モードでプロジェクトを開始します (デフォルト)
  postinstall   プロジェクトをビルドします (開発用、オプション)
  build         プロジェクトをビルドします (\`keystone start\` で必要)
  start         プロジェクトを開始する
  prisma        Prisma CLI コマンドを安全に実行する
  telemetry     テレメトリーの設定 (有効化/無効化/ステータス)

package.json のセットアップ

次のスクリプトをプロジェクトのファイルに追加することをお勧めします。
package.json

{
  "scripts": {
    "deploy": "keystone build && keystone prisma migrate deploy",
    "dev": "keystone dev",
    "postinstall": "keystone postinstall",
    "start": "keystone start"
  }
}

dev

$ keystone dev

これは、ローカル開発のために Keystone を起動するために使用するコマンドです。

  • Keystone の API と管理 UI に必要なファイルを生成する。
  • Keystone スキーマに基づくデータベース移行の生成と適用。
  • GraphQL API と管理 UI をホストするローカル開発サーバーを起動します。

データベースの移行について

開発中には、db.useMigrations がどのように設定されているかに応じて、Keystone はデータベースの構造を 2 つの方法のいずれかで自動的に移行します。

  • db.useMigrations が falseに設定されている場合 (デフォルト)、Keystone は Prisma Migrate を使用して、スキーマに合わせてデータベースを更新します。データベースの更新中にデータが失われる可能性があるため、このモードは初期開発時にのみ使用することが推奨されます。
  • db.useMigrations が true に設定されている場合、Keystone は Prisma Migrate を使用して既存のマイグレーションを適用し、スキーマが変更された場合はマイグレーションの作成を促します。
    マイグレーションを使用する場合、推奨されるワークフローは、keystone dev がマイグレーションを生成し、開発中に自動的に適用することです。
    マイグレーションファイルをソースコントロールにコミットし、アプリを本番環境でホスティングする場合は、Keystone を開始する前に keystone prisma migrate deploy コマンドを使用してマイグレーションを展開することができます。

データベースのリセット

開発中に、データベースをリセットして最初から再作成したい場合があります。これを行うには、Prisma を使用します。

$ keystone prisma db push --force-reset

これは通常、プロジェクトの開発ライフサイクルの早い段階で、データベース初期化スクリプトをテストしたり、新しいテストデータのセットを作成したりするときに役立ちます。

ポストインストール

$ keystone postinstall

Keystone は、ノード、API、TypeScript の定義など .js アプリが依存する可能性のあるいくつかのファイルを生成します。
Keystone の dev コマンドによって生成されるファイルですが、常に存在し最新の状態にするために、postinstall コマンドをプロジェクトの package.json に追加することを強くお勧めします。そうしない場合、コードエディターや CI ワークフローで断続的なエラーが発生する可能性があります。

検証エラーの修正

postinstall コマンドは、ソースコントロールにコミットする必要がある生成されたファイル (Prisma スキーマや GraphQL スキーマなど) のいずれかが Keystone スキーマと同期されていない場合、警告を表示します。
この問題を修正する推奨される方法は、keystone dev を使用してアプリを開始し (これによりこれらのファイルが更新されます)、変更をソースコントロールにコミットすることです。しかし、必要に応じて、–fix フラグを使用して postinstall コマンドにファイルの修正を行わせることもできます。

$ keystone postinstall --fix

build

$ keystone build

このコマンドは、Keystone を実動モードで起動するために必要なファイルを生成します。運用環境のデプロイのビルドフェーズで実行する必要があります。
また、ソース管理にコミットする必要がある生成されたファイルが Keystone スキーマと同期していることも検証されます。

start

$ keystone start

このコマンドは、Keystone を本番モードで起動します。ビルドが生成されている必要があります (上記のビルドを参照)。
このコマンドは、データベースのマイグレーションを生成または適用しません。これらは、本番環境の展開のビルドまたはリリースフェーズで実行する必要があります。

prisma

$ keystone prisma [command]

Keystone の CLI には、プリズマコマンドが含まれており、Keystone プロジェクト内で安全に任意の Prisma CLI コマンドを実行できます。
このコマンドは、生成されたファイル (特に、Prismaスキーマ) が Keystone スキーマと同期されていることを確認し、設定されたデータベース接続文字列も Prisma に渡します。

移行の操作

Keystone プロジェクトで Prisma CLI を使用する主な理由は、Prisma Migrate を使用するためです。たとえば、本番環境でマイグレーションを展開するには、次のように実行します。

$ keystone prisma migrate deploy

これにより、Prisma migrate deploy コマンドが実行されます。
より高度なマイグレーションシナリオで作業を開始すると、migrate resolve および migrate status コマンドも必要になる場合があります。
Keystone は Prisma のワークフローの多くを抽象化していますが、本番環境でアプリケーションを管理する場合には、Prisma Migrate CLI コマンドに詳しくなることを強くお勧めします。

すべてをまとめる

プロジェクトの要件に基づいて Keystone を使用してワークフローをカスタマイズする微妙な方法はたくさんありますが、これはかなり典型的な作業方法です。

git クローンとプル後のポストインストール

postinstall スクリプトを設定することで、ソースコントロールから最新のものを取得し、依存関係をインストールする際に、Keystone の生成されたファイルがすべて存在し、正しい状態になることが保証されます。
これは CI でも実行されるため、lint ルールやテストは最新の Keystone ビルドのバージョンを使用することができます。

プロジェクトの開発

開発用に Keystone を起動するには、keystone dev を使用します。Prisma スキーマファイルや GraphQL スキーマファイル、そしてマイグレーションを含む、生成されたファイルに対する変更は必ずコミットするようにしてください。

運用環境へのデプロイ

ほとんどのアプリケーションホスティングプラットフォームは、新しいデプロイメントに対してビルドスクリプトを指定することができ、アプリが開始されたとき (スケールアップ時を含む) に実行するスタートスクリプトを指定することができます。

ビルドスクリプト

プロジェクトの依存関係をインストールし、ビルドを生成して移行を配置します。

yarn && yarn keystone build && yarn keystone prisma migrate deploy

スクリプトの開始

Keystone を本番モードで起動します。

yarn keystone start

ノート

  • これらの例ではパッケージマネージャーとして yarn を使用していますが、好みに応じて npm や pnpm など他のマネージャーを使用することができます。
  • 上記のコマンドは、このページの上部にある package.json の参照に含まれています。ビルドと開始のコマンドをソースコントロールで一元管理するために、パッケージスクリプトの使用を推奨します。
  • パイプライン内の別々の環境 (例: テスト → ステージング → 本番) でビルドをプロモートする場合は、ビルドスクリプトの一部としてではなく、プロモートステップでマイグレーションを実行する必要があります。
  • ステージングビルドから本番データベースに対してマイグレーションを実行しないように注意することが重要です。本番環境でステージングまたはプレビュー環境を設定している場合は、それらが本番データベースを指していないことを確認してください。