FastAPI to Relational Database

The connection generator wires a FastAPI to a Python Relational Database project, injecting a typed SQLModel session into your route handlers via a FastAPI dependency.

Prerequisites

Before using this generator, ensure you have:

1. A FastAPI project (generated with py#api --framework=fastapi), see the py#api guide
2. A py#rdb project

Usage

Run the Generator

Run this generator@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. Install the Nx Console VSCode Plugin if you haven't already
2. Open the Nx Console in VSCode
3. Click Generate (UI) in the "Common Nx Commands" section
4. Search for @aws/nx-plugin - connection
5. Fill in the required parameters
6. Click Generate

Build your command5

sourceProjectRequired

targetProjectRequired

sourceComponent

targetComponent

preferInstallDependencies

true

--dry-runYou can also perform a dry-run to see what files would be changed

Select your FastAPI project as the source and your relational database project as the target.

Options

Generator Options5 options

sourceProjectRequiredstring

The source project

targetProjectRequiredstring

The target project to connect to

sourceComponentstring

The source component to connect from (component name, path relative to source project root, or generator id). Use '.' to explicitly select the project as the source.

targetComponentstring

The target component to connect to (component name, path relative to target project root, or generator id). Use '.' to explicitly select the project as the target.

preferInstallDependenciesbooleanDefault: true

Whether to prefer installing dependencies after the generator runs. Set to false to defer installing when batching multiple generators (an install still runs if needed so subsequent generators can compute the Nx project graph); install once at the end.

Generator Output

The generator modifies your FastAPI project:

• Directorypackages/my_api

  • project.json Adds a dependency from dev on the database’s dev target
  • pyproject.toml Adds the database package as a workspace dependency
  • Directorymy_api

    • Directorydependencies

      • my_db.py FastAPI MyDbSession dependency for the database session

Using the Database in Route Handlers

This generator configures an injectable FastAPI Dependency which you can use in your route handlers:

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 automatically opens a new session per request and closes it when the handler returns.

Infrastructure

To allow the FastAPI Lambda function to connect to the database at runtime, it must be deployed into the same VPC as the database and granted network and IAM access.

CDK

In your application stack, deploy the API into the same VPC as the database, then call allowDefaultPortFrom and grantConnect to open the network path and grant IAM rds-db:connect permission to the Lambda handler:

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

Deploy the API Lambda functions into a private subnet with egress, not a private isolated subnet. At runtime, session_context() retrieves database configuration from AWS AppConfig, which is a public AWS service endpoint that requires outbound internet access.

Note

This example grants every handler in your API access, but if only some handlers need access it’s better to configure individually.

Terraform

Deploy the API into the same VPC as the database, grant it rds-db:connect via additional_iam_policy_statements, and open the network path with a pair of security group rules:

The example below references the VPC resources from the Python Relational Database deployment guide: aws_subnet.database subnets have no internet route, while aws_subnet.private subnets have NAT egress.

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

Deploy the API Lambda functions into private subnets with egress, not private isolated subnets. appconfig_application_id/appconfig_application_arn come from the shared runtime configuration AppConfig application declared once in your root module, not from the database module — passing them sets RUNTIME_CONFIG_APP_ID on the Lambda functions and grants them read access to the application.

The AppConfig application exposes the database namespace by default, so the database module’s runtime configuration entry is deployed without further configuration.

SSL Requirements When Connecting Without RDS Proxy

The Amazon Linux 2023 Lambda execution environment’s built-in CA trust store includes the Amazon Root CAs used by RDS, so no additional configuration is needed.

When using RDS Proxy, you do not need to configure the RDS CA bundle in your Lambda function.

Local Development

pnpm

pnpm nx dev <project-name>

yarn

yarn nx dev <project-name>

npm

npx nx dev <project-name>

bun

bunx nx dev <project-name>

This starts the FastAPI and all connected databases. The LOCAL_DEV=true environment variable causes the database client to connect to its local Docker database instead of Aurora.