fastapi-postgres-boilerplate

Production-ready FastAPI + Postgres starter: JWT auth, async SQLAlchemy, Alembic migrations, Docker, tests, CI.

Features

• FastAPI with automatic OpenAPI docs (/docs)
• JWT authentication — register, login, protected routes
• Async SQLAlchemy 2.0 with asyncpg driver
• Alembic migrations (one command to migrate)
• Pydantic v2 schemas with email validation
• Docker + docker-compose for local development
• pytest suite using SQLite in-memory (no Postgres needed for tests)
• ruff linting + formatting
• GitHub Actions CI: lint → test → docker build

Architecture

┌─────────────────────────────────────────────┐
│                  FastAPI App                │
│                                             │
│  /auth/register  →  bcrypt hash  →  DB      │
│  /auth/token     →  JWT issue              │
│  /users/me       →  JWT verify  →  DB       │
│  /health         →  200 OK                  │
└──────────────────────┬──────────────────────┘
                       │ asyncpg
                       ▼
              ┌─────────────────┐
              │  PostgreSQL 16  │
              │  (users table)  │
              └─────────────────┘

Quick Start

With Docker (recommended)

git clone https://github.com/MU5A/fastapi-postgres-boilerplate
cd fastapi-postgres-boilerplate

# Start Postgres + app
docker-compose up -d

# Run migrations
docker-compose exec app alembic upgrade head

Browse to http://localhost:8000/docs

Local Development

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# Start Postgres (e.g. via docker-compose up -d db)
export DATABASE_URL=postgresql+asyncpg://boilerplate:boilerplate@localhost/boilerplate
export SECRET_KEY=your-secret-key

alembic upgrade head
uvicorn app.main:app --reload

Running Tests

Tests use SQLite in-memory — no Postgres required:

pytest tests/ -v

API Endpoints

Method	Path	Auth	Description
POST	/auth/register	—	Create account
POST	/auth/token	—	Login → JWT
GET	/users/me	Bearer	Current user
GET	/health	—	Liveness probe

Configuration

Env var	Default	Description
DATABASE_URL	sqlite+aiosqlite:///./app.db	SQLAlchemy async URL
SECRET_KEY	dev-secret-key-...	JWT signing key
ALGORITHM	HS256	JWT algorithm
ACCESS_TOKEN_EXPIRE_MINUTES	30	Token TTL

Project Structure

app/
├── core/
│   ├── config.py        # pydantic-settings
│   └── security.py      # bcrypt + JWT helpers
├── db/
│   └── session.py       # async engine + Base
├── models/
│   └── user.py          # SQLAlchemy User model
├── routers/
│   ├── auth.py          # /auth/register, /auth/token
│   └── users.py         # /users/me
├── schemas/
│   └── user.py          # Pydantic I/O schemas
└── main.py              # FastAPI app + lifespan
alembic/
└── versions/
    └── 0001_create_users_table.py
tests/
├── conftest.py          # async client fixture
└── test_auth.py         # 9 tests

Tech Stack

• FastAPI — ASGI web framework
• SQLAlchemy 2 — async ORM
• Alembic — schema migrations
• asyncpg — Postgres async driver
• PyJWT — JWT encoding/decoding
• bcrypt — password hashing
• pydantic-settings — config management
• httpx — async HTTP client for tests

License

MIT