Skip to content
@aws/nx-plugin
Blog

TypeScript Agent から Relational Database への接続

connection ジェネレーターは、TypeScript Agent を Relational Database プロジェクトに接続し、エージェントファクトリー内で Prisma クライアントを利用可能にします。

前提条件

Section titled “前提条件”

このジェネレーターを使用する前に、以下を用意してください：

  1. ts#agent プロジェクト
  2. ts#rdb プロジェクト

使用方法

Section titled “使用方法”

ジェネレーターの実行

Section titled “ジェネレーターの実行”
  1. インストール Nx Console VSCode Plugin まだインストールしていない場合
  2. VSCodeでNxコンソールを開く
  3. クリック Generate (UI) "Common Nx Commands"セクションで
  4. 検索 @aws/nx-plugin - connection
  5. 必須パラメータを入力
    • クリック Generate

    Agent プロジェクトをソースとして、リレーショナルデータベースプロジェクトをターゲットとして選択します。プロジェクトに複数のエージェントコンポーネントが含まれている場合は、sourceComponent を指定して明確にします。

    オプション

    Section titled “オプション”
    パラメータ 型 デフォルト 説明
    sourceProject 必須 string - ソース プロジェクト
    targetProject 必須 string - 接続先のターゲット プロジェクト
    sourceComponent string - 接続元のソース コンポーネント (コンポーネント名、ソース プロジェクト ルートからの相対パス、またはジェネレーター ID)。プロジェクトをソースとして明示的に選択するには '.' を使用します。
    targetComponent string - 接続先のターゲット コンポーネント (コンポーネント名、ターゲット プロジェクト ルートからの相対パス、またはジェネレーター ID)。プロジェクトをターゲットとして明示的に選択するには '.' を使用します。

    ジェネレーターの出力

    Section titled “ジェネレーターの出力”

    ジェネレーターは、エージェントのソースディレクトリ内の2つのファイルを変更します：

    • Directorypackages/my-service/src/my-agent
      • agent.ts getAgent 内で取得され、ツールで利用可能な Prisma クライアント
      • Dockerfile Aurora への SSL 接続用に RDS CA バンドルがインストールされる

    さらに、エージェントの <agent-name>-serve-local ターゲットが、データベースの serve-local ターゲットに依存するように更新されます。

    仕組み

    Section titled “仕組み”

    Prisma クライアントは getAgent() 内でインスタンス化されます。ts#agent ジェネレーターはセッションごとに単一の Agent を設定するため、クライアントもセッションの存続期間中再利用されます。

    エージェント定義

    Section titled “エージェント定義”

    getAgent は、本体の先頭で Prisma ゲッターをインポートして呼び出すように更新されます：

    packages/my-service/src/my-agent/agent.ts
    import { getPrisma as getMyDb } from ':my-scope/my-db';
    

    export const getAgent = async () => {
      const myDb = await getMyDb();
      // ...
      return new Agent({ /* use myDb in tools */ });
    };

    複数のデータベース

    Section titled “複数のデータベース”

    異なるターゲットで再度ジェネレーターを実行すると、最初のデータベースと並んで2番目のデータベースが追加されます：

    packages/my-service/src/my-agent/agent.ts
    import { getPrisma as getMyDb } from ':my-scope/my-db';
    import { getPrisma as getOtherDb } from ':my-scope/other-db';
    

    export const getAgent = async () => {
      const myDb = await getMyDb();
      const otherDb = await getOtherDb();
      // ...
      return new Agent({ /* use both clients in tools */ });
    };

    インフラストラクチャ

    Section titled “インフラストラクチャ”

    生成されたエージェントコンストラクトは IGrantable と IConnectable を実装しているため、コンストラクト上で直接データベースへのネットワークおよび IAM アクセスを許可できます。

    packages/infra/src/stacks/application-stack.ts
    import { MyDatabase } from ':my-scope/common-constructs';
    

    const db = new MyDatabase(this, 'Db', { vpc, ... });
    const myAgent = new MyAgent(this, 'MyAgent', { vpc, ... });
    

    db.allowDefaultPortFrom(myAgent);
    db.grantConnect(myAgent);

    allowDefaultPortFrom は、エージェントランタイムがデータベースポートに到達できるようにセキュリティグループルールを開きます。grantConnect は、エージェントの実行ロールに IAM rds-db:connect 権限を付与します。

    RDS Proxy を使用せずに接続する場合の SSL 要件

    Section titled “RDS Proxy を使用せずに接続する場合の SSL 要件”

    ローカル開発

    Section titled “ローカル開発”
    Terminal window
    pnpm nx <agent-name>-serve-local <project-name>

    これにより、エージェントと接続されているすべてのデータベースが起動します。SERVE_LOCAL=true 環境変数により、各 Prisma クライアントは Aurora の代わりにローカルの Docker データベースに接続します。