TypeScript Agent to Relational Database

The connection generator wires a TypeScript Agent to a Relational Database project, making a Prisma client available inside your agent factory.

Prerequisites

Before using this generator, ensure you have:

A ts#agent project
A ts#rdb project

Usage

Run the Generator

Run this generator@aws/nx-plugin:connection

CLI
VSCode

$ pnpm nx g @aws/nx-plugin:connection

$ yarn nx g @aws/nx-plugin:connection

$ npx nx g @aws/nx-plugin:connection

$ bunx nx g @aws/nx-plugin:connection

Install the Nx Console VSCode Plugin if you haven't already
Open the Nx Console in VSCode
Click Generate (UI) in the "Common Nx Commands" section
Search for @aws/nx-plugin - connection
Fill in the required parameters
Click Generate

Build your command5

sourceProjectRequired

targetProjectRequired

sourceComponent

targetComponent

preferInstallDependencies

true

--dry-runYou can also perform a dry-run to see what files would be changed

Select your Agent project as the source and your relational database project as the target. If the project contains multiple agent components, specify sourceComponent to disambiguate.

Options

Generator Options5 options

sourceProjectRequiredstring: The source project
targetProjectRequiredstring: The target project to connect to
sourceComponentstring: The source component to connect from (component name, path relative to source project root, or generator id). Use '.' to explicitly select the project as the source.
targetComponentstring: The target component to connect to (component name, path relative to target project root, or generator id). Use '.' to explicitly select the project as the target.
preferInstallDependenciesbooleanDefault: true: Whether to prefer installing dependencies after the generator runs. Set to false to defer installing when batching multiple generators (an install still runs if needed so subsequent generators can compute the Nx project graph); install once at the end.

Generator Output

The generator modifies the following files in your agent’s source directory:

Directorypackages/my-service/src/my-agent
- agent.ts Prisma client fetched inside getAgent and available to tools
- Dockerfile RDS CA bundle installed for SSL connections to Aurora (only when the agent’s infra is agentcore-ecr)

Additionally, the agent’s <agent-name>-dev target is updated to depend on the database’s dev target.

Using the Database in Agent Tools

The Prisma client is instantiated inside getAgent(). Since the ts#agent generator configures a single Agent per session, the client is also reused for the lifetime of the session:

import { getPrisma as getMyDb } from '@my-scope/my-db';

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

Multiple Databases

Running the generator again with a different target adds the second database alongside the first:

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

Infrastructure

The generated agent construct implements IGrantable and IConnectable, so you can grant network and IAM access to the database directly on the construct.

CDK
Terraform

import { SecurityGroup } from 'aws-cdk-lib/aws-ec2';
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 },
    securityGroups: [
      new SecurityGroup(this, 'MyAgentSecurityGroup', { vpc, allowAllOutbound: true }),
    ],
  }),
});

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

allowDefaultPortFrom opens the security group rule so the agent runtime can reach the database port. grantConnect grants IAM rds-db:connect permission to the agent’s execution role.

Run the agent inside the same VPC as the database, grant it rds-db:connect via additional_iam_policy_statements, and open the network path with a pair of security group rules. The aws_vpc.main and aws_subnet resources are defined in the database deployment guide:

module "my_database" {
  source              = "../../common/terraform/src/app/dbs/my-database"
  vpc_id              = aws_vpc.main.id
  database_subnet_ids = aws_subnet.database[*].id
  lambda_subnet_ids   = aws_subnet.private[*].id
}

module "my_agent" {
  source     = "../../common/terraform/src/app/agents/my-agent"
  enable_vpc = true
  vpc_id     = aws_vpc.main.id
  subnet_ids = aws_subnet.private[*].id

  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" {
  description                  = "Allow the agent runtime to connect to the 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" {
  description                  = "Allow outbound traffic from the agent runtime to the 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 come from the shared runtime configuration AppConfig application declared once in your root module, not from the database module. That application exposes the database namespace by default, so the database module’s runtime configuration entry is deployed without further configuration.

SSL Requirements When Connecting Without RDS Proxy

The connection generator updates the Dockerfile to install the Amazon RDS CA bundle at /usr/local/share/ca-certificates/rds-bundle.crt. Set NODE_EXTRA_CA_CERTS to that path so Node.js trusts the certificate when connecting without RDS Proxy:

CDK
Terraform

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

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

For more details, see the Amazon RDS SSL/TLS documentation. When using RDS Proxy, you do not need to configure NODE_EXTRA_CA_CERTS.

Local Development

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

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

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

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

This starts the agent and all connected databases. The LOCAL_DEV=true environment variable causes each Prisma client to connect to its local Docker database instead of Aurora.