FastAPI para Banco de Dados Relacional

O gerador connection conecta um FastAPI a um projeto de Banco de Dados Relacional Python, injetando uma sessão SQLModel tipada em seus manipuladores de rota via uma dependência FastAPI.

Pré-requisitos

Antes de usar este gerador, certifique-se de ter:

1. Um projeto py#fast-api
2. Um projeto py#rdb

Uso

Executar o Gerador

VSCode

1. Instale o Nx Console VSCode Plugin se ainda não o fez
2. Abra o console Nx no VSCode
3. Clique em Generate (UI) na seção "Common Nx Commands"
4. Procure por @aws/nx-plugin - connection
5. Preencha os parâmetros obrigatórios
6. Clique em Generate

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

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

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

Selecione seu projeto FastAPI como origem e seu projeto de banco de dados relacional como destino.

Opções

Parâmetro	Tipo	Padrão	Descrição
sourceProject Obrigatório	string	-	O projeto de origem
targetProject Obrigatório	string	-	O projeto de destino para conectar
sourceComponent	string	-	O componente de origem para conectar (nome do componente, caminho relativo à raiz do projeto de origem, ou id do gerador). Use '.' para selecionar explicitamente o projeto como origem.
targetComponent	string	-	O componente de destino para conectar (nome do componente, caminho relativo à raiz do projeto de destino, ou id do gerador). Use '.' para selecionar explicitamente o projeto como destino.
preferInstallDependencies	boolean	true	Se deve preferir instalar dependências após a execução do gerador. Defina como false para adiar a instalação ao executar múltiplos geradores em lote (uma instalação ainda é executada se necessário para que os geradores subsequentes possam calcular o grafo de projetos Nx); instale uma vez no final.

Saída do Gerador

O gerador modifica seu projeto FastAPI:

• Directorypackages/my_api

  • project.json Adiciona uma dependência de dev no target dev do banco de dados
  • pyproject.toml Adiciona o pacote do banco de dados como uma dependência do workspace
  • Directorymy_api

    • Directorydependencies

      • my_db.py Dependência FastAPI MyDbSession para a sessão do banco de dados

Usando o Banco de Dados em Manipuladores de Rota

Este gerador configura uma Dependência FastAPI injetável que você pode usar em seus manipuladores de rota:

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

O FastAPI abre automaticamente uma nova sessão por requisição e a fecha quando o manipulador retorna.

Infraestrutura

Para permitir que a função Lambda FastAPI se conecte ao banco de dados em tempo de execução, ela deve ser implantada na mesma VPC que o banco de dados e receber acesso de rede e IAM.

CDK

Em sua pilha de aplicação, implante a API na mesma VPC que o banco de dados, depois chame allowDefaultPortFrom e grantConnect para abrir o caminho de rede e conceder permissão IAM rds-db:connect ao manipulador 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);
});

Implante as funções Lambda da API em uma sub-rede privada com saída, não em uma sub-rede isolada privada. Em tempo de execução, session_context() recupera a configuração do banco de dados do AWS AppConfig, que é um endpoint de serviço AWS público que requer acesso à internet de saída.

Nota

Este exemplo concede acesso a todos os manipuladores em sua API, mas se apenas alguns manipuladores precisarem de acesso, é melhor configurar individualmente.

Terraform

Implante a API na mesma VPC que o banco de dados, conceda rds-db:connect via additional_iam_policy_statements, e abra o caminho de rede com um par de regras de grupo de segurança:

packages/infra/src/main.tf

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
}

module "api" {
  source     = "..."
  enable_vpc = true
  vpc_id     = module.vpc.vpc_id
  subnet_ids = module.vpc.private_subnet_ids

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

  env = {
    RUNTIME_CONFIG_APP_ID = module.runtime_config_appconfig.application_id
  }
}

resource "aws_vpc_security_group_ingress_rule" "api_to_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" {
  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"
}

Implante as funções Lambda da API em sub-redes privadas com saída, não em sub-redes isoladas privadas. RUNTIME_CONFIG_APP_ID deve apontar para a aplicação AppConfig de configuração de tempo de execução compartilhada, não para uma saída do módulo do banco de dados.

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

Isso inicia o FastAPI e todos os bancos de dados conectados. A variável de ambiente LOCAL_DEV=true faz com que o cliente do banco de dados se conecte ao seu banco de dados Docker local em vez do Aurora.