Cơ sở dữ liệu Quan hệ TypeScript

Generator này tạo một dự án cơ sở dữ liệu quan hệ mới được hỗ trợ bởi Amazon Aurora (PostgreSQL hoặc MySQL) và Prisma ORM. Nó tạo ra mã ứng dụng và cơ sở hạ tầng cần thiết để cung cấp và quản lý cơ sở dữ liệu bằng AWS CDK hoặc Terraform, với định nghĩa schema khai báo, triển khai migration tự động và ORM client an toàn về kiểu.

Cách sử dụng

Tạo một Cơ sở dữ liệu Quan hệ

Bạn có thể tạo một dự án cơ sở dữ liệu quan hệ mới theo hai cách:

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 - ts#rdb
5. Điền các tham số bắt buộc
6. Nhấp Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#rdb

yarn

yarn nx g @aws/nx-plugin:ts#rdb

npm

npx nx g @aws/nx-plugin:ts#rdb

bun

bunx nx g @aws/nx-plugin:ts#rdb

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:ts#rdb --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#rdb --dry-run

npm

npx nx g @aws/nx-plugin:ts#rdb --dry-run

bun

bunx nx g @aws/nx-plugin:ts#rdb --dry-run

Tùy chọn

Tham số	Kiểu	Mặc định	Mô tả
name Bắt buộc	string	-	Tên của dự án cơ sở dữ liệu cần tạo
directory	string	packages	Thư mục để lưu trữ ứng dụng.
subDirectory	string	-	Thư mục con nơi dự án được đặt. Mặc định là tên dự án.
infra	aurora | none	aurora	Dịch vụ cơ sở dữ liệu quan hệ cần cung cấp.
engine	postgres | mysql	postgres	Database engine sử dụng với dịch vụ đã chọn.
databaseUser	string	dbadmin	Tên người dùng quản trị cơ sở dữ liệu. Mặc định là 'dbadmin'.
databaseName	string	-	Tên cơ sở dữ liệu ban đầu. Mặc định là tên dự án.
framework	prisma	prisma	Framework ORM sử dụng cho dự án được tạo.
iac	inherit | cdk | terraform	inherit	Nhà cung cấp IaC ưu tiên. Mặc định giá trị này được kế thừa từ lựa chọn ban đầu của bạn.
preferInstallDependencies	boolean	true	Có nên cài đặt các dependencies sau khi generator chạy hay không. Đặt thành false để hoãn việc cài đặt khi chạy nhiều generator liên tiếp (việc cài đặt vẫn sẽ chạy nếu cần thiết để các generator tiếp theo có thể tính toán Nx project graph); cài đặt một lần vào cuối.

Kết quả từ Generator

Generator sẽ tạo cấu trúc dự án sau trong thư mục <directory>/<name>:

• Thư mụcprisma

  • Thư mụcmodels

    • example.prisma Định nghĩa model mẫu
  • schema.prisma Schema Prisma chính (tham chiếu các model)
• Thư mụcsrc

  • index.ts Điểm vào của dự án
  • prisma.ts Wrapper Prisma runtime client
  • utils.ts Helper cho runtime config và secret
  • create-db-user-handler.ts Lambda handler được sử dụng để tạo application database user trong quá trình triển khai
  • migration-handler.ts Lambda handler được sử dụng để chạy database migration trong quá trình triển khai
• .gitignore Các mục Git ignore bao gồm output Prisma client được tạo ra
• config.json Chi tiết kết nối phát triển cục bộ và runtime config key
• Dockerfile Định nghĩa container image cho migration handler
• project.json Cấu hình dự án và các build target
• prisma.config.ts Cấu hình cho Prisma CLI

Local development scripts được chia sẻ giữa tất cả các dự án database và được tạo vào packages/common/scripts/:

• Thư mụcpackages/common/scripts/src/rdb

  • pull-image.ts Kéo database container image
  • start-container.ts Khởi động local database container
  • wait-for-postgres-db.ts Chờ local database sẵn sàng (PostgreSQL)
  • wait-for-mysql-db.ts Chờ local database sẵn sàng (MySQL)

Cơ sở hạ tầng

Vì generator này cung cấp infrastructure as code dựa trên iacProvider bạn đã chọn, nó sẽ tạo một dự án trong packages/common bao gồm các CDK constructs hoặc Terraform modules liên quan.

Dự án infrastructure as code chung được cấu trúc như sau:

CDK

• Thư mụcpackages/common/constructs

  • Thư mụcsrc

    • Thư mụcapp/ Constructs cho infrastructure cụ thể của một dự án/generator

      • …
    • Thư mụccore/ Constructs chung được tái sử dụng bởi các constructs trong app

      • …
    • index.ts Entry point xuất các constructs từ app
  • project.json Các build targets và cấu hình của dự án

Dự án được tạo

Dự án này được tạo bằng generator ts#project và do đó cấu hình các build targets giống nhau.

Terraform

• Thư mụcpackages/common/terraform

  • Thư mụcsrc

    • Thư mụcapp/ Terraform modules cho infrastructure cụ thể của một dự án/generator

      • …
    • Thư mụccore/ Modules chung được tái sử dụng bởi các modules trong app

      • …
  • project.json Các build targets và cấu hình của dự án

Dự án được tạo

Dự án này được tạo bằng generator terraform#project và do đó cấu hình các build targets giống nhau.

CDK

• Thư mụcpackages/common/constructs/src

  • Thư mụcapp

    • Thư mụcdbs

      • <name>.ts Cơ sở hạ tầng cụ thể cho cơ sở dữ liệu của bạn
  • Thư mụccore

    • Thư mụcrdb

      • aurora.ts Construct cơ sở dữ liệu Aurora chung

Terraform

• Thư mụcpackages/common/terraform/src

  • Thư mụcapp

    • Thư mụcdbs

      • Thư mục<name>

        • <name>.tf Module cụ thể cho cơ sở dữ liệu của bạn
  • Thư mụccore

    • Thư mụcrdb

      • Thư mụcaurora

        • aurora.tf Module Aurora chung

Kiến trúc

Cơ sở dữ liệu được triển khai có kiến trúc như sau. Theo mặc định, một Amazon RDS Proxy nằm phía trước cụm Aurora để gộp các kết nối và kích hoạt xác thực IAM — xem Vô hiệu hóa RDS Proxy để biết phương án thay thế. Kiến trúc giống nhau cho dù bạn chọn engine PostgreSQL hay MySQL; chỉ có phiên bản engine Aurora khác nhau.

Phát triển Cục bộ

Mô hình hóa Dữ liệu

Dự án được tạo ra sử dụng Prisma ORM để định nghĩa schema cơ sở dữ liệu của bạn và tạo client an toàn về kiểu. Quy trình làm việc là model-first: thêm hoặc cập nhật các file Prisma model trong thư mục prisma/models/ của dự án cơ sở dữ liệu của bạn, sau đó tạo migration từ những thay đổi model đó.

Ví dụ model User:

packages/postgres/prisma/models/user.prisma

model User {
  id          Int      @id @default(autoincrement())
  firstName   String
  lastName    String
}

Để biết thêm chi tiết, xem hướng dẫn chính thức về mô hình hóa dữ liệu với Prisma.

Tạo Database Client

Generator tự động cấu hình target generate để tạo Prisma client TypeScript an toàn về kiểu bất cứ khi nào bạn build dự án. Client được ghi vào generated/prisma (đã thêm vào .gitignore).

Bạn cũng có thể tạo client thủ công bất cứ lúc nào:

pnpm

pnpm nx generate <your-db-project-name>

yarn

yarn nx generate <your-db-project-name>

npm

npx nx generate <your-db-project-name>

bun

bunx nx generate <your-db-project-name>

Sử dụng target prisma để chạy các lệnh Prisma CLI từ workspace root:

pnpm

pnpm nx run <project>:prisma generate

yarn

yarn nx run <project>:prisma generate

npm

npx nx run <project>:prisma generate

bun

bunx nx run <project>:prisma generate

Runtime wrapper trong src/prisma.ts export:

• getPrisma() - tải cài đặt kết nối cơ sở dữ liệu từ AWS AppConfig và tạo Prisma client sử dụng xác thực IAM

Client tự động:

• Lấy cấu hình cơ sở dữ liệu từ AWS AppConfig sử dụng biến môi trường RUNTIME_CONFIG_APP_ID
• Tạo authentication token tạm thời qua AWS RDS Signer cho xác thực IAM
• Quản lý kết nối SSL/TLS với xác thực certificate
• Xử lý connection pooling thông qua các database connection pool bền vững

Tạo Migration

Sau khi thêm hoặc cập nhật các model trong prisma/models/, sử dụng migrate dev để tạo các file migration và áp dụng chúng vào local database của bạn cùng lúc.

Target prisma được tạo ra tự động khởi động local database container trước khi chạy:

pnpm

pnpm nx run <project>:prisma migrate dev

yarn

yarn nx run <project>:prisma migrate dev

npm

npx nx run <project>:prisma migrate dev

bun

bunx nx run <project>:prisma migrate dev

Nếu bạn chỉ muốn tạo các file migration mà không áp dụng chúng vào local database, thêm --create-only:

pnpm

pnpm nx run <project>:prisma migrate dev --create-only

yarn

yarn nx run <project>:prisma migrate dev --create-only

npm

npx nx run <project>:prisma migrate dev --create-only

bun

bunx nx run <project>:prisma migrate dev --create-only

Điều này tạo một thư mục migration mới trong prisma/migrations mỗi khi schema của bạn thay đổi:

• Thư mụcprisma

  • Thư mụcmigrations

    • Thư mục20260405013911_initial_migrations

      • migration.sql
    • migration_lock.toml
  • schema.prisma

Khi bạn triển khai AWS stack, cơ sở hạ tầng được tạo ra tự động áp dụng các migration đã tạo vào cơ sở dữ liệu đã triển khai.

Áp dụng Migration Hiện có

Khi bạn pull các file migration được tạo bởi các developer khác, sử dụng migrate deploy để áp dụng các migration hiện có đó vào local database của bạn.

pnpm

pnpm nx run <project>:prisma migrate deploy

yarn

yarn nx run <project>:prisma migrate deploy

npm

npx nx run <project>:prisma migrate deploy

bun

bunx nx run <project>:prisma migrate deploy

Trong quy trình phát triển cục bộ này, migrate deploy áp dụng các file migration vào local database của bạn; nó không triển khai cơ sở dữ liệu lên AWS.

Chạy Lệnh Prisma

Target prisma được tạo ra expose Prisma CLI, vì vậy bạn có thể sử dụng nó để chạy bất kỳ lệnh nào được Prisma hỗ trợ với local database. Xem Prisma CLI reference để biết các lệnh có sẵn.

pnpm

pnpm nx run <project>:prisma <prisma-command>

yarn

yarn nx run <project>:prisma <prisma-command>

npm

npx nx run <project>:prisma <prisma-command>

bun

bunx nx run <project>:prisma <prisma-command>

Using Prisma Studio

Prisma Studio là trình chỉnh sửa trực quan cho local database của bạn. Sử dụng nó để duyệt bảng, kiểm tra và chỉnh sửa bản ghi, lọc dữ liệu, theo dõi quan hệ và chạy raw SQL qua SQL console tích hợp. Nó hữu ích để xác minh migration và seeding test data trong quá trình phát triển. Khởi chạy nó với:

pnpm

pnpm nx run <project>:prisma studio

yarn

yarn nx run <project>:prisma studio

npm

npx nx run <project>:prisma studio

bun

bunx nx run <project>:prisma studio

Dừng Cơ sở dữ liệu Local

Dừng dev (ví dụ với Ctrl+C) sẽ tự động xóa container database local, nhưng vẫn giữ nguyên named volume để dữ liệu của bạn được lưu trữ qua các lần khởi động lại.

Windows

Do giới hạn xử lý tín hiệu trên Windows, container không bị tự động xóa khi dev bị dừng. Bạn cần xóa thủ công:

<engine> rm -f <scope>-<db-name>

Thay <engine> bằng container engine của bạn (docker hoặc finch), <scope> bằng scope Nx workspace của bạn (ví dụ proj), và <db-name> bằng tên dự án database của bạn (ví dụ my-db).

Kết nối với Cơ sở dữ liệu

Trong bất kỳ dự án TypeScript nào, import getPrisma từ package cơ sở dữ liệu của bạn và gọi nó để lấy Prisma client an toàn về kiểu:

import { getPrisma } from ':my-scope/db';

const prisma = await getPrisma();
const users = await prisma.user.findMany({ orderBy: { id: 'asc' } });

getPrisma() trả về một client được khởi tạo lười biếng và được cache. Các lần gọi tiếp theo trong cùng một Lambda execution context sẽ tái sử dụng connection pool hiện có thay vì mở một kết nối mới.

Prisma client expose các model được type đầy đủ được lấy từ schema prisma/models/ của bạn, cung cấp cho bạn type safety từ đầu đến cuối từ cơ sở dữ liệu cho đến API response.

Triển khai Cơ sở dữ liệu của bạn

Trình tạo cơ sở dữ liệu quan hệ tạo ra cơ sở hạ tầng CDK hoặc Terraform dựa trên iacProvider bạn đã chọn.

CDK

Construct CDK được tạo trong common/constructs. Ví dụ sử dụng:

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

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

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);
    ...
    const db = new MyDatabase(this, 'Db', {
      vpc,
      vpcSubnets: {
        subnetType: SubnetType.PRIVATE_ISOLATED,
      }
    });
  }
}

Điều này cung cấp một cụm Aurora với RDS Proxy, thông tin xác thực quản trị, người dùng cơ sở dữ liệu ứng dụng, đăng ký cấu hình runtime và trình xử lý migration.

Cơ sở hạ tầng được tạo ra tạo hai người dùng cơ sở dữ liệu:

• Người dùng quản trị - Được tạo trong quá trình cung cấp cụm với thông tin xác thực được lưu trữ trong AWS Secrets Manager
• Người dùng ứng dụng - Được tạo thông qua tài nguyên tùy chỉnh Lambda với xác thực IAM được bật và các đặc quyền DML (SELECT, INSERT, UPDATE, DELETE) trên cơ sở dữ liệu ứng dụng

Terraform

Module Terraform được tạo trong common/terraform. Ví dụ sử dụng:

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

  tags = local.common_tags
}

Điều này cung cấp một cụm Aurora với RDS Proxy, thông tin xác thực quản trị, Lambda create-db-user, đăng ký cấu hình runtime, Lambda migration và tài nguyên container registry.

Cơ sở hạ tầng được tạo ra tạo hai người dùng cơ sở dữ liệu:

• Người dùng quản trị - Được tạo trong quá trình cung cấp cụm với thông tin xác thực được lưu trữ trong AWS Secrets Manager
• Người dùng ứng dụng - Được tạo thông qua hàm Lambda với xác thực IAM được bật và các đặc quyền DML (SELECT, INSERT, UPDATE, DELETE) trên cơ sở dữ liệu ứng dụng

Người dùng ứng dụng được tự động tạo với tên ngẫu nhiên và xác thực IAM. Client cơ sở dữ liệu được tạo đã được cấu hình sẵn để xác thực với tư cách người dùng này bằng cách sử dụng token RDS có thời hạn ngắn, vì vậy mã ứng dụng của bạn không bao giờ xử lý mật khẩu cơ sở dữ liệu.

VPC của bạn nên bao gồm các subnet công khai, subnet riêng tư có egress và subnet riêng tư bị cô lập. Cơ sở dữ liệu có thể chạy trong các subnet riêng tư bị cô lập, trong khi các hàm Lambda ứng dụng nên chạy trong các subnet riêng tư có egress để chúng có thể truy cập các dịch vụ AWS như AppConfig.

CDK

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

const vpc = new Vpc(this, 'Vpc', {
  subnetConfiguration: [
    {
      name: 'public',
      subnetType: SubnetType.PUBLIC,
    },
    {
      name: 'private_with_egress',
      subnetType: SubnetType.PRIVATE_WITH_EGRESS,
    },
    {
      name: 'private_isolated',
      subnetType: SubnetType.PRIVATE_ISOLATED,
    },
  ],
});

Terraform

packages/infra/src/main.tf

module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "~> 6.0"

  name = "app"
  ...
  public_subnet_names  = ["public"]
  private_subnet_names = ["private_with_egress"]
  intra_subnet_names   = ["private_isolated"]

  enable_nat_gateway = true
  single_nat_gateway = true
}

Sử dụng trình tạo connection để kết nối một dự án với cơ sở dữ liệu này — xem hướng dẫn kết nối cho loại compute liên quan (ví dụ: FastAPI, MCP server, agent) để biết cách kết nối cơ sở hạ tầng cần thiết để truy cập nó.

Quét Image

Docker image được xây dựng cho dự án này được quét các lỗ hổng bảo mật như một phần của quá trình build bằng cách sử dụng Trivy, chạy từ ECR-hosted Trivy image.

Một target trivy được thêm vào dự án của bạn để quét built image và làm thất bại build nếu phát hiện bất kỳ lỗ hổng bảo mật mức độ nghiêm trọng HIGH hoặc CRITICAL nào. Dockerfile được tạo ra sử dụng base image không có lỗ hổng bảo mật có thể sửa chữa được biết đến với các mức độ nghiêm trọng này tại thời điểm tạo, và nâng cấp các công cụ đi kèm (như npm) để duy trì trạng thái đó.

Quá trình quét sử dụng cùng container engine với quá trình build image của bạn (docker hoặc finch), do đó không cần thêm công cụ nào khác. Vì quá trình quét chỉ được chạy lại khi image thay đổi, một image không thay đổi sẽ không bị quét lại.

Các lỗ hổng không thể sửa chữa được bỏ qua

Quá trình quét chạy với --ignore-unfixed, do đó các lỗ hổng không có bản vá sẵn có sẽ không làm thất bại build, vì chúng không thể được xử lý bằng cách nâng cấp công cụ trong Dockerfile của bạn — chúng không được báo cáo trong kết quả quét của build. Khi các lỗ hổng mới được công bố, kết quả quét có thể thay đổi theo thời gian, do đó hãy xem xét image định kỳ bằng cách chạy trivy image <your-image> mà không có flag, và rebuild lại với base image mới hơn (hoặc thêm các bước container để áp dụng các bản vá có sẵn) khi có bản vá được phát hành.

Loại Trừ Các Phát Hiện Của Trivy

Có thể có những trường hợp bạn muốn loại trừ một lỗ hổng cụ thể, ví dụ khi chưa có bản vá và bạn đã đánh giá rủi ro là chấp nhận được.

Thêm ID lỗ hổng (mỗi dòng một ID) vào file .trivyignore trong thư mục gốc của dự án (tức là bên cạnh project.json của bạn):

.trivyignore

# node-tar arbitrary file write - not exploitable in our usage
CVE-2024-XXXXX

Để biết thêm chi tiết về việc lọc các phát hiện, tham khảo tài liệu lọc của Trivy.

Cấu hình RDS Proxy

Cơ sở hạ tầng được tạo ra bao gồm một RDS Proxy theo mặc định, nằm giữa ứng dụng của bạn và cụm Aurora. RDS Proxy cung cấp một số lợi ích:

• Connection pooling - Duy trì một nhóm kết nối cơ sở dữ liệu có thể được chia sẻ giữa các instance ứng dụng, giảm chi phí thiết lập kết nối mới
• Connection resilience - Tự động xử lý failover và kết nối lại trong quá trình thay thế hoặc bảo trì instance Aurora
• IAM authentication - Hỗ trợ xác thực cơ sở dữ liệu dựa trên IAM, loại bỏ nhu cầu quản lý thông tin xác thực cơ sở dữ liệu trong mã ứng dụng của bạn
• Improved security - Thực thi mã hóa TLS cho tất cả các kết nối

Chi phí bổ sung

RDS Proxy được bật theo mặc định nhưng phát sinh thêm chi phí ngoài chi phí cụm Aurora. Xem AWS RDS Proxy pricing để biết chi tiết. Nếu bạn muốn tắt proxy, hãy xem phần bên dưới.

Tắt RDS Proxy

Bạn có thể tắt RDS proxy như sau:

CDK

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

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

const db = new MyDatabase(this, 'Db', {
  ...
  enableRdsProxy: false,
});

Khi RDS Proxy bị tắt, ứng dụng của bạn kết nối trực tiếp đến endpoint cụm Aurora.

Terraform

Theo mặc định, RDS Proxy được bật. Bạn có thể tắt nó nếu cần:

packages/infra/src/main.tf

module "my_database" {
  source = "../../common/terraform/src/app/dbs/my-database"
  ...
  enable_rds_proxy = false
}

Khi RDS Proxy bị tắt, ứng dụng của bạn kết nối trực tiếp đến endpoint cụm Aurora.

Yêu cầu SSL Khi Kết nối Không qua RDS Proxy

Khi kết nối trực tiếp với Aurora cluster (không qua RDS Proxy), runtime gọi getPrisma() phải tin tưởng Amazon RDS CA bundle. Prisma client được tạo ra bật xác minh certificate; cách bạn cung cấp CA bundle phụ thuộc vào runtime kết nối với cơ sở dữ liệu.

Đối với Amazon RDS, sử dụng global CA bundle từ:

https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem

Runtime Container Images

Nếu bạn chuẩn bị container image riêng cho runtime, tải xuống RDS CA bundle trong Dockerfile của bạn và thêm nó vào trust store của hệ điều hành.

Amazon Linux

RUN curl -fsSL "https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem" \
    -o /etc/pki/ca-trust/source/anchors/rds-bundle.pem && \
    update-ca-trust

Debian

RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates && \
    rm -rf /var/lib/apt/lists/* && \
    curl -fsSL "https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem" \
    -o /usr/local/share/ca-certificates/rds-bundle.crt && \
    update-ca-certificates

Zipped Lambda Functions

Đối với zipped Lambda function sử dụng Node.js 20 hoặc runtime mới hơn, tải Amazon RDS CA bundle bằng cách đặt NODE_EXTRA_CA_CERTS:

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

Để biết thêm chi tiết, xem AWS Lambda SSL/TLS requirements for Amazon RDS connections. Khi sử dụng RDS Proxy, bạn không cần cấu hình RDS CA bundle trong runtime kết nối với cơ sở dữ liệu.

Cluster Instances

Cấu hình các instance writer và reader cho Aurora cluster của bạn.

CDK

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

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

const db = new MyDatabase(this, 'Db', {
  ...
  writer: ClusterInstance.serverlessV2('writer'),
  readers: [ClusterInstance.serverlessV2('reader')],
});

Terraform

packages/infra/src/main.tf

module "my_database" {
  source = "../../common/terraform/src/app/dbs/my-database"
  ...
  instance_count = 2  # 1 writer + 1 reader
}

Serverless Capacity

Kiểm soát giới hạn mở rộng của Aurora Serverless v2 để phù hợp với khối lượng công việc của bạn.

CDK

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

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

const db = new MyDatabase(this, 'Db', {
  ...
  serverlessV2MinCapacity: 0.5,
  serverlessV2MaxCapacity: 8,
});

Terraform

packages/infra/src/main.tf

module "my_database" {
  source = "../../common/terraform/src/app/dbs/my-database"
  ...
  serverless_min_capacity = 0.5
  serverless_max_capacity = 8
}

Engine Version

Cố định một phiên bản engine Aurora cụ thể.

Theo mặc định, image container cơ sở dữ liệu cục bộ được tạo ra sẽ khớp với phiên bản engine Aurora mặc định. Nếu bạn thay đổi phiên bản engine Aurora, bạn nên sử dụng phiên bản image container cục bộ tương ứng để đảm bảo khả năng tương thích tối đa. Xem ghi chú phát hành của AWS cho các phiên bản Aurora PostgreSQL và các phiên bản Aurora MySQL để xác định phiên bản cơ sở dữ liệu cộng đồng tương ứng.

Image cơ sở dữ liệu cục bộ được cấu hình trong trường localDev.image của tệp config.json được tạo ra trong thư mục gốc của dự án cơ sở dữ liệu của bạn. Cập nhật giá trị đó khi bạn thay đổi phiên bản engine.

engine = postgres

CDK

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

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

const db = new MyDatabase(this, 'Db', {
  ...
  engineVersion: AuroraPostgresEngineVersion.VER_17_7,
});

Terraform

packages/infra/src/main.tf

module "my_database" {
  source = "../../common/terraform/src/app/dbs/my-database"
  ...
  engine_version = "17.7"
}

engine = mysql

CDK

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

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

const db = new MyDatabase(this, 'Db', {
  ...
  engineVersion: AuroraMysqlEngineVersion.VER_3_12_0,
});

Terraform

packages/infra/src/main.tf

module "my_database" {
  source = "../../common/terraform/src/app/dbs/my-database"
  ...
  engine_version = "8.0.mysql_aurora.3.12.0"
}

Deletion Protection

Bảo vệ xóa được bật theo mặc định (deletionProtection: true trong CDK, deletion_protection = true trong Terraform) để bảo vệ Aurora cluster khỏi bị xóa nhầm.

Tắt Bảo Vệ Xóa

Bạn có thể tắt bảo vệ xóa cho các môi trường mà việc xóa cơ sở dữ liệu được dự kiến, chẳng hạn như các stack phát triển hoặc xem trước có thời gian tồn tại ngắn.

CDK

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

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

const db = new MyDatabase(this, 'Db', {
  ...
  deletionProtection: false,
});

Terraform

packages/infra/src/main.tf

module "my_database" {
  source = "../../common/terraform/src/app/dbs/my-database"
  ...
  deletion_protection = false
}

Removal Policy

Cấu trúc CDK giữ lại cụm Aurora theo mặc định (removalPolicy: RemovalPolicy.RETAIN). Thay đổi điều này khi bạn muốn việc xóa CDK stack tạo snapshot hoặc phá hủy cụm thay vào đó.

Khi sử dụng RemovalPolicy.DESTROY, bảo vệ xóa cũng phải được tắt trước khi cụm có thể bị xóa.

CDK

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

import { RemovalPolicy } from 'aws-cdk-lib';
import { MyDatabase } from ':my-scope/common-constructs';

const db = new MyDatabase(this, 'Db', {
  ...
  removalPolicy: RemovalPolicy.SNAPSHOT,
});

Đối với môi trường tạm thời mà cơ sở dữ liệu nên được xóa cùng với stack:

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

import { RemovalPolicy } from 'aws-cdk-lib';
import { MyDatabase } from ':my-scope/common-constructs';

const db = new MyDatabase(this, 'Db', {
  ...
  deletionProtection: false,
  removalPolicy: RemovalPolicy.DESTROY,
});

Terraform

Terraform không sử dụng chính sách xóa của CDK. Theo mặc định, module tạo một snapshot cuối cùng khi xóa (skip_final_snapshot = false). Để bỏ qua snapshot cuối cùng cho môi trường tạm thời:

packages/infra/src/main.tf

module "my_database" {
  source = "../../common/terraform/src/app/dbs/my-database"
  ...
  deletion_protection = false
  skip_final_snapshot = true
}

Data Loss

skip_final_snapshot = true sẽ xóa vĩnh viễn tất cả dữ liệu khi cụm bị xóa. Chỉ sử dụng trong các môi trường tạm thời (chẳng hạn như các bài kiểm tra tự động). Giữ skip_final_snapshot = false cho tất cả các stack liên tục và sản xuất để ngăn chặn mất dữ liệu.

Logging and Monitoring

Performance Insights được bật trên Aurora writer instance theo mặc định (được mã hóa bằng KMS key của cluster). Bạn cũng có thể xuất các nhật ký Aurora engine sang CloudWatch Logs (postgresql cho Aurora PostgreSQL; audit, error, general và slowquery cho Aurora MySQL). Bật xuất nhật ký cho từng cơ sở dữ liệu:

CDK

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

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

const db = new MyDatabase(this, 'Db', {
  ...
  enableCloudwatchLogs: true,
  enablePerformanceInsights: false, // disable if not required
});

Terraform

packages/infra/src/main.tf

module "my_database" {
  source = "../../common/terraform/src/app/dbs/my-database"
  ...
  enable_cloudwatch_logs      = true
  enable_performance_insights = false # disable if not required
}

Encryption Key Rotation

Khóa KMS được sử dụng để mã hóa cụm Aurora và bí mật thông tin xác thực của nó có tính năng xoay vòng khóa tự động được bật theo mặc định. Tắt nó nếu chính sách bảo mật của bạn quản lý việc xoay vòng từ bên ngoài.

CDK

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

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

const db = new MyDatabase(this, 'Db', {
  ...
  enableKeyRotation: false,
});

Terraform

packages/infra/src/main.tf

module "my_database" {
  source = "../../common/terraform/src/app/dbs/my-database"
  ...
  enable_key_rotation = false
}

Hạn chế

engine = mysql

MySQL: API Gateway Streaming Mode

Khi sử dụng Aurora MySQL với API Gateway streaming response (ví dụ: với httpBatchStreamLink của tRPC), Prisma MySQL client giữ Node.js event loop sau khi một query hoàn thành, ngăn Lambda flush stream và kết thúc request.

Để giải quyết vấn đề này, ngắt kết nối client một cách rõ ràng trong khối finally sau mỗi query để event loop được tự do thoát và streaming response có thể hoàn thành.

Tùy chọn 1: per-procedure

export const listExampleTable = publicProcedure
  .output(z.array(ExampleTableSchema))
  .query(async () => {
    const prisma = await getPrisma();
    try {
      return await prisma.exampleTable.findMany();
    } finally {
      await prisma.$disconnect();
    }
  });

Tùy chọn 2: tRPC middleware

Nếu bạn đang sử dụng pattern middleware, thêm lệnh gọi $disconnect() vào middleware để tất cả các procedure được xây dựng trên nó được bao phủ tự động:

packages/api/src/middleware/db.ts

import { getPrisma } from ':my-scope/db';
import { initTRPC } from '@trpc/server';

export interface IDbContext {
  db: Awaited<ReturnType<typeof getPrisma>>;
}

export const createDbPlugin = () => {
  const t = initTRPC.context<IDbContext>().create();
  return t.procedure.use(async (opts) => {
    const db = await getPrisma();
    try {
      return await opts.next({
        ctx: {
          ...opts.ctx,
          db,
        },
      });
    } finally {
      await db.$disconnect();
    }
  });
};

Ghi chú

Điều này không bắt buộc đối với PostgreSQL. PostgreSQL adapter sử dụng connection pool pg được cấu hình với allowExitOnIdle: true, cho phép event loop thoát một cách tự nhiên mà không cần ngắt kết nối rõ ràng. Do hạn chế này, getPrisma() cho MySQL không cache client hoặc tái sử dụng kết nối qua các lần gọi Lambda warm. Một kết nối mới được mở cho mỗi lần gọi, không giống như PostgreSQL adapter cache client ở cấp module và tái sử dụng cùng một connection pool.

MySQL: IAM Token Expiry

RDS IAM authentication token hết hạn sau 15 phút. MySQL Prisma client lưu giữ IAM token như một giá trị tĩnh tại thời điểm getPrisma() được gọi. Một kết nối mở hiện có không bị ảnh hưởng, nhưng nếu một kết nối mới cần được thiết lập sau khi token đã hết hạn, xác thực sẽ thất bại. PostgreSQL adapter tránh điều này bằng cách làm mới token một cách động mỗi khi pool mở một kết nối mới, nhưng MySQL adapter không có cơ chế tương đương.

Chú ý

Hãy cẩn thận với các tác vụ chạy lâu hơn 15 phút. Nếu MySQL client cần mở một kết nối mới sau khi IAM token ban đầu đã hết hạn, xác thực sẽ thất bại.

Đối với các tác vụ chạy lâu như batch job hoặc data migration, gọi getPrisma() ở đầu mỗi đơn vị công việc thay vì một lần cho toàn bộ hoạt động. Bởi vì getPrisma() luôn tạo một client mới và lấy một IAM token mới cho MySQL, điều này đảm bảo mỗi kết nối xác thực với một token hợp lệ.

Kết nối

Sử dụng generator connection để tích hợp dự án này với các dự án khác trong workspace của bạn. Các kết nối sau liên quan đến dự án này:

tRPC API to Relational DatabaseKết nối tRPC API với cơ sở dữ liệu quan hệ Aurora

Smithy API to Relational DatabaseKết nối Smithy API với cơ sở dữ liệu quan hệ Aurora

TypeScript Agent to Relational DatabaseKết nối TypeScript Agent với cơ sở dữ liệu quan hệ Aurora

MCP Server to Relational DatabaseKết nối TypeScript MCP Server với cơ sở dữ liệu quan hệ Aurora