FastAPI a Base de Datos Relacional

El generador connection conecta una FastAPI a un proyecto de Base de Datos Relacional de Python, inyectando una sesión SQLModel tipada en tus manejadores de rutas a través de una dependencia de FastAPI.

Requisitos Previos

Antes de usar este generador, asegúrate de tener:

1. Un proyecto FastAPI (generado con py#api --framework=fastapi), consulta la guía de py#api
2. Un proyecto py#rdb

Uso

Ejecutar el Generador

Ejecute este generador@aws/nx-plugin:connection

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

VSCode

1. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque @aws/nx-plugin - connection
5. Complete los parámetros requeridos
6. Haga clic en Generate

Construya su comando5

sourceProjectRequerido

targetProjectRequerido

sourceComponent

targetComponent

preferInstallDependencies

true

--dry-runTambién puede realizar una ejecución en seco para ver qué archivos se cambiarían

Selecciona tu proyecto FastAPI como origen y tu proyecto de base de datos relacional como destino.

Opciones

Opciones del generador5 opciones

sourceProjectRequeridostring

El proyecto de origen

targetProjectRequeridostring

El proyecto de destino al que conectar

sourceComponentstring

El componente de origen desde el cual conectar (nombre del componente, ruta relativa a la raíz del proyecto de origen, o id del generador). Usa '.' para seleccionar explícitamente el proyecto como origen.

targetComponentstring

El componente de destino al cual conectar (nombre del componente, ruta relativa a la raíz del proyecto de destino, o id del generador). Usa '.' para seleccionar explícitamente el proyecto como destino.

preferInstallDependenciesbooleanPredeterminado: true

Si se prefiere instalar las dependencias después de que se ejecute el generador. Establecer en false para diferir la instalación al ejecutar múltiples generadores en lote (la instalación aún se ejecuta si es necesario para que los generadores subsiguientes puedan calcular el grafo de proyectos de Nx); instalar una vez al final.

Salida del Generador

El generador modifica tu proyecto FastAPI:

• Directoriopackages/my_api

  • project.json Agrega una dependencia desde dev al objetivo dev de la base de datos
  • pyproject.toml Agrega el paquete de la base de datos como una dependencia del workspace
  • Directoriomy_api

    • Directoriodependencies

      • my_db.py Dependencia MyDbSession de FastAPI para la sesión de base de datos

Usar la Base de Datos en Manejadores de Rutas

Este generador configura una Dependencia de FastAPI inyectable que puedes usar en tus manejadores de rutas:

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))).scalars().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 abre automáticamente una nueva sesión por solicitud y la cierra cuando el manejador retorna.

Infraestructura

Para permitir que la función Lambda de FastAPI se conecte a la base de datos en tiempo de ejecución, debe desplegarse en la misma VPC que la base de datos y se le debe otorgar acceso de red e IAM.

CDK

En tu stack de aplicación, despliega la API en la misma VPC que la base de datos, luego llama a allowDefaultPortFrom y grantConnect para abrir la ruta de red y otorgar el permiso IAM rds-db:connect al manejador Lambda:

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

Despliega las funciones Lambda de la API en una subred privada con salida, no en una subred privada aislada. En tiempo de ejecución, session_context() recupera la configuración de la base de datos desde AWS AppConfig, que es un endpoint de servicio público de AWS que requiere acceso a internet saliente.

Nota

Este ejemplo otorga acceso a todos los manejadores de tu API, pero si solo algunos manejadores necesitan acceso es mejor configurarlos individualmente.

Terraform

Despliega la API en la misma VPC que la base de datos, otórgale rds-db:connect a través de additional_iam_policy_statements, y abre la ruta de red con un par de reglas de grupo de seguridad:

El ejemplo a continuación hace referencia a los recursos de VPC de la guía de despliegue de Base de Datos Relacional de Python: las subredes aws_subnet.database no tienen ruta de internet, mientras que las subredes aws_subnet.private tienen salida 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"
}

Despliega las funciones Lambda de la API en subredes privadas con salida, no en subredes privadas aisladas. appconfig_application_id/appconfig_application_arn provienen de la aplicación AppConfig de configuración en tiempo de ejecución compartida declarada una vez en tu módulo raíz, no del módulo de base de datos — pasarlos establece RUNTIME_CONFIG_APP_ID en las funciones Lambda y les otorga acceso de lectura a la aplicación.

La aplicación AppConfig expone el namespace database por defecto, por lo que la entrada de configuración en tiempo de ejecución del módulo de base de datos se despliega sin configuración adicional.

Requisitos de SSL al Conectarse sin RDS Proxy

El almacén de confianza de CA integrado del entorno de ejecución Lambda de Amazon Linux 2023 incluye las CA raíz de Amazon utilizadas por RDS, por lo que no se necesita configuración adicional.

Cuando se utiliza RDS Proxy, no es necesario configurar el paquete de CA de RDS en su función Lambda.

Desarrollo Local

pnpm

pnpm nx dev <project-name>

yarn

yarn nx dev <project-name>

npm

npx nx dev <project-name>

bun

bunx nx dev <project-name>

Esto inicia la FastAPI y todas las bases de datos conectadas. La variable de entorno LOCAL_DEV=true hace que el cliente de base de datos se conecte a su base de datos Docker local en lugar de Aurora.