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

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

Cài đặt Nx Console VSCode Plugin nếu bạn chưa cài đặt
Mở Nx Console trong VSCode
Nhấp Generate (UI) trong phần "Common Nx Commands"
Tìm kiếm @aws/nx-plugin - py#rdb
Điền các tham số bắt buộc
Nhấp Generate

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

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

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

bunx 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

pnpm nx g @aws/nx-plugin:py#rdb --dry-run

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

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

bunx nx g @aws/nx-plugin:py#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 mà dự án được đặt trong đó. 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	Công cụ cơ sở dữ liệu 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	sqlmodel	sqlmodel	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 được kế thừa từ lựa chọn ban đầu của bạn.
preferInstallDependencies	boolean	true	Có 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

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 và session factory với xác thực IAM
- utils.py Runtime config và các helper phát triển cục bộ
- migration_handler.py Lambda handler chạy Alembic migrations trong quá trình triển khai
- create_db_user_handler.py Lambda handler tạo application database user trong quá trình triển khai
- Thư mụcmodels
  - example.py Ví dụ định nghĩa bảng SQLModel
Thư mụcmigrations
- versions Các script migration được tạo bởi Alembic
- env.py Môi trường Alembic (kết nối đến cơ sở dữ liệu)
- script.py.mako Template script migration Alembic
alembic.ini Cấu hình Alembic
config.json Chi tiết kết nối phát triển cục bộ và runtime config key
Dockerfile.migration Container image cho migration handler
Dockerfile.create-db-user Container image cho create-db-user handler
project.json Cấu hình dự án và 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 Kéo database container image
- start-container.ts Khởi động một local database container
- wait-for-postgres-db.ts Chờ cơ sở dữ liệu cục bộ sẵn sàng (PostgreSQL)
- wait-for-mysql-db.ts Chờ cơ sở dữ liệu cục bộ 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
Terraform

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

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

CDK
Terraform

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

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 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, sau đó tạo một migration từ những thay đổi model đó.

Ví dụ model:

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

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 local database container trước khi chạy:

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

yarn nx run <project>:alembic revision --autogenerate -m "describe your change"

npx nx run <project>:alembic revision --autogenerate -m "describe your change"

bunx 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:

pnpm nx run <project>:migrate

yarn nx run <project>:migrate

npx nx run <project>:migrate

bunx 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 migrations đã tạo vào cơ sở dữ liệu đã triển khai.

Áp dụng Migrations hiện có

Khi bạn kéo 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:

pnpm nx run <project>:migrate

yarn nx run <project>:migrate

npx nx run <project>:migrate

bunx nx run <project>:migrate

Chạy các lệnh Alembic

Target alembic được tạo hiển thị 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.

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

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

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

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

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

Dừng dev (ví dụ: với Ctrl+C) tự động xóa local database container, 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.

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

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

Thay thế <engine> bằng container engine của bạn (docker hoặc finch), <scope> bằng Nx workspace scope của bạn (ví dụ: proj), và <db-name> bằng tên dự án cơ sở dữ liệu của bạn (ví dụ: my-db).

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

Import session_context từ database package 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 bằng biến môi trường RUNTIME_CONFIG_APP_ID
Tạo token xác thực tạm thời qua boto3 RDS Signer cho xác thực IAM
Thiết lập kết nối TLS bằng ssl.create_default_context()

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
Terraform

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

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

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

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
Terraform

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

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ó.

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

Tắt RDS Proxy

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

CDK
Terraform

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.

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

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 có RDS Proxy

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

Container Runtimes

Amazon Linux
Debian

ADD https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem /etc/pki/ca-trust/source/anchors/global-bundle.pem
RUN update-ca-trust

ADD https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem /usr/local/share/ca-certificates/rds-global-bundle.crt
RUN update-ca-certificates

Zip Lambda Functions

Đối với các Lambda function được triển khai dưới dạng zip (chẳng hạn như py#api FastAPI), system trust store tích hợp sẵn 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

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

CDK
Terraform

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

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

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
Terraform

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

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

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

Phiên bản Engine

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.

CDK
Terraform

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

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

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

CDK
Terraform

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

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

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

Bảo vệ Xóa

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
Terraform

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

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

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

Chính sách Xóa

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
Terraform

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:

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 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:

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

Logging và 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
Terraform

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

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

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

Xoay vòng Khóa mã hóa

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
Terraform

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

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

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

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:

Python Agent to Relational DatabaseKết nối một Python Agent đến cơ sở dữ liệu quan hệ Aurora

FastAPI to Relational DatabaseKết nối một FastAPI đến cơ sở dữ liệu quan hệ Aurora

Python MCP Server to Relational DatabaseKết nối một Python MCP Server đến cơ sở dữ liệu quan hệ Aurora