tRPC API đến Cơ sở dữ liệu Quan hệ

Trình tạo connection kết nối một tRPC API với dự án Relational Database, tạo ra một plugin middleware tRPC an toàn kiểu giúp cung cấp Prisma client trong ngữ cảnh procedure của bạn.

Điều kiện tiên quyết

Trước khi sử dụng trình tạo này, hãy đảm bảo bạn có:

1. Một dự án ts#trpc-api
2. Một dự án ts#rdb

Cách sử dụng

Chạy Trình tạo

VSCode

1. Cài đặt Nx Console VSCode Plugin nếu bạn chưa cài đặt
2. Mở Nx Console trong VSCode
3. Nhấp Generate (UI) trong phần "Common Nx Commands"
4. Tìm kiếm @aws/nx-plugin - connection
5. Điền các tham số bắt buộc
6. Nhấp 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

Bạn cũng có thể thực hiện chạy thử để xem những tệp nào sẽ bị thay đổi

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

Chọn dự án tRPC API của bạn làm nguồn và dự án cơ sở dữ liệu quan hệ của bạn làm đích.

Tùy chọn

Tham số	Kiểu	Mặc định	Mô tả
sourceProject Bắt buộc	string	-	Dự án nguồn
targetProject Bắt buộc	string	-	Dự án đích để kết nối tới
sourceComponent	string	-	Component nguồn để kết nối từ đó (tên component, đường dẫn tương đối so với thư mục gốc của dự án nguồn, hoặc generator id). Sử dụng '.' để chọn rõ ràng dự án làm nguồn.
targetComponent	string	-	Component đích để kết nối tới (tên component, đường dẫn tương đối so với thư mục gốc của dự án đích, hoặc generator id). Sử dụng '.' để chọn rõ ràng dự án làm đích.

Kết quả của Trình tạo

Trình tạo tạo một tệp middleware trong dự án tRPC API của bạn:

• Thư mụcpackages/api/src

  • Thư mụcmiddleware

    • <db-name>.ts plugin tRPC cung cấp Prisma client trong ngữ cảnh procedure

Ngoài ra, nó cập nhật target serve-local của tRPC API để tự động khởi động cơ sở dữ liệu khi chạy cục bộ.

Sử dụng Middleware

Đăng ký Plugin

Thêm plugin được tạo vào tRPC router của bạn để tất cả các procedure sử dụng nó có quyền truy cập vào cơ sở dữ liệu:

packages/api/src/router.ts

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

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

Truy cập Cơ sở dữ liệu trong Procedures

Plugin hợp nhất IMyDbContext vào ngữ cảnh procedure của bạn, làm cho myDb có sẵn như một thuộc tính tùy chọn:

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 là Prisma client — được định kiểu là Awaited<ReturnType<typeof getPrisma>>
    return await ctx.myDb!.user.findMany();
  });

MySQL: Ngắt kết nối Sau Mỗi Request

Khi cơ sở dữ liệu đích sử dụng engine MySQL, middleware được tạo bọc opts.next() trong một khối try/finally gọi $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();
  }
});

Điều này giải quyết vấn đề adapter MySQL giữ vòng lặp sự kiện Node.js mở sau một truy vấn, điều này sẽ ngăn Lambda xả các phản hồi streaming. Ngắt kết nối trong finally giải phóng vòng lặp sự kiện để phản hồi có thể hoàn thành. Xem MySQL: API Gateway Streaming Mode để biết chi tiết.

PostgreSQL không yêu cầu điều này — adapter của nó sử dụng connection pool được cấu hình với allowExitOnIdle: true.

MySQL: Hết hạn IAM Token

Token IAM của RDS hết hạn sau 15 phút. Adapter MySQL lưu token tại thời điểm kết nối. Nếu Lambda của bạn giữ warm đủ lâu để token hết hạn, các nỗ lực kết nối mới có thể thất bại. Kiểm tra lỗi kết nối và gọi getPrisma() lại để có được một client mới với token mới. Xem MySQL: IAM Token Expiry để biết chi tiết và cách giải quyết.

Nhiều Cơ sở dữ liệu

Bạn có thể kết nối thêm các cơ sở dữ liệu bằng cách chạy lại trình tạo với một đích khác. Mỗi cơ sở dữ liệu có plugin và giao diện ngữ cảnh riêng:

packages/api/src/router.ts

export const dbProcedure = t.procedure
  .concat(createPostgresDbPlugin())
  .concat(createMySqlDbPlugin());

Hạ tầng

Để cho phép API của bạn kết nối với cơ sở dữ liệu tại runtime, các hàm Lambda API phải được triển khai vào cùng VPC với cơ sở dữ liệu và được cấp quyền truy cập mạng và IAM.

CDK

Trong application stack của bạn, triển khai API vào cùng VPC với cơ sở dữ liệu, sau đó gọi allowDefaultPortFrom và grantConnect để mở đường dẫn mạng và cấp quyền IAM rds-db:connect cho mỗi Lambda handler:

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

Triển khai các hàm Lambda API vào private subnet with egress, không phải private isolated subnet. Tại runtime, getPrisma() truy xuất thông tin chi tiết kết nối cơ sở dữ liệu từ AWS AppConfig, đây là một public AWS service endpoint yêu cầu truy cập internet ra ngoài.

Ghi chú

Ví dụ này cấp quyền truy cập cho mọi handler trong API của bạn, nhưng nếu chỉ một số handler cần truy cập thì tốt hơn là cấu hình riêng lẻ.

Terraform

Truyền các output của database module vào API module của bạn để nó có thể truy cập cơ sở dữ liệu và đọc cấu hình runtime của nó:

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 "api" {
  source             = "..."
  vpc_id             = module.vpc.vpc_id
  private_subnet_ids = module.vpc.private_subnet_ids

  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

  environment_variables = {
    RUNTIME_CONFIG_APP_ID = module.my_database.appconfig_application_id
  }
}

Triển khai các hàm Lambda API vào private subnets with egress, không phải private isolated subnets. Đảm bảo API Lambda role có quyền rds-db:connect và security group của nó có thể truy cập database security group trên database port.

Phát triển Cục bộ

Trình tạo cấu hình target serve-local của tRPC API để phụ thuộc vào target serve-local của cơ sở dữ liệu, vì vậy khi chạy:

pnpm

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

yarn

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

npm

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

bun

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

sẽ tự động khởi động cơ sở dữ liệu cục bộ cùng với API của bạn.