Como construir uma API REST com FastAPI e PostgreSQL em 2026: tutorial completo

{
“@context”: “https://schema.org”,
“@type”: “TechArticle”,
“headline”: “Como construir uma API REST com FastAPI e PostgreSQL em 2026: tutorial completo”,
“description”: “Crie uma API REST pronta para produção do zero usando FastAPI, PostgreSQL, SQLAlchemy e Docker. Completo com autenticação, CRUD e implantação.”,
“url”: “https://techpulsesite.com/how-to-build-a-rest-api-with-fastapi-and-pt/”,
“datePublished”: “2026-06-24T10:35:00+00:00”,
“dateModified”: “2026-06-29T04:14:54+00:00”,
“author”: {
“@type”: “Organization”,
“name”: “TechPulse Editorial Team”,
“url”: “https://techpulsesite.com”
},
“publisher”: {
“@type”: “Organization”,
“name”: “TechPulse”,
“url”: “https://techpulsesite.com”
},
“inLanguage”: “pt”
}

{
“@context”: “https://schema.org”,
“@type”: “TechArticle”,
“headline”: “Como construir uma API REST com FastAPI e PostgreSQL em 2026: tutorial completo”,
“description”: “Crie uma API REST pronta para produção do zero usando FastAPI, PostgreSQL, SQLAlchemy e Docker. Completo com autenticação, CRUD e implantação.”,
“url”: “https://techpulsesite.com/how-to-build-a-rest-api-with-fastapi-and-pt/”,
“datePublished”: “2026-06-24T10:35:00+00:00”,
“dateModified”: “2026-06-21T05:55:13+00:00”,
“author”: {
“@type”: “Organization”,
“name”: “TechPulse Editorial Team”,
“url”: “https://techpulsesite.com”
},
“publisher”: {
“@type”: “Organization”,
“name”: “TechPulse”,
“url”: “https://techpulsesite.com”
},
“inLanguage”: “pt”
}

FastAPI tornou-se o padrão ouro para APIs REST Python em 2026 – é mais rápido que Flask, tem validação de dados integrada via Pydantic v2, gera automaticamente documentos OpenAPI e é totalmente assíncrono. Combinado com PostgreSQL e SQLAlchemy, você obtém uma pilha robusta, pronta para produção e com boa escalabilidade.

Este tutorial cria uma API completa de gerenciamento de tarefas, do zero à implantação.

Pré-requisitos

• Python 3.11+ instalado
• PostgreSQL 15+ em execução (ou Docker)
• Compreensão básica dos conceitos REST e Python

Configuração do Projeto

mkdir taskapi && cd taskapi
python -m venv venv && source venv/bin/activate
pip install fastapi uvicorn sqlalchemy psycopg2-binary pydantic python-jose passlib python-dotenv alembic

Crie a estrutura do projeto:

taskapi/
├── app/
│   ├── __init__.py
│   ├── main.py
│   ├── database.py
│   ├── models.py
│   ├── schemas.py
│   ├── crud.py
│   └── routers/
│       ├── tasks.py
│       └── auth.py
├── .env
└── requirements.txt

Configuração do banco de dados

In .env:

DATABASE_URL=postgresql://user:password@localhost:5432/taskdb
SECRET_KEY=your-secret-key-here
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

In app/database.py:

from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker, DeclarativeBase
from dotenv import load_dotenv
import os

load_dotenv()
DATABASE_URL = os.getenv("DATABASE_URL")

engine = create_engine(DATABASE_URL)
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)

class Base(DeclarativeBase):
    pass

def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

Modelos e Esquemas

In app/models.py:

from sqlalchemy import Column, Integer, String, Boolean, DateTime, ForeignKey
from sqlalchemy.sql import func
from .database import Base

class User(Base):
    __tablename__ = "users"
    id         = Column(Integer, primary_key=True, index=True)
    email      = Column(String, unique=True, index=True)
    hashed_password = Column(String)
    is_active  = Column(Boolean, default=True)
    created_at = Column(DateTime(timezone=True), server_default=func.now())

class Task(Base):
    __tablename__ = "tasks"
    id          = Column(Integer, primary_key=True, index=True)
    title       = Column(String, index=True)
    description = Column(String, nullable=True)
    completed   = Column(Boolean, default=False)
    owner_id    = Column(Integer, ForeignKey("users.id"))
    created_at  = Column(DateTime(timezone=True), server_default=func.now())

In app/schemas.py:

from pydantic import BaseModel, EmailStr
from datetime import datetime
from typing import Optional

class TaskCreate(BaseModel):
    title: str
    description: Optional[str] = None

class TaskResponse(TaskCreate):
    id: int
    completed: bool
    owner_id: int
    created_at: datetime
    class Config:
        from_attributes = True

class UserCreate(BaseModel):
    email: EmailStr
    password: str

class Token(BaseModel):
    access_token: str
    token_type: str

Operações CRUD

In app/crud.py:

from sqlalchemy.orm import Session
from . import models, schemas
from passlib.context import CryptContext

pwd_context = CryptContext(schemes=["bcrypt"])

def get_user_by_email(db: Session, email: str):
    return db.query(models.User).filter(models.User.email == email).first()

def create_user(db: Session, user: schemas.UserCreate):
    hashed = pwd_context.hash(user.password)
    db_user = models.User(email=user.email, hashed_password=hashed)
    db.add(db_user); db.commit(); db.refresh(db_user)
    return db_user

def get_tasks(db: Session, owner_id: int, skip=0, limit=100):
    return db.query(models.Task).filter(
        models.Task.owner_id == owner_id).offset(skip).limit(limit).all()

def create_task(db: Session, task: schemas.TaskCreate, owner_id: int):
    db_task = models.Task(**task.model_dump(), owner_id=owner_id)
    db.add(db_task); db.commit(); db.refresh(db_task)
    return db_task

def update_task(db: Session, task_id: int, completed: bool):
    task = db.query(models.Task).filter(models.Task.id == task_id).first()
    if task:
        task.completed = completed; db.commit(); db.refresh(task)
    return task

Principais Aplicações e Rotas

In app/main.py:

from fastapi import FastAPI
from .database import engine
from . import models
from .routers import tasks, auth

models.Base.metadata.create_all(bind=engine)

app = FastAPI(title="Task API", version="1.0.0")
app.include_router(auth.router, prefix="/auth", tags=["auth"])
app.include_router(tasks.router, prefix="/tasks", tags=["tasks"])

@app.get("/health")
def health(): return {"status": "ok"}

Execute com:uvicorn app.main:app --reload

Visitehttp://localhost:8000/docs para UI Swagger gerada automaticamente.

Implantando com Docker

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

Comdocker-compose.yml:

services:
  api:
    build: .
    ports: ["8000:8000"]
    env_file: .env
    depends_on: [db]
  db:
    image: postgres:15
    environment:
      POSTGRES_DB: taskdb
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password

Melhores Práticas para Produção

• UsarAlambique para migrações de banco de dados em vez decreate_all()
• Adicionarlimitação de taxa comslowapi pacote
• UsarSQLAlchemy assíncrono comasyncpg driver para alta simultaneidade
• AdicionarCache Redis para endpoints lidos com frequência
• ConfigurarSentinela para rastreamento de erros na produção
• Nunca exponha erros de banco de dados brutos aos consumidores da API

Perguntas Frequentes

P: FastAPI vs Django REST Framework em 2026?
R: FastAPI é mais rápido, tem melhor suporte assíncrono e requer menos padrões. Django DRF é melhor para painéis de administração complexos, recursos ORM e equipes que já usam Django.

P: Como lidar com migrações de banco de dados?
R: Use Alambique:alembic init alembic, configure o URL do seu banco de dados e, em seguida,alembic revision --autogenerate -m "init" ealembic upgrade head.

P: Como adiciono paginação?
R: Adicioneskip: int = 0, limit: int = 20 parâmetros para seu endpoint e use.offset(skip).limit(limit) na sua consulta.

P: Vale a pena usar o SQLAlchemy 2.0 em 2026?
R: Absolutamente. O estilo 2.0 comselect() declarações são mais limpas, mais rápidas e melhores para uso assíncrono. Todos os novos projetos devem utilizá-lo.

P: Como adiciono tarefas em segundo plano?
R: FastAPI possuiBackgroundTasks para casos simples. Para fluxos de trabalho complexos, use Celery com Redis como corretor.

Conclusão

FastAPI + PostgreSQL + SQLAlchemy é uma das melhores pilhas de back-end Python disponíveis em 2026. Você obtém documentação automática, tratamento de solicitação/resposta com segurança de tipo, desempenho assíncrono rápido e uma camada de banco de dados madura e testada em batalha. O código completo deste tutorial é uma base sólida para qualquer API de produção — adicione middleware de autenticação, limitação de taxa e monitoramento antes de entrar no ar.