FastAPI + PostgreSQL

intermediate

Modern Python FastAPI with PostgreSQL and async support.

[i]Overview

FastAPI is a modern, high-performance web framework for building APIs with Python 3.7+ based on standard Python type hints. Created by Sebastián Ramirez in 2018, FastAPI has rapidly gained adoption for its automatic API documentation generation, native async/await support, and exceptional performance that rivals Node.js and Go frameworks. It leverages Pydantic for data validation and Starlette for the web components, creating a developer-friendly framework that generates OpenAPI schemas automatically. This FastAPI and PostgreSQL combination creates a powerful foundation for data-driven web applications and APIs. PostgreSQL's advanced features like JSONB support, full-text search, and ACID compliance complement FastAPI's automatic validation and serialization capabilities. The asyncpg driver enables true asynchronous database operations, allowing the application to handle thousands of concurrent connections efficiently while PostgreSQL manages complex queries and maintains data integrity. This stack is ideal for startups building scalable APIs, enterprises migrating from Django REST or Flask applications, and developers creating modern web applications that require both high performance and robust data management. The automatic API documentation generation makes it particularly valuable for teams building microservices or public APIs, while PostgreSQL's reliability ensures production-grade data handling.

[*]Key Features

[+]Automatic OpenAPI/Swagger documentation generation with interactive API testing interface
[+]Native async/await support with asyncpg for non-blocking PostgreSQL operations
[+]Pydantic model integration for automatic request/response validation and serialization
[+]FastAPI's dependency injection system for clean database session management
[+]PostgreSQL JSONB support for hybrid relational-document data models
[+]SQLModel compatibility for type-safe database operations with FastAPI
[+]Hot reloading in development mode for rapid API iteration
[+]PostgreSQL's advanced indexing and query optimization for high-performance data access

[#]Common Use Cases

[1]REST API backends for React, Vue, or Angular single-page applications
[2]Microservices architectures requiring high-performance async communication
[3]Data analytics platforms with complex PostgreSQL queries and JSON data processing
[4]E-commerce platforms requiring ACID transactions and inventory management
[5]IoT data collection systems handling high-frequency sensor data ingestion
[6]Content management systems leveraging PostgreSQL's full-text search capabilities
[7]Financial applications requiring PostgreSQL's transaction integrity and decimal precision

[!]Prerequisites

[!]Docker and Docker Compose installed with at least 4GB available memory
[!]Python 3.7+ knowledge and familiarity with async/await programming concepts
[!]Basic understanding of PostgreSQL and SQL query fundamentals
[!]Port 8000 available for FastAPI application access
[!]Knowledge of environment variable configuration and .env file management
[!]Understanding of database migration concepts for Alembic usage

[!]

WARNING: For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

[$]docker-compose.yml

[docker-compose.yml]

1services: 
2  app: 
3    build: .
4    container_name: fastapi
5    environment: 
6      DATABASE_URL: postgresql+asyncpg://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
7    ports: 
8      - "8000:8000"
9    depends_on: 
10      - postgres
11    networks: 
12      - fastapi
13
14  postgres: 
15    image: postgres:16-alpine
16    container_name: postgres
17    environment: 
18      POSTGRES_DB: ${DB_NAME}
19      POSTGRES_USER: ${DB_USER}
20      POSTGRES_PASSWORD: ${DB_PASSWORD}
21    volumes: 
22      - postgres_data:/var/lib/postgresql/data
23    networks: 
24      - fastapi
25
26volumes: 
27  postgres_data: 
28
29networks: 
30  fastapi: 
31    driver: bridge

[$].env Template

[.env]

1DB_NAME=fastapi
2DB_USER=fastapi
3DB_PASSWORD=changeme

[i]Usage Notes

[1]Docs: https://fastapi.tiangolo.com/
[2]Create Dockerfile with Python + uvicorn
[3]Interactive API docs at http://localhost:8000/docs (Swagger)
[4]ReDoc at http://localhost:8000/redoc
[5]Async support with asyncpg, use SQLModel or SQLAlchemy 2.0
[6]Alembic for database migrations

Individual Services(2 services)

Copy individual services to mix and match with your existing compose files.

app

app:
  build: .
  container_name: fastapi
  environment:
    DATABASE_URL: postgresql+asyncpg://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
  ports:
    - "8000:8000"
  depends_on:
    - postgres
  networks:
    - fastapi

postgres

postgres:
  image: postgres:16-alpine
  container_name: postgres
  environment:
    POSTGRES_DB: ${DB_NAME}
    POSTGRES_USER: ${DB_USER}
    POSTGRES_PASSWORD: ${DB_PASSWORD}
  volumes:
    - postgres_data:/var/lib/postgresql/data
  networks:
    - fastapi

[>]Quick Start

[terminal]

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  app:
5    build: .
6    container_name: fastapi
7    environment:
8      DATABASE_URL: postgresql+asyncpg://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
9    ports:
10      - "8000:8000"
11    depends_on:
12      - postgres
13    networks:
14      - fastapi
15
16  postgres:
17    image: postgres:16-alpine
18    container_name: postgres
19    environment:
20      POSTGRES_DB: ${DB_NAME}
21      POSTGRES_USER: ${DB_USER}
22      POSTGRES_PASSWORD: ${DB_PASSWORD}
23    volumes:
24      - postgres_data:/var/lib/postgresql/data
25    networks:
26      - fastapi
27
28volumes:
29  postgres_data:
30
31networks:
32  fastapi:
33    driver: bridge
34EOF
35
36# 2. Create the .env file
37cat > .env << 'EOF'
38DB_NAME=fastapi
39DB_USER=fastapi
40DB_PASSWORD=changeme
41EOF
42
43# 3. Start the services
44docker compose up -d
45
46# 4. View logs
47docker compose logs -f

[>]One-Liner

Run this command to download and set up the recipe in one step:

[terminal]

1curl -fsSL https://docker.recipes/api/recipes/fastapi-postgres/run | bash

[?]Troubleshooting

[!]asyncpg.exceptions.InvalidCatalogNameError: Ensure POSTGRES_DB environment variable matches DATABASE_URL database name and postgres container has fully initialized
[!]FastAPI startup fails with 'database connection refused': Add healthcheck to postgres service or implement retry logic in FastAPI database connection
[!]uvicorn worker timeout errors under load: Increase worker_connections in uvicorn configuration and verify asyncpg connection pooling is properly configured
[!]Pydantic validation errors on database model serialization: Ensure SQLModel or SQLAlchemy models inherit from BaseModel and use proper type annotations
[!]PostgreSQL container fails to start with permission denied: Check that postgres_data volume has correct ownership or remove volume to reinitialize
[!]FastAPI returns 500 errors on database queries: Enable SQLAlchemy echo=True to debug queries and verify async session management in dependency injection

Community Notes

Loading notes...

## Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

## Components

fastapipostgres

## Tags

#fastapi#python#postgres#async

## Category

Full Web Stacks

## Related

Shortcuts: C CopyF FavoriteD Download