FastAPI + PostgreSQL Backend Template

A production-ready FastAPI backend template with PostgreSQL, JWT authentication, Alembic migrations, SQLModel ORM, Docker support, and Railway deployment configuration.

Built for scalable API development with clean architecture and modern Python tooling.

---

🚀 Quick Start

Prerequisites

• Python 3.12+
• PostgreSQL 14+
• Docker & Docker Compose (optional)

---

⚡ Local Development (2 minutes)

# 1. Clone repository
git clone <repo-url>
cd fastapi-postgres-template

# 2. Install dependencies
uv sync

# 3. Configure environment variables
cp .env.example .env

# Edit .env with your PostgreSQL credentials

# 4. Run database migrations
uv run alembic upgrade head

# 5. Start development server
uv run uvicorn app.main:app --reload

Visit:

• API: http://localhost:8000
• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

---

🐳 Using Docker

cp .env.example .env
docker-compose up --build

---

📚 Documentation

• SETUP.md — Local development setup
• ARCHITECTURE.md — Project structure and design patterns
• DATABASE.md — Database models and migrations
• DEPLOYMENT.md — Railway deployment guide
• API.md — API documentation

---

🏗️ Project Structure

fastapi-postgres-template/
├── app/
│   ├── api/                 # API routes & dependencies
│   ├── core/                # Settings, security, db config
│   ├── models.py            # SQLModel ORM models
│   ├── crud.py              # Database operations
│   ├── schemas.py           # Pydantic schemas
│   ├── deps.py              # Shared dependencies
│   └── main.py              # FastAPI app
│
├── alembic/                 # Database migrations
│
├── scripts/
│   ├── setup-dev.sh
│   ├── run-local.sh
│   └── db-reset.sh
│
├── tests/                   # Pytest test suite
│
├── Dockerfile
├── docker-compose.yml
├── railway.json
├── pyproject.toml
├── .env.example
└── README.md

---

🔐 Authentication

This template uses JWT-based stateless authentication.

Flow:

1. User logs in with email/password
2. Backend validates credentials
3. JWT access token is generated
4. Frontend/client includes token in Authorization header
5. Protected endpoints validate token automatically

Example header:

Authorization: Bearer <token>

---

🗄️ Database

• PostgreSQL
• SQLModel
• Alembic

Included models:

• User
• Item

Supports:

• migrations
• relationships
• typed schemas
• async-ready architecture

---

📡 API Endpoints

Interactive docs available at:

• Swagger UI → /docs
• ReDoc → /redoc

Core endpoints:

POST /login/access-token
POST /users/
GET  /users/
GET  /items/
POST /items/
GET  /health

---

❤️ Health Check

Railway-ready health endpoint included:

GET /health

Returns:

{
  "status": "ok"
}

---

🚢 Railway Deployment

One-Click Deploy

---

Manual Railway Setup

1. Connect GitHub repository
2. Add PostgreSQL service
3. Configure environment variables
4. Deploy

---

⚙️ Example railway.json

{
  "$schema": "https://railway.app/railway.schema.json",
  "build": {
    "builder": "NIXPACKS"
  },
  "deploy": {
    "startCommand": "uvicorn app.main:app --host 0.0.0.0 --port $PORT",
    "healthcheckPath": "/health",
    "healthcheckTimeout": 100,
    "restartPolicyType": "ON_FAILURE"
  }
}

---

🔑 Environment Variables

Example:

SECRET_KEY=your-secret-key
POSTGRES_SERVER=localhost
POSTGRES_PORT=5432
POSTGRES_DB=app
POSTGRES_USER=postgres
POSTGRES_PASSWORD=password

Railway users can use:

DATABASE_URL=${{Postgres.DATABASE_URL}}

---

🛠️ Development

Create Migration

alembic revision --autogenerate -m "description"

Apply Migration

alembic upgrade head

Rollback Migration

alembic downgrade -1

---

🧪 Testing

pytest

---

📦 Key Dependencies

• FastAPI
• SQLModel
• Pydantic v2
• Alembic
• Psycopg
• PyJWT
• Passlib
• Ruff
• Uvicorn

---

✨ Features

✅ JWT Authentication ✅ PostgreSQL Integration ✅ Alembic Migrations ✅ SQLModel ORM ✅ Docker Support ✅ Railway Ready ✅ Health Checks ✅ OpenAPI Docs ✅ Clean Project Structure ✅ Production Deployment Ready

---

🤝 Contributing

git checkout -b feature/my-feature
git commit -m "Add feature"
git push origin feature/my-feature

Open a Pull Request.

---

📝 License

MIT License

---

🆘 Troubleshooting

Database Connection Errors

• Verify PostgreSQL is running
• Check .env credentials
• Confirm migrations ran successfully

Railway Deployment Issues

• Ensure app listens on:

  0.0.0.0:$PORT

• Verify healthcheck path:

  /health

• Confirm environment variables are set

---

📧 Support

1. Review documentation
2. Check existing issues
3. Open a new issue with logs/details

---

Happy building 🚀