Minimal FastAPI PostgreSQL Template for Rapid Development

If you're a developer looking for a solid foundation to build your web applications, the Minimal FastAPI PostgreSQL Template is a great choice. It combines the power of FastAPI and PostgreSQL in a minimalist, easy-to-understand setup, making it ideal for both newcomers and seasoned developers seeking to expedite their project development.

What Is Minimal FastAPI PostgreSQL Template?

The Minimal FastAPI PostgreSQL Template is an open-source boilerplate that provides a straightforward starting point for building web applications using FastAPI and PostgreSQL. By offering a clean and concise structure, it allows developers to focus on writing business logic rather than boilerplate code. This template is based on the official FastAPI template but has been rewritten to enhance usability and streamline the overall experience.

Key Features

• FastAPI Integration: Leverage the high performance of FastAPI for building APIs with automatic generation of interactive documentation.
• PostgreSQL Support: Built-in support for PostgreSQL, a powerful relational database, ensuring data integrity and scalability.
• Async Capabilities: Utilizes Python's asyncio features for non-blocking I/O operations, improving performance for concurrent requests.
• Docker Compatibility: Easily deploy your application using Docker, simplifying the setup process across different environments.
• Pre-configured Testing: Includes a testing setup with pytest, allowing you to write and run tests effortlessly.
• Pre-commit Hooks: Automatically apply code quality checks before committing your code, keeping your repository clean and maintainable.
• Detailed Documentation: Comprehensive documentation and examples, making it easy to get started and customize to your needs.

Installation & Setup

To get started with the Minimal FastAPI PostgreSQL Template, follow these steps:

# Clone the repository
git clone https://github.com/rafsaf/minimal-fastapi-postgres-template.git

# Navigate into the project directory
cd minimal-fastapi-postgres-template

# Install dependencies using uv
uv install

# Start the application
uv run app/main.py

Before running the application, make sure you have Python 3.14 and PostgreSQL installed on your machine.

How to Use It

Let’s create a simple application that includes a POST endpoint for adding a new pet and a GET endpoint for retrieving all pets.

Step 1: Create New App

Start by creating a new FastAPI application within the existing structure.

# Create a new file: app/pets.py

Step 2: Create SQLAlchemy Model

Define a SQLAlchemy model for your pet.

from sqlalchemy import Column, Integer, String
from database import Base

class Pet(Base):
    __tablename__ = 'pets'
    id = Column(Integer, primary_key=True, index=True)
    name = Column(String, index=True)
    species = Column(String)

Step 3: Import New Models

Update your Alembic configuration to include the new model.

# In app/alembic/env.py
from app.pets import Pet

Step 4: Create and Apply Alembic Migration

Run the following commands to create and apply the migration:

# Create migration
alembic revision --autogenerate -m "create pets table"

# Apply migration
alembic upgrade head

Step 5: Create Schemas

Define request and response schemas for your endpoints.

from pydantic import BaseModel

class PetCreate(BaseModel):
    name: str
    species: str

class PetResponse(PetCreate):
    id: int

Step 6: Create Endpoints

Implement the POST and GET endpoints in your FastAPI app.

from fastapi import FastAPI, HTTPException
from sqlalchemy.orm import Session
from models import Pet
from schemas import PetCreate, PetResponse

app = FastAPI()

@app.post("/pets/", response_model=PetResponse)
def create_pet(pet: PetCreate, db: Session):
    # Add logic to create pet
    pass

@app.get("/pets/", response_model=List[PetResponse])
def read_pets(db: Session):
    # Add logic to retrieve pets
    pass

Step 7: Testing

Finally, write tests to ensure your endpoints behave as expected.

# In tests/test_pets.py

Who Should Use Minimal FastAPI PostgreSQL Template?

This template is perfect for developers who want to build APIs quickly and efficiently. Whether you're a beginner learning FastAPI or an experienced developer needing a solid foundation for your next project, this template provides all the essential components to get you started.

Final Thoughts

The Minimal FastAPI PostgreSQL Template is a well-crafted solution for anyone looking to leverage the capabilities of FastAPI and PostgreSQL. Its simplicity and clear structure make it an excellent choice for rapid application development. If you value clean code and efficient workflows, this template is worth checking out.