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:

1. A ts#agent project
2. A ts#rdb project

Usage

Run the Generator

VSCode

1. Install the Nx Console VSCode Plugin if you haven't already
2. Open the Nx Console in VSCode
3. Click Generate (UI) in the "Common Nx Commands" section
4. Search for @aws/nx-plugin - connection
5. Fill in the required parameters
6. Click 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

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

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

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

Parameter	Type	Default	Description
sourceProject Required	string	-	The source project
targetProject Required	string	-	The target project to connect to
sourceComponent	string	-	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.
targetComponent	string	-	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.

Generator Output

The generator modifies two 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

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

How It Works

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.

Agent Definition

getAgent is updated to import and call the Prisma getter at the top of its body:

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

Multiple Databases

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

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

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

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 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.

Terraform

Pass the database module outputs into your agent module so it can reach the database and read its runtime configuration:

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
}

module "my_agent" {
  source = "../../common/terraform/src/app/agents/my-agent"

  appconfig_application_id     = module.my_database.appconfig_application_id
  database_cluster_resource_id = module.my_database.cluster_resource_id
  database_runtime_user        = module.my_database.database_runtime_user
  database_security_group_id   = module.my_database.security_group_id
  database_port                = module.my_database.cluster_port
}

Ensure the agent’s execution role has rds-db:connect permission and that its security group can reach the database security group on the database port.

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

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"
  }
}

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

pnpm nx <agent-name>-serve-local <project-name>

yarn

yarn nx <agent-name>-serve-local <project-name>

npm

npx nx <agent-name>-serve-local <project-name>

bun

bunx nx <agent-name>-serve-local <project-name>

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