Bỏ qua để đến nội dung
@aws/nx-plugin
Blog

Cơ sở dữ liệu quan hệ Python

Filter this guidePick generator option values to hide sections that don't apply.

Generator này tạo một dự án cơ sở dữ liệu quan hệ Python mới được hỗ trợ bởi Amazon Aurora (PostgreSQL hoặc MySQL), SQLModel để mô hình hóa dữ liệu, và Alembic để di chuyển schema. 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à một database client.

Cách sử dụng

Phần tiêu đề “Cách sử dụng”

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

Phần tiêu đề “Tạo một Cơ sở dữ liệu quan hệ”
Terminal window
pnpm nx g @aws/nx-plugin:py#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
Terminal window
pnpm nx g @aws/nx-plugin:py#rdb --dry-run

Tùy chọn

Phần tiêu đề “Tùy chọn”
Tham sốKiểuMặc địnhMô tả
name Bắt buộcstring-Tên của dự án cơ sở dữ liệu cần tạo
directory stringpackagesThư mục để lưu trữ ứng dụng.
subDirectory string-Thư mục con mà dự án được đặt trong đó. Mặc định là tên dự án.
infra aurora | noneauroraDịch vụ cơ sở dữ liệu quan hệ cần cung cấp.
engine postgres | mysqlpostgresCông cụ cơ sở dữ liệu sử dụng với dịch vụ đã chọn.
databaseUser stringdbadminTê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 sqlmodelsqlmodelFramework ORM sử dụng cho dự án được tạo.
iac inherit | cdk | terraforminheritNhà cung cấp IaC ưu tiên. Mặc định được kế thừa từ lựa chọn ban đầu của bạn.
preferInstallDependencies booleantrueCó nên ưu tiên cài đặt các phụ thuộc sau khi generator chạy hay không. Đặt thành false để hoãn cài đặt khi thực hiện nhiều generator cùng lúc (việc cài đặt vẫn chạy nếu cần thiết để các generator tiếp theo có thể tính toán biểu đồ dự án Nx); cài đặt một lần vào cuối.

Kết quả của Generator

Phần tiêu đề “Kết quả của Generator”

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

  • Thư mục<name>
    • __init__.py Package exports (get_engine, session_context)
    • connection.py Database engine and session factory with IAM authentication
    • utils.py Runtime config and local development helpers
    • migration_handler.py Lambda handler that runs Alembic migrations during deployment
    • create_db_user_handler.py Lambda handler that creates the application database user during deployment
    • Thư mụcmodels
      • example.py Example SQLModel table definition
  • Thư mụcmigrations
    • versions Alembic-generated migration scripts
    • env.py Alembic environment (connects to the database)
    • script.py.mako Alembic migration script template
  • alembic.ini Alembic configuration
  • config.json Local development connection details and runtime config key
  • Dockerfile.migration Container image for the migration handler
  • Dockerfile.create-db-user Container image for the create-db-user handler
  • project.json Project configuration and build targets

Các script phát triển cục bộ được chia sẻ trên tất cả các dự án cơ sở dữ liệu và được tạo vào packages/common/scripts/:

  • Thư mụcpackages/common/scripts/src/rdb
    • pull-image.ts Pulls the database container image
    • start-container.ts Starts a local database container
    • wait-for-postgres-db.ts Waits for the local database to be ready (PostgreSQL)
    • wait-for-mysql-db.ts Waits for the local database to be ready (MySQL)

Cơ sở hạ tầng

Phần tiêu đề “Cơ sở hạ tầng”

Vì generator này cung cấp infrastructure as code dựa trên iac 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:

  • Thư mụcpackages/common/constructs
    • Thư mụcsrc
      • Thư mụcapp/ Constructs for infrastructure specific to a project/generator
        • …
      • Thư mụccore/ Generic constructs which are reused by constructs in app
        • …
      • index.ts Entry point exporting constructs from app
    • project.json Project build targets and configuration
  • 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 Aurora database chung

Kiến trúc

Phần tiêu đề “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 đứng 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 Aurora engine là khác nhau.

Application(Lambda, Agent, ...)RDS ProxyMigrations LambdaAurora(PostgreSQL or MySQL)Secrets Manager(DB credentials) SQL (IAM auth) Schema migrations Admin credentials

Phát triển cục bộ

Phần tiêu đề “Phát triển cục bộ”

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

Phần tiêu đề “Mô hình hóa dữ liệu”

Dự án được tạo sử dụng SQLModel để định nghĩa schema cơ sở dữ liệu của bạn. Quy trình làm việc là model-first: thêm hoặc cập nhật các lớp bảng SQLModel trong thư mục <name>/models/ của dự án cơ sở dữ liệu của bạn, sau đó tạo một migration từ những thay đổi model đó.

Ví dụ về model:

packages/my_db/my_db/models/example.py
from sqlalchemy import Column, String
from sqlmodel import Field, SQLModel




class ExampleModel(SQLModel, table=True):
    id: int | None = Field(default=None, primary_key=True)
    name: str = Field(sa_column=Column(String(255), nullable=False))
    description: str | None = Field(default=None, sa_column=Column(String(255), nullable=True))

Import các model của bạn trong <name>/models/__init__.py để Alembic có thể phát hiện chúng trong quá trình tự động tạo.

Tạo Migrations

Phần tiêu đề “Tạo Migrations”

Sau khi thêm hoặc cập nhật models, sử dụng Alembic để tạo và áp dụng các script migration. Target alembic được tạo tự động khởi động một container cơ sở dữ liệu cục bộ trước khi chạy:

Terminal window
pnpm nx run <project>:alembic revision --autogenerate -m "describe your change"

Điều này tạo một script migration mới trong migrations/versions/. Xem xét script được tạo trước khi áp dụng nó.

Áp dụng migration vào cơ sở dữ liệu cục bộ của bạn:

Terminal window
pnpm nx run <project>:migrate

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

Áp dụng Migrations hiện có

Phần tiêu đề “Áp dụng Migrations hiện có”

Khi bạn pull các file migration được tạo bởi các nhà phát triển khác, áp dụng chúng vào cơ sở dữ liệu cục bộ của bạn:

Terminal window
pnpm nx run <project>:migrate

Chạy các lệnh Alembic

Phần tiêu đề “Chạy các lệnh Alembic”

Target alembic được tạo cung cấp Alembic CLI, vì vậy bạn có thể chạy bất kỳ lệnh Alembic nào đối với cơ sở dữ liệu cục bộ. Xem tài liệu tham khảo lệnh Alembic để biết các lệnh có sẵn.

Terminal window
pnpm nx run <project>:alembic <alembic-command>

Dừng Cơ sở dữ liệu cục bộ

Phần tiêu đề “Dừng Cơ sở dữ liệu cục bộ”

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

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

Phần tiêu đề “Kết nối đến Cơ sở dữ liệu”

Import session_context từ package cơ sở dữ liệu của bạn và sử dụng nó như một async context manager để có được một AsyncSession:

from sqlmodel import select


from my_scope.my_db import session_context
from my_scope.my_db.models.example import ExampleModel


async def example():
    async with session_context() as session:
        results = (await session.execute(select(ExampleModel))).all()

Database client tự động:

  • Lấy cấu hình cơ sở dữ liệu từ AWS AppConfig tại runtime
  • Tạo các token xác thực tạm thời thông qua boto3 RDS Signer cho xác thực IAM
  • Thiết lập kết nối TLS bằng cách sử dụng ssl.create_default_context()

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

Phần tiêu đề “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 iac bạn đã chọn.

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 admin, 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 Admin - Đượ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

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, các subnet riêng tư có egress và các 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.

Nhấp vào đây để xem cấu hình VPC ví dụ.

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

Phần tiêu đề “Quét Image”

Docker image được xây dựng cho dự án này có thể được quét để tìm các lỗ hổng bảo mật 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 image đã xây dựng và thoát với mã khác không 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 một base image không có lỗ hổng bảo mật có thể sửa chữa nào ở 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 (chẳng hạn 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 xây dựng image của bạn (docker hoặc finch), do đó không cần công cụ bổ sung nào. 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 được quét lại. Script root trivy được cung cấp sẽ quét mọi image trong workspace:

Terminal window
pnpm trivy

Loại Bỏ Các Phát Hiện Của Trivy

Phần tiêu đề “Loại Bỏ Các Phát Hiện Của Trivy”

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

Thêm ID lỗ hổng bảo mật (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, hãy tham khảo tài liệu lọc của Trivy.

Cấu hình RDS Proxy

Phần tiêu đề “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 các kết nối cơ sở dữ liệu có thể được chia sẻ giữa các phiên bản ứng dụng, giảm chi phí thiết lập kết nối mới
  • Connection resilience - Tự động xử lý chuyển đổi dự phòng và kết nối lại trong quá trình thay thế hoặc bảo trì phiên bản 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

Tắt RDS Proxy

Phần tiêu đề “Tắt RDS Proxy”

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

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 điểm cuối cụm Aurora.

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

Phần tiêu đề “Yêu cầu SSL khi kết nối không có RDS Proxy”

Amazon RDS CA bundle phải có trong system trust store của runtime.

Container Runtimes
Phần tiêu đề “Container Runtimes”
ADD https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem /etc/pki/ca-trust/source/anchors/global-bundle.pem
RUN update-ca-trust
Zip Lambda Functions
Phần tiêu đề “Zip Lambda Functions”

Đối với các hàm Lambda được triển khai bằng zip (chẳng hạn như py#api FastAPI), CA trust store tích hợp của môi trường thực thi Lambda Amazon Linux 2023 bao gồm các Amazon Root CA được sử dụng bởi RDS.

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 đến cơ sở dữ liệu.

Cluster Instances

Phần tiêu đề “Cluster Instances”

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

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')],
});

Serverless Capacity

Phần tiêu đề “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.

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

Engine Version

Phần tiêu đề “Engine Version”

Cố định một phiên bản Aurora engine 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 Aurora engine mặc định. Nếu bạn thay đổi phiên bản Aurora engine, 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 phiên bản Aurora PostgreSQL và 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
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,
});
engine = mysql
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,
});

Deletion Protection

Phần tiêu đề “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ệ cụm Aurora khỏi bị xóa do nhầm lẫn.

Tắt Bảo Vệ Xóa

Phần tiêu đề “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 mong đợi, 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.

packages/infra/src/stacks/application-stack.ts
import { MyDatabase } from '@my-scope/common-constructs';


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

Removal Policy

Phần tiêu đề “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 hủy cụm thay vì giữ lại.

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

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

Logging và Monitoring

Phần tiêu đề “Logging và Monitoring”
engine = postgres

Log postgresql được xuất cho Aurora PostgreSQL, với phạm vi ghi log chỉ giới hạn ở các câu lệnh DDL (log_statement=ddl) do đó các giá trị tham số của câu lệnh không bao giờ được ghi log — miễn là mỗi câu lệnh được gửi riêng lẻ. log_statement=ddl ghi log toàn bộ văn bản thô của một batch nhiều câu lệnh (ví dụ: một lệnh gọi psql -c "a;b;c" duy nhất) nguyên văn nếu bất kỳ câu lệnh nào trong đó là DDL, bao gồm cả các giá trị DML trong cùng batch đó.

engine = mysql

Các log audit và error được xuất cho Aurora MySQL — general và slowquery được cố ý loại trừ vì chúng ghi lại toàn bộ văn bản câu lệnh, bao gồm cả giá trị DML. Advanced Auditing được giới hạn phạm vi cho các kết nối và DDL (server_audit_events=CONNECT,QUERY_DDL), do đó các giá trị tham số câu lệnh không bao giờ được ghi log.

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). Aurora engine logs cũng được xuất sang CloudWatch Logs theo mặc định, được cấu hình để hiển thị hoạt động ở cấp độ schema mà không làm rò rỉ dữ liệu hàng.

Tắt xuất log cho từng database nếu không cần thiết:

packages/infra/src/stacks/application-stack.ts
import { MyDatabase } from '@my-scope/common-constructs';


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

Encryption Key Rotation

Phần tiêu đề “Encryption Key Rotation”

Khóa KMS được sử dụng để mã hóa cụm Aurora và secret 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 tính năng này 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.

packages/infra/src/stacks/application-stack.ts
import { MyDatabase } from '@my-scope/common-constructs';


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

Kết nối

Phần tiêu đề “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:

Strands AgentsPythonAmazon AuroraPython
Python Agent to Relational DatabaseConnect a Python Agent to an Aurora relational database
FastAPIAmazon AuroraPython
FastAPI to Relational DatabaseConnect a FastAPI to an Aurora relational database
Model Context ProtocolPythonAmazon AuroraPython
Python MCP Server to Relational DatabaseConnect a Python MCP Server to an Aurora relational database