TypeScript Agent tới Cơ sở dữ liệu quan hệ

Generator connection kết nối một TypeScript Agent với dự án Relational Database, làm cho Prisma client có sẵn bên trong agent factory của bạn.

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

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

1. Một dự án ts#agent
2. Một dự án ts#rdb

Cách sử dụng

Chạy Generator

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 Agent 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. Nếu dự án chứa nhiều agent component, hãy chỉ định sourceComponent để phân biệt.

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 Generator

Generator sửa đổi hai file trong thư mục nguồn của agent của bạn:

• Thư mụcpackages/my-service/src/my-agent

  • agent.ts Prisma client được lấy bên trong getAgent và có sẵn cho các công cụ
  • Dockerfile RDS CA bundle được cài đặt cho kết nối SSL tới Aurora

Ngoài ra, target <agent-name>-serve-local của agent được cập nhật để phụ thuộc vào target serve-local của cơ sở dữ liệu.

Cách hoạt động

Prisma client được khởi tạo bên trong getAgent(). Vì generator ts#agent cấu hình một Agent duy nhất cho mỗi phiên, client cũng được tái sử dụng trong suốt vòng đời của phiên.

Định nghĩa Agent

getAgent được cập nhật để import và gọi Prisma getter ở đầu phần thân của nó:

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

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

Chạy generator lần nữa với một đích khác sẽ thêm cơ sở dữ liệu thứ hai bên cạnh cơ sở dữ liệu đầu tiên:

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

Cơ sở hạ tầng

Construct agent được tạo ra triển khai IGrantable và IConnectable, vì vậy bạn có thể cấp quyền truy cập mạng và IAM cho cơ sở dữ liệu trực tiếp trên 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 mở quy tắc security group để agent runtime có thể truy cập cổng cơ sở dữ liệu. grantConnect cấp quyền IAM rds-db:connect cho execution role của agent.

Terraform

Truyền các output của database module vào agent 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
}

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
}

Đảm bảo execution role của agent có quyền rds-db:connect và security group của nó có thể truy cập security group của cơ sở dữ liệu trên cổng cơ sở dữ liệu.

Yêu cầu SSL khi kết nối không qua RDS Proxy

Nguy hiểm

Unable to load snippet connection/agent-rdb-ssl-requirements for locale vi

Phát triển cục bộ

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>

Lệnh này khởi động agent và tất cả các cơ sở dữ liệu được kết nối. Biến môi trường SERVE_LOCAL=true khiến mỗi Prisma client kết nối với cơ sở dữ liệu Docker cục bộ của nó thay vì Aurora.