Skip to content

Releases: benavlabs/FastAPI-boilerplate

v0.18.0

24 May 19:49
@igorbenav igorbenav
v0.18.0
c01a17a
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
v0.18.0 Latest
Latest

Release v0.18.0 - The Pluggable Restructure

Release Notes by FastAPI-boilerplate team

This is the release we promised in v0.17.0; the one that tears the layout apart and rebuilds it as a real plugin system. If you've been pinned to v0.17.0 waiting for it, this is your moment.

A heads-up before we go further: the diff is enormous; v0.17.0 → v0.18.0 is not the kind of upgrade you run git pull for. The Python package moved, auth changed completely, workers changed, the admin panel changed, there's a new CLI in a new workspace member. We didn't do this lightly, and the rationale is the rest of this document.

Why this release is so different

We didn't iterate on the v0.17.0 codebase to get here. We rebased the project on the fastroai-template structure.

fastroai-template is the production-tested template we use internally (and sell) for AI SaaS products. It's been running real apps for months and the structural choices (three-layer architecture, vertical-slice modules, server-side sessions, SQLAdmin, Taskiq, swappable infrastructure) have proven themselves under load. Reinventing all of that for FastAPI-boilerplate would have meant another six months of polish; rebasing meant we could ship the good parts on day one.

The trade-off is that fastroai-template carries a lot of stuff this boilerplate's audience doesn't necessarily need: a Stripe integration, subscription/credits/entitlements modeling, AI agent orchestration, usage tracking with cost calculation, OAuth-specific provisioning for SaaS, an Astro frontend. Excellent for an AI SaaS starter, wrong for a general FastAPI boilerplate.

So this release is fastroai-template minus the SaaS/AI parts, plus a plugin system that fastroai-template doesn't have. What's left is the structural skeleton; the parts that any FastAPI app needs and that we've watched hold up in real use:

  • The three-layer split (interfaces/, infrastructure/, modules/)
  • Vertical-slice modules (user/, tier/, api_keys/, rate_limit/)
  • Server-side sessions + CSRF, OAuth (Google wired, GitHub scaffolded)
  • SQLAdmin, Taskiq, swappable cache/session/rate-limit backends
  • The production security validator that refuses to boot with insecure defaults

The new part, the one fastroai-template doesn't have, is bp — a plugin-aware CLI. fastroai-template ships everything in-tree because that's appropriate for an AI SaaS starter. FastAPI-boilerplate's whole pitch is "use what you need, drop what you don't", and that pitch only works if dropping things and adding things are first-class operations. The bp.commands and bp.features entry points are how external Python packages contribute new commands and feature generators without touching the core. Build a Stripe plugin, a Prometheus plugin, a CRUD-generator plugin, they all ship as separate packages.

If you can stay on v0.17.0, consider it

For brand-new projects, v0.18.0 is the better starting point. For existing apps with significant custom code on v0.17.0, the honest answer is: the migration path is "copy your business logic into the new structure", not a sed-style find-and-replace. If your fork has diverged from v0.17.0 in non-trivial ways, pinning to v0.17.0 may be the right call.

We'll keep v0.17.0 around as a tag forever. You can hold there as long as you need.

New co-maintainers

Two contributors are now officially helping us maintain and improve the boilerplate going forward: @carlosplanchon and @emiliano-gandini-outeda. Both have been contributing for months — this release is the right moment to make it official.

@carlosplanchon drove a lot of the polish that made this restructure possible. Six merged PRs and four issues that shaped direction:

  • #247 — Python 3.14 dependency compatibility pass
  • #218 — README cleanup; installation scripts moved out of Gists into the repo
  • #215 — FastCRUD 0.19.0 pagination structure adoption
  • #214 — Docs note on falsy values from FastCRUD
  • #205 — SQLAlchemy 2.0 syntax in docs/user-guide/development.md
  • #192 — DeepWiki link in the README
  • #221 — Proposal: Extension Mechanism (informed the shape of the bp.commands / bp.features design that landed in this release)
  • #216 — Flagged that the README was too long; led to the slim version that shipped here
  • #195 — Documentation Improvements (long-running tracking issue)
  • #193 — Proposed the community Discord

@emiliano-gandini-outeda has been pushing on documentation quality:

  • #199 — Issue documentation improvements (merged)
  • #201 — Follow-up documentation improvements

If you've been wondering why the docs felt sharper in this release, that's part of where it came from.

What this means in practice: both can triage issues, request changes on PRs, and merge to main. If you've been opening issues hoping for a response, that response will get faster.

If you want to talk to us

Join us on Discord, open an issue, or ping @igorbenav, @LucasQR, @carlosplanchon, or @emiliano-gandini-outeda on the repo. The plugin system is intentionally minimal in v0.18.0 — bp.commands and bp.features cover most needs, but if you're hitting a wall (e.g., you want app-factory hooks, settings-mixin extensions, lifespan plugins), that's exactly the kind of feedback that lands in v0.19 instead of waiting for v1.0.

What's New in v0.18.0

This release contains eight breaking changes (called out individually below) and one major addition (the CLI). The themes:

  1. Three-layer architecture with vertical-slice modules
  2. uv workspace split — backend/ (deployable) + cli/ (developer tool)
  3. bp CLI with plugin extension points — bp.commands and bp.features
  4. Server-side sessions + CSRF replaces JWT access/refresh tokens
  5. OAuth wired (Google end-to-end, GitHub scaffolded)
  6. API keys with scrypt + per-row salt + prefix-based lookup
  7. SQLAdmin replaces CRUDAdmin
  8. Taskiq replaces ARQ
  9. Swappable backends behind ABCs — Redis/Memcached/Memory for cache, sessions, rate limit
  10. Production security validator — startup gate that refuses insecure prod configs
  11. Full documentation rewrite + Zensical replaces MkDocs
  12. Lint enforcement — PLC0415 no-deferred-imports across the codebase

Breaking Changes Summary

Change Impact Migration Effort
src/app/ layout removed Imports break at import time High — manual restructure
JWT auth removed (sessions only) Authorization: Bearer clients rejected High — client-side cookie auth
CRUDAdmin → SQLAdmin Custom admin views need porting Medium
ARQ → Taskiq Workers need re-registration Medium
API key hash format Existing keys won't validate High — users must regenerate
Settings classes moved/composed Env var names mostly stable; a few moved Low
cd backend && uv sync --extra dev Silently produces a broken venv Low but easy to miss — use uv sync --all-packages --all-extras from repo root
Deployment scaffolder ./setup.py local no longer exists Low — use bp deploy generate
Docs generator: MkDocs → Zensical Local preview command + deploy workflow change Low

Detailed Changes

1. Three-Layer Architecture with Vertical-Slice Modules ⚠️ BREAKING

The old src/app/{admin,api,core,crud,middleware,models,schemas}/ layout was a horizontal slice per concern — every feature spread across seven directories. Adding a feature meant editing seven files; removing one (try removing posts from v0.17.0) meant playing whack-a-mole with imports.

The new layout splits by layer, then by vertical slice inside the domain layer:

backend/src/
├── interfaces/             # HTTP entry points: FastAPI app, routes, admin sub-app
├── infrastructure/         # Cross-cutting: cache, sessions, rate limit, taskiq, security, logging, db, config
└── modules/                # One directory per domain — owns its own models/schemas/crud/service/routes
    ├── user/
    ├── tier/
    ├── api_keys/
    ├── rate_limit/
    └── common/

Each module owns its full vertical: models.py, schemas.py, crud.py, service.py, routes.py, enums.py. Removing a feature is rm -rf modules/foo, register your import-time guard in the v1 includes list, and you're done.

Import Migration

Before (v0.17.0) After (v0.18.0)
from src.app.models.user import User from modules.user.models import User
from src.app.schemas.user import UserCreate from modules.user.schemas import UserCreate
from src.app.crud.crud_users import crud_users from modules.user.crud import crud_users
from src.app.api.v1.users import router from modules.user.routes import router
from src.app.core.config import settings from infrastructure.config.settings import get_settings
from src.app.core.db.database import get_db from infrastructure.database.session import async_session
from src.app.core.security import verify_password from infrastructure.auth.utils import verify_password

No automated rewrite exists. If you have a fork with custom modules, you'll need to relocate them into backend/src/modules/<your_module>/ with the standard layout.

2. uv Workspace Split — backend/ and cli/ ⚠️ BREAKING

The repo root is now a uv workspace with two members:

fastapi-boilerplate/
├── pyproject.toml          # Workspace root, not a shipped artifact
├── uv.lock                 # Single lockfile, shared
├── backend/
│   ├── pyproject.toml      # name = "fastapi-boilerplate"
│   ├── Dockerfile          # Multi-stage: dev / migrate / prod
│   └── src/
└── cli/
    ├── pyproject.toml      # name = "fastapi-boilerplate-cli", [scripts] ...
Read more

Contributors

carlosplanchon, igorbenav, and 2 other contributors
Assets 2
Loading

0.17.0

08 May 02:09
@igorbenav igorbenav
v0.17.0
84a70f2
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
0.17.0

Release v0.17.0 - Final Polish Before the Rebuild

Release Notes by FastAPI-boilerplate team

This is the final release of FastAPI-boilerplate in its current shape. After this, we're tearing the layout apart and rebuilding it as a real plugin system, then shipping 1.0 at the end. If you want to stay on the old shape, pin to v0.17.0 — once the restructure starts, main will be unstable for a while.

The changes in this release are mostly polishing. A lot of credit to @rragundez for cleaning up the settings layer — CORS got proper middleware, the .env file was being loaded twice through different code paths and now it isn't, hosts validation is in place, and the SQLite/MySQL settings classes that nobody actually used are gone (we're committing to Postgres as the default going forward). @sri-dhurkesh integrated structlog, so logging is actually structured now instead of f-string soup. @carlosplanchon updated dependencies for Python 3.14 and moved the installation scripts to a proper folder. We bumped FastCRUD to 0.19.2.

Nothing here should break apps you've built on the boilerplate. The breakage comes next.

Why we're restructuring

If you've cloned this template and tried to remove a feature you didn't want — say, posts — you've probably noticed it lives in five or six folders (models/, schemas/, crud/, api/v1/, plus the aggregator __init__.py). Easy to miss a file. People end up with dead code they didn't want, or they delete by hand and break imports somewhere downstream. That's the actual problem we're fixing.

The other thing that bothers us: cache is hard-coded to Redis, queue is hard-coded to ARQ, auth is hard-coded to JWT. If you want Memcached, Taskiq, or session-cookie auth, you have to fork the boilerplate and edit core. That's where most real users diverge from the template, and it's exactly the divergence that makes it stop receiving upstream updates cleanly. We want to fix that too.

users, tiers, auth, and health stay core in 1.0 — making everything a plugin would be a different project (and would mean 1.0 never ships). Save it for 2.0 if it ever matters.

Versioning during the restructure

Sticking with ZeroVer until 1.0. Each milestone is a tagged release you can pin to.

Each tag is independently shippable — if life intervenes, every milestone is a usable end state, not a half-finished refactor. Migration guides will land with each release that has breaking changes.

While we're in 0.x, once 0.x+1.y is released, support for 0.x.y is dropped. Eventually we'll get to SemVer at 1.0.

If you want to talk to us

Join us on Discord, open an issue, or ping @igorbenav on the repo. The restructure is a real chance to influence the shape of the boilerplate going forward — if there's something you want from a plugin system (a specific capability slot, a manifest field, a CLI command), now's the moment to say so. Easier to land it in 0.18 than to retrofit it post-1.0.

What's Changed

New Contributors

Full Changelog: v0.16.0...v0.17.0

Contributors

carlosplanchon, rragundez, and 3 other contributors
Loading

0.16.0

10 Nov 20:29
@igorbenav igorbenav
v0.16.0
16271bb
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
0.16.0

🚀 FastAPI Boilerplate v0.16.0

We're excited to announce v0.16.0 with major improvements to type safety and developer experience through the latest FastCRUD integration! 🎉

🌟 Key Highlights

  • Enhanced Type Safety: Upgraded to FastCRUD 0.19.1 with improved overloads for better type inference
  • Cleaner Codebase: Removed unnecessary manual type casting across the entire codebase
  • Better Developer Experience: Eliminated union types when using schema-based column selection
  • Health Check Endpoints: New endpoints for monitoring application health
  • Improved Documentation: Updated guides to reflect FastCRUD 0.19.0+ changes

🔧 What's Changed

  • 🔗 Fix: Fixed the discord link by @LucasQR in #203
  • 📚 Documentation: Updated docs to use SQLAlchemy 2.0 syntax by @carlosplanchon in #205
  • 🛠️ Fix: Update pre-commit hooks version to solve InvalidManifestError by @rragundez in #207
  • ⚙️ Enhancement: Update python specifier by @rragundez in #209
  • 🏥 New Feature: Add health check endpoints by @rragundez in #210
  • 📝 Documentation: Added note about falsy values from FastCRUD by @carlosplanchon in #214
  • 📦 Enhancement: Add pre-commit dependency in DEV group by @rragundez in #208
  • 🔄 Refactor: Adapt imports to FastCRUD 0.19.0 pagination structure by @carlosplanchon in #215
  • ⚡ Major Update: Upgrade to FastCRUD 0.19.1 with better typing by @igorbenav in #217

⚡ FastCRUD 0.19.1 Type Safety Improvements

This release brings significant type safety enhancements through FastCRUD 0.19.1:

Before v0.16.0:

# Required manual casting due to union types
user = await crud_users.get(db=db, username="john", schema_to_select=UserRead)
user = cast(dict[str, Any], user)  # Manual cast needed! 😞
if user["tier_id"] is None:
    # ...

After v0.16.0:

# Direct type-safe access - no casting needed!
user = await crud_users.get(db=db, username="john", schema_to_select=UserRead)
if user["tier_id"] is None:  # Directly type-safe! 😍
    # ...

What This Means:

  • No More Manual Casting: Eliminated all cast(dict[str, Any], result) calls
  • Better IDE Support: Improved autocomplete and error detection
  • Cleaner Code: Removed 25+ unnecessary cast statements across the codebase
  • Type Safety: mypy now properly infers Optional[dict[str, Any]] for schema-based column selection

🏥 Health Check Endpoints

New health monitoring capabilities:

GET /health          # Basic health check
GET /health/detailed # Detailed system health with database status

Perfect for:

  • Load balancer health checks
  • Monitoring system integration
  • Container orchestration readiness probes

🎉 New Contributors

We're grateful to welcome these new contributors to the project:

🔗 Links

🚀 Migration Guide

For Existing Projects:

  1. Update Dependencies:

    # Update pyproject.toml
fastcrud>=0.19.1

# Sync dependencies
uv sync

  2. Remove Manual Casts (if you added any):

    # Remove these patterns:
user = cast(dict[str, Any], user)
tier = cast(dict[str, Any], tier)

# FastCRUD 0.19.1 overloads handle this automatically!

  3. Update Import Structure:

    # New import structure for pagination
from fastcrud import PaginatedListResponse, compute_offset, paginated_response

  4. Run Tests:

    uv run pytest
uv run mypy src/ --config-file pyproject.toml

Benefits You'll Get:

  • ✅ Better Type Safety: No more union types for common patterns
  • ✅ Cleaner Code: Removed casting boilerplate
  • ✅ Enhanced DX: Better IDE support and error detection
  • ✅ Future-Proof: Ready for FastCRUD's continued improvements

What's Changed

New Contributors

Full Changelog: v0.15.0...v0.16.0

Powered by Benav Labs - benav.io

Contributors

carlosplanchon, rragundez, and 2 other contributors
Loading

0.15.0

09 Oct 19:28
@igorbenav igorbenav
v0.15.0
7c58913
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
0.15.0

🚀 FastAPI Boilerplate v0.15.0

We're excited to announce the launch of our Discord community! 🎉 Join fellow developers, get help, share projects, and stay updated with the latest FastAPI boilerplate developments.

🌟 Key Highlights

  • Discord Community: Join our new Discord server for real-time discussions and community support
  • UUID v7 Migration: Switched from UUID v4 to v7 for better performance and ordering
  • Enhanced Documentation: Improved documentation structure and added new resources

🔧 What's Changed

🎉 New Contributors

We're grateful to welcome these new contributors to the project:

🔗 Links

What's Changed

New Contributors

Full Changelog: v0.14.0...v0.15.0

Contributors

defp, carlosplanchon, and 4 other contributors
Loading

0.14.0

02 Jul 04:53
@igorbenav igorbenav
v0.14.0
01632e2
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
0.14.0

Benav Labs FastAPI boilerplate

Yet another template to speed your FastAPI development up, now with proper docs and an admin panel.

Python FastAPI Pydantic PostgreSQL Redis Docker NGINX

What's Changed

New Contributors

Full Changelog: v0.13.0...v0.14.0

📖 Documentation

📚 Visit our comprehensive documentation at benavlabs.github.io/FastAPI-boilerplate

⚠️ Documentation Status

This is our first version of the documentation. While functional, we acknowledge it's rough around the edges - there's a huge amount to document and we needed to start somewhere! We built this foundation (with a lot of AI assistance) so we can improve upon it.

Better documentation, examples, and guides are actively being developed. Contributions and feedback are greatly appreciated!

This README provides a quick reference for LLMs and developers, but the full documentation contains detailed guides, examples, and best practices.

0. About

FastAPI boilerplate creates an extendable async API using FastAPI, Pydantic V2, SQLAlchemy 2.0 and PostgreSQL:

  • FastAPI: modern Python web framework for building APIs
  • Pydantic V2: the most widely used data Python validation library, rewritten in Rust (5x-50x faster)
  • SQLAlchemy 2.0: Python SQL toolkit and Object Relational Mapper
  • PostgreSQL: The World's Most Advanced Open Source Relational Database
  • Redis: Open source, in-memory data store used by millions as a cache, message broker and more.
  • ARQ Job queues and RPC in python with asyncio and redis.
  • Docker Compose With a single command, create and start all the services from your configuration.
  • NGINX High-performance low resource consumption web server used for Reverse Proxy and Load Balancing.

Tip

There's a SQLModel version as well, but it's no longer updated: SQLModel-boilerplate.

1. Features

  • ⚡️ Fully async
  • 🚀 Pydantic V2 and SQLAlchemy 2.0
  • 🔐 User authentication with JWT
  • 🍪 Cookie based refresh token
  • 🏬 Easy redis caching
  • 👜 Easy client-side caching
  • 🚦 ARQ integration for task queue
  • ⚙️ Efficient and robust queries with fastcrud
  • ⎘ Out of the box offset and cursor pagination support with fastcrud
  • 🛑 Rate Limiter dependency
  • 👮 FastAPI docs behind authentication and hidden based on the environment
  • 🔧 Modern and light admin interface powered by CRUDAdmin
  • 🚚 Easy running with docker compose
  • ⚖️ NGINX Reverse Proxy and Load Balancing

2. Contents

  1. About
  2. Features
  3. Contents
  4. Prerequisites
    1. Environment Variables (.env)
    2. Docker Compose
    3. From Scratch
  5. Usage
    1. Docker Compose
    2. From Scratch
      1. Packages
      2. Running PostgreSQL With Docker
      3. Running Redis with Docker
      4. Running the API
    3. Creating the first superuser
    4. Database Migrations
  6. Extending
    1. Project Structure
    2. Database Model
    3. SQLAlchemy Models
    4. Pydantic Schemas
    5. Alembic Migrations
    6. CRUD
    7. Routes
      1. Paginated Responses
      2. HTTP Exceptions
    8. Caching
    9. More Advanced Caching
    10. ARQ Job Queues
    11. Rate Limiting
    12. JWT Authentication
    13. Admin Panel
    14. Running
    15. Create Application
    16. Opting Out of Services
  7. Running in Production
    1. Uvicorn Workers with Gunicorn
    2. Running With NGINX
      1. One Server
      2. Multiple Servers
  8. Testing
  9. Contributing
  10. References
  11. [Licens...
Read more

Contributors

geekashu, epinapala, and 11 other contributors
Loading

0.13.0

09 May 02:54
@igorbenav igorbenav
v0.13.0
4c1f9af
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
0.13.0

0.13.0 Summary

 🚀Features

 🔎Bug fixes

  • minor mypy and ruff fixes
  • gunicorn bumped, security issue fixed
  • fastcrud bumped to 0.12.0 with bug fixes

What's Changed

Full Changelog: v0.12.4...v0.13.0

Contributors

igorbenav
Loading

0.12.4

22 Feb 08:51
@igorbenav igorbenav
v0.12.4
45781d7
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
0.12.4

0.12.4 Summary

 🚀Features

  • improved scripts logging

 🔎Bug fixes

  • remove db.commit() from async_get_db - thanks @mithun2003
  • using fastcrud, result from get is no longer a db_row object, so no longer passing it in delete

What's Changed

  • logging added to scripts, get_db fix, endpoints fixed for fastcrud usage by @igorbenav in #121

Full Changelog: v0.12.3...v0.12.4

Contributors

igorbenav and mithun2003
Loading

0.12.3

15 Feb 03:28
@igorbenav igorbenav
v0.12.3
b1a8370
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
0.12.3

0.12.3

 🔎Bug fixes

What's Changed

New Contributors

Full Changelog: v0.12.2...v0.12.3

Contributors

rememberlenny and luca-medeiros
Loading

0.12.2

11 Feb 21:59
@igorbenav igorbenav
v0.12.2
189d5fd
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
0.12.2

0.12.2

⚡️Enhancements

  • now using recommended lifespan events instead of startup and shutdown events
  • libs bumped

 🔎Bug fixes

  • wrong .env reference in docker-compose fixed

What's Changed

Full Changelog: v0.11.1...v0.12.2

Contributors

igorbenav
Loading

0.11.1

03 Feb 19:17
@igorbenav igorbenav
v0.11.1
444ce98
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
0.11.1

0.11.1

 🔎Bug fixes

Warning

Content-Type Header ReDoS - FastAPI vulnerability fixed

Update python-multipart to 0.0.7 as soon as possible.

https://github.com/tiangolo/fastapi/security/advisories/GHSA-qf9m-vfgh-m389

What's Changed

Full Changelog: v0.11.0...v0.11.1

Contributors

igorbenav
Loading