FastAPI에서 관계형 데이터베이스로

connection 생성기는 FastAPI를 Python 관계형 데이터베이스 프로젝트에 연결하여, FastAPI 의존성을 통해 타입이 지정된 SQLModel 세션을 라우트 핸들러에 주입합니다.

사전 요구 사항

이 생성기를 사용하기 전에 다음이 필요합니다:

1. FastAPI 프로젝트 (py#api --framework=fastapi로 생성), py#api 가이드 참조
2. py#rdb 프로젝트

사용법

생성기 실행

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection

yarn

yarn nx g @aws/nx-plugin:connection

npm

npx nx g @aws/nx-plugin:connection

bun

bunx nx g @aws/nx-plugin:connection

어떤 파일이 변경될지 확인하기 위해 드라이 런을 수행할 수도 있습니다

pnpm

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn

yarn nx g @aws/nx-plugin:connection --dry-run

npm

npx nx g @aws/nx-plugin:connection --dry-run

bun

bunx nx g @aws/nx-plugin:connection --dry-run

VSCode

1. 설치 Nx Console VSCode Plugin 아직 설치하지 않았다면
2. VSCode에서 Nx 콘솔 열기
3. 클릭 Generate (UI) "Common Nx Commands" 섹션에서
4. 검색 @aws/nx-plugin - connection
5. 필수 매개변수 입력
6. 클릭 Generate

FastAPI 프로젝트를 소스로, 관계형 데이터베이스 프로젝트를 타겟으로 선택하세요.

옵션

매개변수	타입	기본값	설명
sourceProject 필수	string	-	소스 프로젝트
targetProject 필수	string	-	연결할 대상 프로젝트
sourceComponent	string	-	연결을 시작할 소스 컴포넌트 (컴포넌트 이름, 소스 프로젝트 루트 기준 상대 경로, 또는 generator id). 프로젝트를 소스로 명시적으로 선택하려면 '.'을 사용하세요.
targetComponent	string	-	연결할 대상 컴포넌트 (컴포넌트 이름, 대상 프로젝트 루트 기준 상대 경로, 또는 generator id). 프로젝트를 대상으로 명시적으로 선택하려면 '.'을 사용하세요.
preferInstallDependencies	boolean	true	생성기 실행 후 의존성 설치를 선호할지 여부입니다. 여러 생성기를 일괄 처리할 때 설치를 연기하려면 false로 설정하세요 (후속 생성기가 Nx 프로젝트 그래프를 계산할 수 있도록 필요한 경우 설치는 여전히 실행됩니다); 마지막에 한 번만 설치합니다.

생성기 출력

생성기는 FastAPI 프로젝트를 수정합니다:

• 디렉터리packages/my_api

  • project.json 데이터베이스의 dev 타겟에 대한 dev 의존성 추가
  • pyproject.toml 워크스페이스 의존성으로 데이터베이스 패키지 추가
  • 디렉터리my_api

    • 디렉터리dependencies

      • my_db.py 데이터베이스 세션을 위한 FastAPI MyDbSession 의존성

라우트 핸들러에서 데이터베이스 사용

이 생성기는 라우트 핸들러에서 사용할 수 있는 주입 가능한 FastAPI Dependency를 구성합니다:

packages/my_api/my_api/api.py

from sqlmodel import select
from my_api.dependencies.my_db import MyDbSession
from my_scope.my_db.models.example import ExampleModel

@app.get("/examples")
async def list_examples(my_db: MyDbSession):
    return (await my_db.execute(select(ExampleModel))).all()

@app.post("/examples")
async def create_example(name: str, my_db: MyDbSession):
    item = ExampleModel(name=name)
    my_db.add(item)
    await my_db.commit()
    await my_db.refresh(item)
    return item

FastAPI는 요청당 자동으로 새 세션을 열고 핸들러가 반환될 때 닫습니다.

인프라

런타임에 FastAPI Lambda 함수가 데이터베이스에 연결할 수 있도록 하려면, 데이터베이스와 동일한 VPC에 배포되어야 하며 네트워크 및 IAM 액세스 권한이 부여되어야 합니다.

CDK

애플리케이션 스택에서 API를 데이터베이스와 동일한 VPC에 배포한 다음, allowDefaultPortFrom 및 grantConnect를 호출하여 네트워크 경로를 열고 Lambda 핸들러에 IAM rds-db:connect 권한을 부여합니다:

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

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

const db = new MyDatabase(this, 'Db', { vpc, ... });

const api = new MyApi(this, 'Api', {
  integrations: MyApi.defaultIntegrations(this)
    .withDefaultOptions({
      vpc,
      vpcSubnets: { subnetType: SubnetType.PRIVATE_WITH_EGRESS },
    })
    .build(),
});

Object.entries(api.integrations).forEach(([operation, integration]) => {
  db.allowDefaultPortFrom(integration.handler, `Allow ${operation} to connect to the database`);
  db.grantConnect(integration.handler);
});

API Lambda 함수를 프라이빗 격리 서브넷이 아닌 이그레스가 있는 프라이빗 서브넷에 배포하세요. 런타임에 session_context()는 AWS AppConfig에서 데이터베이스 구성을 검색하는데, 이는 아웃바운드 인터넷 액세스가 필요한 퍼블릭 AWS 서비스 엔드포인트입니다.

참고

이 예제는 API의 모든 핸들러에 액세스 권한을 부여하지만, 일부 핸들러만 액세스가 필요한 경우 개별적으로 구성하는 것이 좋습니다.

Terraform

API를 데이터베이스와 동일한 VPC에 배포하고, additional_iam_policy_statements를 통해 rds-db:connect를 부여하며, 보안 그룹 규칙 쌍으로 네트워크 경로를 엽니다:

아래 예제는 Python 관계형 데이터베이스 배포 가이드의 VPC 리소스를 참조합니다: aws_subnet.database 서브넷은 인터넷 라우트가 없고, aws_subnet.private 서브넷은 NAT 이그레스가 있습니다.

packages/infra/src/main.tf

module "my_database" {
  source              = "../../common/terraform/src/app/dbs/my-database"
  vpc_id              = aws_vpc.main.id
  database_subnet_ids = aws_subnet.database[*].id
  lambda_subnet_ids   = aws_subnet.private[*].id
}

module "api" {
  source     = "../../common/terraform/src/app/apis/my-api"
  enable_vpc = true
  vpc_id     = aws_vpc.main.id
  subnet_ids = aws_subnet.private[*].id

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn

  additional_iam_policy_statements = [
    {
      Effect = "Allow"
      Action = ["rds-db:connect"]
      Resource = [
        "arn:aws:rds-db:${data.aws_region.current.region}:${data.aws_caller_identity.current.account_id}:dbuser:${module.my_database.connect_resource_id}/${module.my_database.database_runtime_user}"
      ]
    }
  ]
}

resource "aws_vpc_security_group_ingress_rule" "api_to_database" {
  description                  = "Allow the API Lambda functions to connect to the database"
  security_group_id            = module.my_database.security_group_id
  referenced_security_group_id = module.api.security_group_id
  from_port                    = module.my_database.cluster_port
  to_port                      = module.my_database.cluster_port
  ip_protocol                  = "tcp"
}

resource "aws_vpc_security_group_egress_rule" "api_to_database" {
  description                  = "Allow outbound traffic from the API Lambda functions to the database"
  security_group_id            = module.api.security_group_id
  referenced_security_group_id = module.my_database.security_group_id
  from_port                    = module.my_database.cluster_port
  to_port                      = module.my_database.cluster_port
  ip_protocol                  = "tcp"
}

API Lambda 함수를 프라이빗 격리 서브넷이 아닌 이그레스가 있는 프라이빗 서브넷에 배포하세요. appconfig_application_id/appconfig_application_arn은 데이터베이스 모듈이 아닌 루트 모듈에서 한 번 선언된 공유 런타임 구성 AppConfig 애플리케이션에서 가져옵니다. 이를 전달하면 Lambda 함수에 RUNTIME_CONFIG_APP_ID가 설정되고 애플리케이션에 대한 읽기 액세스 권한이 부여됩니다.

AppConfig 애플리케이션은 데이터베이스 모듈의 런타임 구성 항목이 배포되도록 database 네임스페이스를 노출해야 합니다. runtime-config/appconfig 모듈을 인스턴스화할 때 namespaces에 포함하세요:

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

로컬 개발

pnpm

pnpm nx dev <project-name>

yarn

yarn nx dev <project-name>

npm

npx nx dev <project-name>

bun

bunx nx dev <project-name>

이는 FastAPI와 연결된 모든 데이터베이스를 시작합니다. LOCAL_DEV=true 환경 변수는 데이터베이스 클라이언트가 Aurora 대신 로컬 Docker 데이터베이스에 연결하도록 합니다.