Python リレーショナルデータベース

このジェネレーターは、Amazon Aurora（PostgreSQL または MySQL）、データモデリング用の SQLModel、スキーママイグレーション用の Alembic をベースとした新しい Python リレーショナルデータベースプロジェクトを作成します。AWS CDK または Terraform を使用してデータベースをプロビジョニングおよび管理するために必要なアプリケーションコードとインフラストラクチャを生成し、宣言的なスキーマ定義、自動マイグレーションデプロイ、データベースクライアントを提供します。

使用方法

リレーショナルデータベースを生成する

VSCode
CLI

インストール Nx Console VSCode Plugin まだインストールしていない場合
VSCodeでNxコンソールを開く
クリック Generate (UI) "Common Nx Commands"セクションで
検索 @aws/nx-plugin - py#rdb
必須パラメータを入力
クリック 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

変更されるファイルを確認するためにドライランを実行することもできます

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

オプション

パラメータ	型	デフォルト	説明
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> ディレクトリに以下のプロジェクト構造を作成します：

Directory<name>
- __init__.py パッケージエクスポート（get_engine、session_context）
- connection.py IAM 認証を使用したデータベースエンジンとセッションファクトリ
- utils.py ランタイム設定とローカル開発ヘルパー
- migration_handler.py デプロイ時に Alembic マイグレーションを実行する Lambda ハンドラー
- create_db_user_handler.py デプロイ時にアプリケーションデータベースユーザーを作成する Lambda ハンドラー
- Directorymodels
  - example.py SQLModel テーブル定義の例
Directorymigrations
- versions Alembic が生成したマイグレーションスクリプト
- env.py Alembic 環境（データベースに接続）
- script.py.mako Alembic マイグレーションスクリプトテンプレート
alembic.ini Alembic 設定
config.json ローカル開発接続の詳細とランタイム設定キー
Dockerfile.migration マイグレーションハンドラー用のコンテナイメージ
Dockerfile.create-db-user create-db-user ハンドラー用のコンテナイメージ
project.json プロジェクト設定とビルドターゲット

ローカル開発スクリプトはすべてのデータベースプロジェクト間で共有され、packages/common/scripts/ に生成されます：

Directorypackages/common/scripts/src/rdb
- pull-image.ts データベースコンテナイメージをプル
- start-container.ts ローカルデータベースコンテナを起動
- wait-for-postgres-db.ts ローカルデータベースの準備完了を待機（PostgreSQL）
- wait-for-mysql-db.ts ローカルデータベースの準備完了を待機（MySQL）

インフラストラクチャ

このジェネレータは選択した iacProvider に基づいてInfrastructure as Codeを生成するため、packages/common に関連するCDKコンストラクトまたはTerraformモジュールを含むプロジェクトを作成します。

共通のInfrastructure as Codeプロジェクトは以下の構造を持ちます：

CDK
Terraform

Directorypackages/common/constructs
- Directorysrc
  - Directoryapp/ プロジェクト/ジェネレータ固有のインフラストラクチャ用コンストラクト
    …
  - Directorycore/ app 内のコンストラクトで再利用される汎用コンストラクト
    …
  - index.ts app からコンストラクトをエクスポートするエントリーポイント
- project.json プロジェクトのビルドターゲットと設定

Directorypackages/common/terraform
- Directorysrc
  - Directoryapp/ プロジェクト/ジェネレータ固有のインフラストラクチャ用Terraformモジュール
    …
  - Directorycore/ app 内のモジュールで再利用される汎用モジュール
    …
- project.json プロジェクトのビルドターゲットと設定

CDK
Terraform

Directorypackages/common/constructs/src
- Directoryapp
  - Directorydbs
    <name>.ts データベース固有のインフラストラクチャ
- Directorycore
  - Directoryrdb
    aurora.ts 汎用 Aurora データベースコンストラクト

アーキテクチャ

デプロイされたデータベースは以下のアーキテクチャを持ちます。デフォルトでは、Amazon RDS Proxy が Aurora クラスターの前に配置され、接続をプールし、IAM 認証を有効にします — 代替方法については RDS Proxy を無効にするを参照してください。PostgreSQL または MySQL エンジンのどちらを選択しても、アーキテクチャは同じです。異なるのは Aurora エンジンのフレーバーのみです。

ローカル開発

データモデリング

生成されたプロジェクトは SQLModel を使用してデータベーススキーマを定義します。ワークフローはモデルファーストです：データベースプロジェクトの <name>/models/ ディレクトリ配下に SQLModel テーブルクラスを追加または更新し、それらのモデル変更からマイグレーションを生成します。

モデルの例：

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

Alembic が自動生成時にモデルを検出できるように、<name>/models/__init__.py でモデルをインポートしてください。

マイグレーションの作成

モデルを追加または更新した後、Alembic を使用してマイグレーションスクリプトを生成および適用します。生成された alembic ターゲットは、実行前に自動的にローカルデータベースコンテナを起動します：

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"

これにより、migrations/versions/ 配下に新しいマイグレーションスクリプトが生成されます。適用する前に生成されたスクリプトを確認してください。

ローカルデータベースにマイグレーションを適用します：

pnpm nx run <project>:migrate

yarn nx run <project>:migrate

npx nx run <project>:migrate

bunx nx run <project>:migrate

AWS スタックをデプロイすると、生成されたインフラストラクチャが自動的に生成されたマイグレーションをデプロイされたデータベースに適用します。

既存のマイグレーションの適用

他の開発者が作成したマイグレーションファイルをプルした場合、ローカルデータベースに適用します：

pnpm nx run <project>:migrate

yarn nx run <project>:migrate

npx nx run <project>:migrate

bunx nx run <project>:migrate

Alembic コマンドの実行

生成された alembic ターゲットは Alembic CLI を公開するため、ローカルデータベースに対して任意の Alembic コマンドを実行できます。利用可能なコマンドについては、Alembic コマンドリファレンスを参照してください。

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>

ローカルデータベースの停止

dev を停止する（例：Ctrl+C で）と、ローカルデータベースコンテナは自動的に削除されますが、名前付きボリュームは保持されるため、再起動してもデータは保持されます。

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

データベースクライアントは自動的に以下を行います：

RUNTIME_CONFIG_APP_ID 環境変数を使用して AWS AppConfig からデータベース設定を取得
IAM 認証用に boto3 RDS Signer を介して一時的な認証トークンを生成
ssl.create_default_context() を使用して TLS 接続を確立

データベースのデプロイ

リレーショナルデータベースジェネレーターは、選択した iacProvider に基づいて CDK または Terraform インフラストラクチャを作成します。

CDK
Terraform

CDK コンストラクトは common/constructs に作成されます。使用例：

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 クラスター、管理者認証情報、アプリケーションデータベースユーザー、ランタイム設定の登録、およびマイグレーションハンドラーがプロビジョニングされます。

生成されたインフラストラクチャは、2つのデータベースユーザーを作成します：

管理者ユーザー - クラスターのプロビジョニング中に作成され、認証情報は AWS Secrets Manager に保存されます
アプリケーションユーザー - Lambda カスタムリソースを介して作成され、IAM 認証が有効化され、アプリケーションデータベースに対する DML 権限（SELECT、INSERT、UPDATE、DELETE）が付与されます

Terraform モジュールは common/terraform に作成されます。使用例：

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
}

これにより、RDS Proxy を備えた Aurora クラスター、管理者認証情報、create-db-user Lambda、ランタイム設定の登録、マイグレーション Lambda、およびコンテナレジストリリソースがプロビジョニングされます。

生成されたインフラストラクチャは、2つのデータベースユーザーを作成します：

管理者ユーザー - クラスターのプロビジョニング中に作成され、認証情報は AWS Secrets Manager に保存されます
アプリケーションユーザー - Lambda 関数を介して作成され、IAM 認証が有効化され、アプリケーションデータベースに対する DML 権限（SELECT、INSERT、UPDATE、DELETE）が付与されます

アプリケーションユーザーは、ランダムな名前と IAM 認証で自動的に作成されます。生成されたデータベースクライアントは、短期間有効な RDS トークンを使用してこのユーザーとして認証するように既に設定されているため、アプリケーションコードがデータベースパスワードを処理することはありません。

VPC には、パブリックサブネット、エグレス付きプライベートサブネット、およびプライベート分離サブネットを含める必要があります。データベースはプライベート分離サブネットで実行でき、アプリケーション Lambda 関数は AppConfig などの AWS サービスに到達できるように、エグレス付きプライベートサブネットで実行する必要があります。

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
}

connection ジェネレーターを使用して、プロジェクトをこのデータベースに接続します。データベースに到達するために必要なインフラストラクチャの配線については、関連するコンピュートタイプ（例：FastAPI、MCP サーバー、エージェント）の接続ガイドを参照してください。

RDS Proxy の設定

生成されるインフラストラクチャには、デフォルトでRDS Proxyが含まれており、アプリケーションとAuroraクラスター間に配置されます。RDS Proxyは以下のような利点を提供します：

コネクションプーリング - アプリケーションインスタンス間で共有できるデータベース接続のプールを維持し、新しい接続を確立するオーバーヘッドを削減します
接続の回復性 - Auroraインスタンスの交換やメンテナンス中のフェイルオーバーと再接続を自動的に処理します
IAM認証 - IAMベースのデータベース認証をサポートし、アプリケーションコードでデータベース認証情報を管理する必要がなくなります
セキュリティの向上 - すべての接続に対してTLS暗号化を強制します

RDS Proxyを無効にする

RDS Proxyは次のように無効にできます：

CDK
Terraform

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

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

RDS Proxyが無効になっている場合、アプリケーションはAuroraクラスターエンドポイントに直接接続します。

デフォルトでは、RDS Proxyが有効になっています。必要に応じて無効にできます：

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

RDS Proxyが無効になっている場合、アプリケーションはAuroraクラスターエンドポイントに直接接続します。

RDS Proxy を使用せずに接続する場合の SSL 要件

Amazon RDS CA バンドルは、ランタイムのシステムトラストストアに含まれている必要があります。

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

Zip 形式でデプロイされる Lambda 関数（py#api FastAPI など）の場合、Amazon Linux 2023 Lambda 実行環境の組み込み CA トラストストアには、RDS で使用される Amazon ルート CA が含まれています。

RDS Proxy を使用する場合、データベースに接続するランタイムで RDS CA バンドルを設定する必要はありません。

クラスターインスタンス

Auroraクラスターのライターインスタンスとリーダーインスタンスを設定します。

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
}

サーバーレス容量

ワークロードに合わせてAurora Serverless v2のスケーリング制限を制御します。

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
}

エンジンバージョン

特定のAuroraエンジンバージョンを固定します。

デフォルトでは、生成されたローカルデータベースコンテナイメージはデフォルトのAuroraエンジンバージョンと一致します。Auroraエンジンバージョンを変更する場合は、最大限の互換性を確保するために、一致するローカルコンテナイメージバージョンも使用することをお勧めします。対応するコミュニティデータベースバージョンを特定するには、Aurora PostgreSQLバージョンおよびAurora MySQLバージョンのAWSリリースノートを参照してください。

ローカルデータベースイメージは、データベースプロジェクトルートにある生成されたconfig.jsonファイルのlocalDev.imageフィールドで設定されます。エンジンバージョンを変更する際は、その値を更新してください。

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

削除保護

削除保護はデフォルトで有効になっており（CDKではdeletionProtection: true、Terraformではdeletion_protection = true）、Auroraクラスターを誤削除から保護します。

削除保護を無効にする

短期間の開発環境やプレビュースタックなど、データベースの削除が想定される環境では、削除保護を無効にすることができます。

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
}

削除ポリシー

CDK コンストラクトはデフォルトで Aurora クラスターを保持します（removalPolicy: RemovalPolicy.RETAIN）。CDK スタックの削除時にクラスターのスナップショットを作成するか、破棄する場合は、これを変更してください。

RemovalPolicy.DESTROY を使用する場合、クラスターを削除する前に削除保護も無効にする必要があります。

CDK
Terraform

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

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

スタックと共にデータベースを削除する一時的な環境の場合：

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 は CDK の削除ポリシーを使用しません。デフォルトでは、モジュールは削除時に最終スナップショットを作成します（skip_final_snapshot = false）。一時的な環境で最終スナップショットをスキップする場合：

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

ロギングとモニタリング

Performance Insightsは、デフォルトでAuroraライターインスタンスで有効になっています（クラスターのKMSキーで暗号化されています）。また、AuroraエンジンログをCloudWatch Logsにエクスポートすることもできます（Aurora PostgreSQLの場合はpostgresql、Aurora MySQLの場合はaudit、error、general、slowquery）。データベースごとにログエクスポートを有効にします：

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
}

暗号化キーのローテーション

Auroraクラスターとその認証情報シークレットの暗号化に使用されるKMSキーは、デフォルトで自動キーローテーションが有効になっています。セキュリティポリシーで外部的にローテーションを管理している場合は、これを無効にしてください。

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
}

接続

connection ジェネレーターを使用して、このプロジェクトをワークスペース内の他のプロジェクトと統合します。このプロジェクトに関連する接続は以下の通りです：

Python Agent to Relational DatabasePython Agent を Aurora リレーショナルデータベースに接続する

FastAPI to Relational DatabaseFastAPI を Aurora リレーショナルデータベースに接続する

Python MCP Server to Relational DatabasePython MCP Server を Aurora リレーショナルデータベースに接続する