Python 关系数据库

此生成器创建一个新的 Python 关系数据库项目，由 Amazon Aurora（PostgreSQL 或 MySQL）、SQLModel 用于数据建模，以及 Alembic 用于模式迁移提供支持。它生成应用程序代码和基础设施，使用 AWS CDK 或 Terraform 来配置和管理数据库，具有声明式模式定义、自动迁移部署和数据库客户端。

用法

生成关系数据库

CLI

pnpm

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

yarn

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

npm

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

bun

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

您还可以执行试运行以查看哪些文件会被更改

pnpm

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

yarn

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

npm

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

bun

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

VSCode

1. 安装 Nx Console VSCode Plugin 如果您尚未安装
2. 在VSCode中打开Nx控制台
3. 点击 Generate (UI) 在"Common Nx Commands"部分
4. 搜索 @aws/nx-plugin - py#rdb
5. 填写必需参数
6. 点击 Generate

选项

参数	类型	默认值	描述
name 必需	string	-	要生成的数据库项目名称
directory	string	packages	存储应用程序的目录。
subDirectory	string	-	项目所在的子目录。默认为项目名称。
infra	aurora | none	aurora	要配置的关系数据库服务。
engine	postgres | mysql	postgres	与所选服务一起使用的数据库引擎。
databaseUser	string	dbadmin	数据库管理员用户名。默认为 'dbadmin'。
databaseName	string	-	初始数据库名称。默认为项目名称。
framework	sqlmodel	sqlmodel	用于生成项目的 ORM 框架。
iac	inherit | cdk | terraform	inherit	首选的 IaC 提供商。默认情况下,这继承自您的初始选择。
preferInstallDependencies	boolean	true	是否在生成器运行后优先安装依赖项。设置为 false 可在批量运行多个生成器时延迟安装(如果后续生成器需要计算 Nx 项目图,仍会运行安装);最后统一安装一次。

生成器输出

生成器在 <directory>/<name> 目录中创建以下项目结构：

• 文件夹<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
  • 文件夹models

    • example.py Example SQLModel table definition
• 文件夹migrations

  • 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

本地开发脚本在所有数据库项目之间共享，并生成到 packages/common/scripts/：

• 文件夹packages/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)

基础设施

由于此生成器根据您选择的 iac 提供基础设施即代码，它将在 packages/common 中创建一个项目，其中包含相关的 CDK 构造或 Terraform 模块。

通用基础设施即代码项目的结构如下：

CDK

• 文件夹packages/common/constructs

  • 文件夹src

    • 文件夹app/ Constructs for infrastructure specific to a project/generator

      • …
    • 文件夹core/ Generic constructs which are reused by constructs in app

      • …
    • index.ts Entry point exporting constructs from app
  • project.json Project build targets and configuration

Generated Project

此项目使用 ts#project 生成器生成，因此配置了相同的构建目标。

Terraform

• 文件夹packages/common/terraform

  • 文件夹src

    • 文件夹app/ Terraform modules for infrastructure specific to a project/generator

      • …
    • 文件夹core/ Generic modules which are reused by modules in app

      • …
  • project.json Project build targets and configuration

Generated Project

此项目使用 terraform#project 生成器生成，因此配置了相同的构建目标。

CDK

• 文件夹packages/common/constructs/src

  • 文件夹app

    • 文件夹dbs

      • <name>.ts 特定于您的数据库的基础设施
  • 文件夹core

    • 文件夹rdb

      • aurora.ts 通用 Aurora 数据库构造

Terraform

• 文件夹packages/common/terraform/src

  • 文件夹app

    • 文件夹dbs

      • 文件夹<name>

        • <name>.tf 特定于您的数据库的模块
  • 文件夹core

    • 文件夹rdb

      • 文件夹aurora

        • aurora.tf 通用 Aurora 模块

架构

已部署的数据库具有以下架构。默认情况下，Amazon RDS Proxy 位于 Aurora 集群前面以池化连接并启用 IAM 身份验证 — 有关替代方案，请参阅禁用 RDS Proxy。无论您选择 PostgreSQL 还是 MySQL 引擎，架构都是相同的；只有 Aurora 引擎类型不同。

本地开发

数据建模

生成的项目使用 SQLModel 来定义您的数据库模式。工作流程是模型优先的：在数据库项目的 <name>/models/ 目录下添加或更新 SQLModel 表类，然后从这些模型更改生成迁移。

示例模型：

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

在 <name>/models/__init__.py 中导入您的模型，以便 Alembic 在自动生成期间可以发现它们。

创建迁移

在添加或更新模型后，使用 Alembic 生成并应用迁移脚本。生成的 alembic 目标在运行之前会自动启动本地数据库容器：

pnpm

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

yarn

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

npm

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

bun

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

这会在 migrations/versions/ 下生成一个新的迁移脚本。在应用之前请检查生成的脚本。

将迁移应用到您的本地数据库：

pnpm

pnpm nx run <project>:migrate

yarn

yarn nx run <project>:migrate

npm

npx nx run <project>:migrate

bun

bunx nx run <project>:migrate

当您部署 AWS 堆栈时，生成的基础设施会自动将生成的迁移应用到已部署的数据库。

应用现有迁移

当您拉取其他开发人员创建的迁移文件时，将它们应用到您的本地数据库：

pnpm

pnpm nx run <project>:migrate

yarn

yarn nx run <project>:migrate

npm

npx nx run <project>:migrate

bun

bunx nx run <project>:migrate

运行 Alembic 命令

生成的 alembic 目标公开了 Alembic CLI，因此您可以对本地数据库运行任何 Alembic 命令。有关可用命令，请参阅 Alembic 命令参考。

pnpm

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

yarn

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

npm

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

bun

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

停止本地数据库

停止 dev（例如使用 Ctrl+C）会自动删除本地数据库容器，但会保留命名卷，以便您的数据在重启后保持不变。

Windows

由于 Windows 上信号处理的限制，当 dev 停止时容器不会自动删除。您需要手动删除它：

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

将 <engine> 替换为您的容器引擎（docker 或 finch），将 <scope> 替换为您的 Nx 工作空间作用域（例如 proj），将 <db-name> 替换为您的数据库项目名称（例如 my-db）。

连接到数据库

从您的数据库包中导入 session_context 并将其用作异步上下文管理器以获取 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()

数据库客户端会自动：

• 在运行时从 AWS AppConfig 检索数据库配置
• 通过 boto3 RDS Signer 生成临时身份验证令牌以进行 IAM 身份验证
• 使用 ssl.create_default_context() 建立 TLS 连接

运行时配置

这依赖于 RUNTIME_CONFIG_APP_ID 环境变量在运行时从 AWS AppConfig 获取配置。使用此插件构建的项目（API、Agent、MCP 服务器）已自动配置此变量。对于其他项目，请确保在运行时环境中设置 RUNTIME_CONFIG_APP_ID，其值为基础设施配置的 AppConfig 应用程序 ID。有关更多信息，请参阅 运行时配置指南。

部署您的数据库

关系数据库生成器会根据您选择的 iac 创建 CDK 或 Terraform 基础设施。

CDK

CDK 构造在 common/constructs 中创建。使用示例：

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

这将配置一个带有 RDS Proxy、管理员凭证、应用程序数据库用户、运行时配置注册和迁移处理程序的 Aurora 集群。

生成的基础设施会创建两个数据库用户：

• 管理员用户 - 在集群配置期间创建，凭证存储在 AWS Secrets Manager 中
• 应用程序用户 - 通过 Lambda 自定义资源创建，启用 IAM 身份验证，并在应用程序数据库上具有 DML 权限（SELECT、INSERT、UPDATE、DELETE）

Terraform

Terraform 模块在 common/terraform 中创建。使用示例：

packages/infra/src/main.tf

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

  # Database subnets have no internet route; Lambda subnets need NAT egress.
  vpc_id              = aws_vpc.main.id
  database_subnet_ids = aws_subnet.database[*].id
  lambda_subnet_ids   = aws_subnet.private[*].id

  tags = local.common_tags
}

这将配置一个带有 RDS Proxy、管理员凭证、create-db-user Lambda、运行时配置注册、迁移 Lambda 和容器注册表资源的 Aurora 集群。

数据库模块在 database 运行时配置命名空间下注册其连接详细信息。在实例化共享运行时配置 AppConfig 应用程序时包含此命名空间：

packages/infra/src/main.tf

module "runtime_config_appconfig" {
  source = "../../common/terraform/src/core/runtime-config/appconfig"

  application_name = "my-app-runtime-config"
  namespaces       = ["connection", "agentcore", "database"]
}

生成的基础设施会创建两个数据库用户：

• 管理员用户 - 在集群配置期间创建，凭证存储在 AWS Secrets Manager 中
• 应用程序用户 - 通过 Lambda 函数创建，启用 IAM 身份验证，并在应用程序数据库上具有 DML 权限（SELECT、INSERT、UPDATE、DELETE）

应用程序用户会自动创建，具有随机名称和 IAM 身份验证。生成的数据库客户端已配置为使用短期 RDS 令牌以此用户身份进行身份验证，因此您的应用程序代码永远不会处理数据库密码。

您的 VPC 应包括公有子网、具有出口的私有子网和私有隔离子网。数据库可以在私有隔离子网中运行，而应用程序 Lambda 函数应在具有出口的私有子网中运行，以便它们可以访问 AWS 服务（如 AppConfig）。

点击此处查看 VPC 配置示例。

使用 connection 生成器将项目连接到此数据库 — 请参阅相关计算类型（例如 FastAPI、MCP 服务器、代理）的连接指南，了解访问数据库所需的基础设施配置。

镜像扫描

为此项目构建的 Docker 镜像可以使用 Trivy 进行漏洞扫描，该工具从 ECR 托管的 Trivy 镜像运行。

项目中会添加一个 trivy 目标，用于扫描构建的镜像，如果发现任何 HIGH 或 CRITICAL 严重级别的漏洞，将以非零状态退出。生成的 Dockerfile 使用的基础镜像在生成时没有已知的可修复漏洞（这些严重级别），并升级捆绑的工具（如 npm）以保持这种状态。

扫描使用与镜像构建相同的容器引擎（docker 或 finch），因此不需要额外的工具。由于扫描仅在镜像更改时重新运行，未更改的镜像不会被重新扫描。提供的 trivy 根脚本会扫描工作区中的每个镜像：

pnpm

pnpm trivy

yarn

yarn trivy

npm

npm run trivy

bun

bun trivy

在 CI 中运行 Trivy

扫描故意不连接到 build，因为这可能会在开发过程中迭代时引入不必要的摩擦，因为 Trivy 的漏洞数据库会不断更新新的 CVE。

相反，我们建议在部署到生产阶段之前，在 CI 流水线中将上述命令作为专门的步骤运行。

忽略无法修复的漏洞

扫描使用 --ignore-unfixed 运行，因此没有可用修复的漏洞不会导致构建失败，因为它们无法通过升级 Dockerfile 中的工具来解决——它们不会在构建的扫描输出中报告。随着新漏洞的披露，扫描结果可能会随时间而变化，因此请通过运行 trivy image <your-image>（不带该标志）定期检查镜像，并在发布修复后针对更新的基础镜像重新构建（或添加容器步骤以应用可用的补丁）。

抑制 Trivy 发现

在某些情况下，您可能希望抑制特定的漏洞，例如当尚无可用修复且您已评估风险为可接受时。

将漏洞 ID（每行一个）添加到项目根目录中的 .trivyignore 文件（即 project.json 旁边）：

.trivyignore

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

有关过滤发现的更多详细信息，请参阅 Trivy 过滤文档。

RDS Proxy 配置

生成的基础设施默认包含一个 RDS Proxy，它位于您的应用程序和 Aurora 集群之间。RDS Proxy 提供了几个好处：

• 连接池 - 维护一个可以在应用程序实例之间共享的数据库连接池，减少建立新连接的开销
• 连接弹性 - 在 Aurora 实例替换或维护期间自动处理故障转移和重新连接
• IAM 身份验证 - 支持基于 IAM 的数据库身份验证，无需在应用程序代码中管理数据库凭证
• 改进的安全性 - 对所有连接强制执行 TLS 加密

额外费用

RDS Proxy 默认启用，但会在 Aurora 集群成本之上产生额外费用。有关详细信息，请参阅 AWS RDS Proxy 定价。如果您希望禁用代理，请参阅下面的部分。

禁用 RDS Proxy

您可以按如下方式禁用 RDS 代理：

CDK

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

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

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

当 RDS Proxy 被禁用时，您的应用程序将直接连接到 Aurora 集群端点。

Terraform

默认情况下，RDS Proxy 是启用的。如果需要，您可以禁用它：

packages/infra/src/main.tf

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

当 RDS Proxy 被禁用时，您的应用程序将直接连接到 Aurora 集群端点。

不使用 RDS Proxy 连接时的 SSL 要求

Amazon RDS CA 捆绑包必须位于运行时的系统信任存储中。

容器运行时

Amazon Linux

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

Debian

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 函数

对于 zip 部署的 Lambda 函数（例如 py#api FastAPI），Amazon Linux 2023 Lambda 执行环境的内置 CA 信任存储包含 RDS 使用的 Amazon 根 CA。

使用 RDS Proxy 时，您无需在连接到数据库的运行时中配置 RDS CA 捆绑包。

集群实例

为您的 Aurora 集群配置写入器和读取器实例。

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
}

无服务器容量

控制 Aurora Serverless v2 扩展限制以匹配您的工作负载。

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
}

引擎版本

固定特定的 Aurora 引擎版本。

默认情况下，生成的本地数据库容器镜像与默认的 Aurora 引擎版本匹配。如果您更改 Aurora 引擎版本，建议同时使用匹配的本地容器镜像版本以获得最大兼容性。请参阅 AWS 发布说明中的 Aurora PostgreSQL 版本 和 Aurora MySQL 版本 以确定相应的社区数据库版本。

本地数据库镜像在数据库项目根目录中生成的 config.json 文件的 localDev.image 字段中配置。当您更改引擎版本时，请更新该值。

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

删除保护

默认情况下启用删除保护（CDK 中为 deletionProtection: true，Terraform 中为 deletion_protection = true），以保护 Aurora 集群免遭意外删除。

禁用删除保护

您可以为预期会删除数据库的环境禁用删除保护，例如短期开发或预览堆栈。

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
}

删除策略

CDK 构造默认保留 Aurora 集群（removalPolicy: RemovalPolicy.RETAIN）。当您希望 CDK 堆栈删除时改为快照或销毁集群时，请更改此设置。

使用 RemovalPolicy.DESTROY 时，还必须禁用删除保护才能删除集群。

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

对于应随堆栈一起删除数据库的临时环境：

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

数据丢失

RemovalPolicy.DESTROY 将在删除堆栈时永久擦除所有数据。仅在临时环境（例如自动化测试）中使用。对所有持久性和生产堆栈使用 RETAIN 或 SNAPSHOT 以防止数据丢失。

Terraform

Terraform 不使用 CDK 删除策略。默认情况下，该模块在删除时创建最终快照（skip_final_snapshot = false）。要跳过临时环境的最终快照：

packages/infra/src/main.tf

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

数据丢失

skip_final_snapshot = true 将在删除集群时永久擦除所有数据。仅在临时环境（例如自动化测试）中使用。对所有持久性和生产堆栈保持 skip_final_snapshot = false 以防止数据丢失。

日志记录和监控

engine = postgres

postgresql 日志会导出到 Aurora PostgreSQL，日志记录范围仅限于 DDL 语句（log_statement=ddl），因此永远不会记录语句参数值——只要每个语句单独发送。log_statement=ddl 会逐字记录多语句批处理的整个原始文本（例如单个 psql -c "a;b;c" 调用），如果其中任何语句是 DDL，则包括同一批处理中的任何 DML 值。

engine = mysql

对于 Aurora MySQL，会导出 audit 和 error 日志——故意排除了 general 和 slowquery，因为它们会记录完整的语句文本，包括 DML 值。高级审计的范围限定为连接和 DDL（server_audit_events=CONNECT,QUERY_DDL），因此永远不会记录语句参数值。

Performance Insights 默认在 Aurora 写入器实例上启用（使用集群的 KMS 密钥加密）。Aurora 引擎日志也默认导出到 CloudWatch Logs，配置为显示架构级活动而不泄露行数据。

如果不需要，可以按数据库禁用日志导出：

CDK

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

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

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

Terraform

packages/infra/src/main.tf

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

加密密钥轮换

用于加密 Aurora 集群及其凭证密钥的 KMS 密钥默认启用自动密钥轮换。如果您的安全策略在外部管理轮换，请禁用它。

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
}

连接

使用 connection 生成器将此项目与工作空间中的其他项目集成。以下连接涉及此项目：

Python Agent to Relational DatabaseConnect a Python Agent to an Aurora relational database

FastAPI to Relational DatabaseConnect a FastAPI to an Aurora relational database

Python MCP Server to Relational DatabaseConnect a Python MCP Server to an Aurora relational database