TypeScript Agent から Relational Database への接続

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

前提条件

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

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

使用方法

ジェネレーターの実行

VSCode

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

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection

yarn

yarn nx g @aws/nx-plugin:connection

npm

npx nx g @aws/nx-plugin:connection

bun

bunx nx g @aws/nx-plugin:connection

変更されるファイルを確認するためにドライランを実行することもできます

pnpm

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn

yarn nx g @aws/nx-plugin:connection --dry-run

npm

npx nx g @aws/nx-plugin:connection --dry-run

bun

bunx nx g @aws/nx-plugin:connection --dry-run

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

オプション

パラメータ	型	デフォルト	説明
sourceProject 必須	string	-	ソース プロジェクト
targetProject 必須	string	-	接続先のターゲット プロジェクト
sourceComponent	string	-	接続元のソース コンポーネント (コンポーネント名、ソース プロジェクト ルートからの相対パス、またはジェネレーター ID)。プロジェクトをソースとして明示的に選択するには '.' を使用します。
targetComponent	string	-	接続先のターゲット コンポーネント (コンポーネント名、ターゲット プロジェクト ルートからの相対パス、またはジェネレーター ID)。プロジェクトをターゲットとして明示的に選択するには '.' を使用します。
preferInstallDependencies	boolean	true	ジェネレーター実行後に依存関係のインストールを優先するかどうか。複数のジェネレーターをバッチ処理する際にインストールを延期する場合はfalseに設定します（後続のジェネレーターがNxプロジェクトグラフを計算できるよう、必要に応じてインストールは実行されます）。最後に一度だけインストールします。

ジェネレーターの出力

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

• Directorypackages/my-service/src/my-agent

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

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

エージェントツールでのデータベースの使用

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

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 */ });
};

複数のデータベース

異なるターゲットで再度ジェネレーターを実行すると、最初のデータベースと並んで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 */ });
};

インフラストラクチャ

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

CDK

packages/infra/src/stacks/application-stack.ts

import { RuntimeNetworkConfiguration } from 'aws-cdk-lib/aws-bedrockagentcore';
import { MyDatabase } from ':my-scope/common-constructs';

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

const myAgent = new MyAgent(this, 'MyAgent', {
  networkConfiguration: RuntimeNetworkConfiguration.usingVpc(this, {
    vpc,
    vpcSubnets: { subnetType: SubnetType.PRIVATE_WITH_EGRESS },
  }),
});

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

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

Terraform

エージェントをデータベースと同じ VPC 内で実行し、additional_iam_policy_statements を介して rds-db:connect を付与し、セキュリティグループルールのペアでネットワークパスを開きます：

packages/infra/src/main.tf

module "my_database" {
  source              = "../../common/terraform/src/app/dbs/my-database"
  vpc_id              = module.vpc.vpc_id
  database_subnet_ids = module.vpc.private_isolated_subnet_ids
  lambda_subnet_ids   = module.vpc.private_subnet_ids
}

module "my_agent" {
  source     = "../../common/terraform/src/app/agents/my-agent"
  enable_vpc = true
  vpc_id     = module.vpc.vpc_id
  subnet_ids = module.vpc.private_subnet_ids

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn

  additional_iam_policy_statements = [
    {
      Effect = "Allow"
      Action = ["rds-db:connect"]
      Resource = [
        "arn:aws:rds-db:${data.aws_region.current.region}:${data.aws_caller_identity.current.account_id}:dbuser:${module.my_database.connect_resource_id}/${module.my_database.database_runtime_user}"
      ]
    }
  ]
}

resource "aws_vpc_security_group_ingress_rule" "agent_to_database" {
  security_group_id            = module.my_database.security_group_id
  referenced_security_group_id = module.my_agent.security_group_id
  from_port                    = module.my_database.cluster_port
  to_port                      = module.my_database.cluster_port
  ip_protocol                  = "tcp"
}

resource "aws_vpc_security_group_egress_rule" "agent_to_database" {
  security_group_id            = module.my_agent.security_group_id
  referenced_security_group_id = module.my_database.security_group_id
  from_port                    = module.my_database.cluster_port
  to_port                      = module.my_database.cluster_port
  ip_protocol                  = "tcp"
}

appconfig_application_id/appconfig_application_arn は、データベースモジュールからではなく、ルートモジュールで一度宣言された共有 ランタイム設定 AppConfig アプリケーションから取得されます。

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

接続ジェネレーターは、Dockerfile を更新して Amazon RDS CA バンドルを /usr/local/share/ca-certificates/rds-bundle.crt にインストールします。RDS Proxy を使用せずに接続する場合、Node.js が証明書を信頼するように NODE_EXTRA_CA_CERTS をそのパスに設定してください：

CDK

packages/infra/src/stacks/application-stack.ts

new MyAgent(this, 'MyAgent', {
  ...
  environmentVariables: {
    NODE_EXTRA_CA_CERTS: '/usr/local/share/ca-certificates/rds-bundle.crt',
  },
});

Terraform

packages/infra/src/main.tf

module "my_agent" {
  ...
  environment_variables = {
    NODE_EXTRA_CA_CERTS = "/usr/local/share/ca-certificates/rds-bundle.crt"
  }
}

詳細については、Amazon RDS SSL/TLS ドキュメントを参照してください。RDS Proxy を使用する場合、NODE_EXTRA_CA_CERTS を設定する必要はありません。

ローカル開発

pnpm

pnpm nx <agent-name>-dev <project-name>

yarn

yarn nx <agent-name>-dev <project-name>

npm

npx nx <agent-name>-dev <project-name>

bun

bunx nx <agent-name>-dev <project-name>

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