tRPC API 连接到关系数据库

connection 生成器将 tRPC API 连接到 关系数据库 项目，生成一个类型安全的 tRPC 中间件插件，使 Prisma 客户端在您的过程上下文中可用。

前置条件

在使用此生成器之前，请确保您拥有：

1. 一个 tRPC API 项目（使用 ts#api 生成）
2. 一个 ts#rdb 项目

使用方法

运行生成器

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

VSCode

1. 安装 Nx Console VSCode Plugin 如果您尚未安装
2. 在VSCode中打开Nx控制台
3. 点击 Generate (UI) 在"Common Nx Commands"部分
4. 搜索 @aws/nx-plugin - connection
5. 填写必需参数
6. 点击 Generate

选择您的 tRPC API 项目作为源，选择您的关系数据库项目作为目标。

选项

参数	类型	默认值	描述
sourceProject 必需	string	-	源项目
targetProject 必需	string	-	要连接到的目标项目
sourceComponent	string	-	要从其连接的源组件（组件名称、相对于源项目根目录的路径或生成器 ID）。使用 '.' 显式选择项目作为源。
targetComponent	string	-	要连接到的目标组件（组件名称、相对于目标项目根目录的路径或生成器 ID）。使用 '.' 显式选择项目作为目标。
preferInstallDependencies	boolean	true	是否在生成器运行后优先安装依赖项。设置为 false 可在批量运行多个生成器时延迟安装（如果后续生成器需要计算 Nx 项目图，仍会运行安装）；在最后统一安装一次。

生成器输出

生成器在您的 tRPC API 项目中创建一个中间件文件：

• 文件夹packages/api/src

  • 文件夹middleware

    • <db-name>.ts tRPC 插件，在过程上下文中暴露 Prisma 客户端

此外，它还会更新您的 tRPC API 的 dev 目标，以便在本地运行时自动启动数据库。

使用中间件

注册插件

将生成的插件添加到您的 tRPC 路由器，这样所有使用它的过程都可以访问数据库：

packages/api/src/router.ts

import { t } from './init.js';
import { createMyDbPlugin } from './middleware/my-db.js';

export const authenticatedProcedure = t.procedure
  .concat(createMyDbPlugin());

在过程中访问数据库

该插件将 IMyDbContext 合并到您的过程上下文中，使 myDb 作为可选属性可用：

packages/api/src/procedures/users.ts

import { z } from 'zod';
import { authenticatedProcedure } from '../router.js';

export const listUsers = authenticatedProcedure
  .output(z.array(z.object({ id: z.string(), name: z.string() })))
  .query(async ({ ctx }) => {
    // ctx.myDb is the Prisma client — typed as Awaited<ReturnType<typeof getPrisma>>
    return await ctx.myDb!.user.findMany();
  });

MySQL：每次请求后断开连接

当目标数据库使用 MySQL 引擎时，生成的中间件会将 opts.next() 包装在一个 try/finally 块中，该块会调用 $disconnect()：

packages/api/src/middleware/my-db.ts

return t.procedure.use(async (opts) => {
  const myDb = await getPrisma();
  try {
    return await opts.next({ ctx: { ...opts.ctx, myDb } });
  } finally {
    await myDb.$disconnect();
  }
});

这解决了 MySQL 适配器在查询后保持 Node.js 事件循环打开的问题，否则会阻止 Lambda 刷新流式响应。在 finally 中断开连接会释放事件循环，以便响应可以完成。详情请参阅 MySQL：API Gateway 流式模式。

PostgreSQL 不需要这样做——其适配器使用配置了 allowExitOnIdle: true 的连接池。

MySQL：IAM 令牌过期

RDS IAM 令牌在 15 分钟后过期。MySQL 适配器在连接时捕获令牌。如果您的 Lambda 保持温暖的时间足够长，令牌过期后，新的连接尝试可能会失败。检查连接错误并再次调用 getPrisma() 以获取带有新令牌的新客户端。详情和解决方法请参阅 MySQL：IAM 令牌过期。

多个数据库

您可以通过使用不同的目标再次运行生成器来连接其他数据库。每个数据库都有自己的插件和上下文接口：

packages/api/src/router.ts

export const dbProcedure = t.procedure
  .concat(createMyDbPlugin())
  .concat(createOtherDbPlugin());

基础设施

要允许您的 API 在运行时连接到数据库，API Lambda 函数必须部署到与数据库相同的 VPC 中，并授予网络和 IAM 访问权限。

CDK

在您的应用程序堆栈中，将 API 部署到与数据库相同的 VPC 中，然后调用 allowDefaultPortFrom 和 grantConnect 来打开网络路径并为每个 Lambda 处理程序授予 IAM rds-db:connect 权限：

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

import { MyDatabase } from '@my-scope/common-constructs';

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

const api = new MyApi(this, 'Api', {
  integrations: MyApi.defaultIntegrations(this)
    .withDefaultOptions({
      vpc,
      vpcSubnets: { subnetType: SubnetType.PRIVATE_WITH_EGRESS },
    })
    .build(),
});

Object.entries(api.integrations).forEach(([operation, integration]) => {
  db.allowDefaultPortFrom(integration.handler, `Allow ${operation} to connect to the database`);
  db.grantConnect(integration.handler);
});

将 API Lambda 函数部署到具有出口的私有子网中，而不是私有隔离子网。在运行时，getPrisma() 从 AWS AppConfig 检索数据库连接详细信息，这是一个公共 AWS 服务端点，需要出站互联网访问。

注意

此示例授予 API 中的每个处理程序访问权限，但如果只有某些处理程序需要访问权限，最好单独配置。

Terraform

将 API 部署到与数据库相同的 VPC 中，通过 additional_iam_policy_statements 授予它 rds-db:connect 权限，并使用一对安全组规则打开网络路径。aws_vpc.main 和 aws_subnet 资源在数据库部署指南中定义：

packages/infra/src/main.tf

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 "api" {
  source     = "../../common/terraform/src/app/apis/my-api"
  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" "api_to_database" {
  description                  = "Allow the API Lambda functions to connect to the database"
  security_group_id            = module.my_database.security_group_id
  referenced_security_group_id = module.api.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" "api_to_database" {
  description                  = "Allow outbound traffic from the API Lambda functions to the database"
  security_group_id            = module.api.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"
}

将 API Lambda 函数部署到具有出口的私有子网中，而不是私有隔离子网。appconfig_application_id/appconfig_application_arn 来自共享的运行时配置 AppConfig 应用程序，该应用程序在根模块中声明一次，而不是来自数据库模块——传递它们会在 Lambda 函数上设置 RUNTIME_CONFIG_APP_ID 并授予它们对应用程序的读取访问权限。在实例化时包含 database 命名空间，以便部署数据库模块的运行时配置条目：

packages/infra/src/main.tf

module "runtime_config_appconfig" {
  source = "../../common/terraform/src/core/runtime-config/appconfig"

  application_name = "my-app-runtime-config"
  namespaces       = ["connection", "agentcore", "database"]
}

不使用 RDS Proxy 连接时的 SSL 要求

对于从 Node.js 20 或更高版本的 Lambda 运行时直接连接 Aurora 集群，需要通过设置 NODE_EXTRA_CA_CERTS 来加载 Amazon RDS CA 证书包：

CDK

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

const api = new Api(this, 'Api', {
  integrations: Api.defaultIntegrations(this)
    .withDefaultOptions({
      environment: {
        NODE_EXTRA_CA_CERTS: '/var/runtime/ca-cert.pem',
      },
    })
    .build(),
});

Terraform

packages/infra/src/main.tf

module "api" {
  source = "..."
  ...

  environment_variables = {
    NODE_EXTRA_CA_CERTS = "/var/runtime/ca-cert.pem"
  }
}

有关更多详细信息，请参阅 AWS Lambda Amazon RDS 连接的 SSL/TLS 要求 和 Amazon RDS Proxy TLS 文档。使用 RDS Proxy 时，您无需在 Lambda 函数中配置 RDS CA 证书包。

本地开发

生成器将您的 tRPC API 的 dev 目标配置为依赖于数据库的 dev 目标，因此运行：

pnpm

pnpm nx dev <api-project-name>

yarn

yarn nx dev <api-project-name>

npm

npx nx dev <api-project-name>

bun

bunx nx dev <api-project-name>

将自动在您的 API 旁边启动本地数据库。