fastapi-gino-arq-uvicorn
High-performance Async REST API, in Python. FastAPI + GINO + Arq + Uvicorn (powered by Redis & PostgreSQL).
Contents
Get Started
Setup
- Clone this Repository.
git clone https://github.com/leosussan/fastapi-gino-arq-uvicorn.git - Install
Python 3.8andpoetry.- Recommended Method:
asdf- a universal version manager (thinknvmorpyenv)- Follow these instructions to install
asdf. - Run the following commands from the project root:
asdf plugin add pythonasdf plugin add poetryasdf install-- will download & configure this project'sPython+poetrysetup
- Follow these instructions to install
- If you have
Python 3.8andpoetryinstalled already, please feel free to skip.
- Recommended Method:
- Install dependencies (
poetry install). - Activate pre-commit hooks (in
poetry shell, runpre-commit install). - Make a copy of
.dist.env, rename to.env. Fill in PostgreSQL, Redis, Sentry (optional) variables. - Generate DB Migrations: in
poetry shell, runalembic revision --autogenerate.- Apply migrations manually with
alembic upgrade head. - If using the Dockerfile, migrations are applied at startup.
- Apply migrations manually with
Run
Run Locally
NOTE: You must have PostgreSQL & Redis running locally.
- Make sure PostgreSQL & Redis are running locally.
- Run:
- FastAPI Application:
- For Active Development (w/ auto-reload): Run locally with
poetry run task app - For Debugging (compatible w/ debuggers, no auto-reload): Configure debugger to run
python app/main.py.
- For Active Development (w/ auto-reload): Run locally with
- Background Task Worker:
- For Active Development: Run
poetry run task worker
- For Active Development: Run
- FastAPI Application:
Run Locally with Docker-Compose.
- Make sure
Dockeris running locally. - Run
poetry run task compose-up*.- Run
poetry run task compose-downto spin down, clean up.
- Run
*app/settings/prestart.sh will run migrations for you before the app starts.
Build Your Application
- Create routes in
/app/routes, import & add them to theROUTERSconstant in/app/main.py - Create database models to
/app/models/orm, add them to/app/models/orm/migrations/env.pyfor migrations - Create pydantic models in
/app/models/pydantic - Store complex db queries in
/app/models/orm/queries - Store complex tasks in
app/tasks. - Add / edit globals to
/.env, expose & import them from/app/settings/globals.py- Use any coroutine as a background function: store a reference in the
ARQ_BACKGROUND_FUNCTIONSenv. - Set
SENTRY_DSNin your environment to enable Sentry.
- Use any coroutine as a background function: store a reference in the
- Define code to run before launch (migrations, setup, etc) in
/app/settings/prestart.sh
Features
Core Dependencies
- FastAPI: touts performance on-par with NodeJS & Go + automatic Swagger + ReDoc generation.
- GINO: built on SQLAlchemy core. Lightweight, simple, asynchronous ORM for PostgreSQL.
- Arq: Asyncio + Redis = fast, resource-light job queuing & RPC.
- Uvicorn: Lightning-fast, asynchronous ASGI server.
- Optimized Dockerfile: Optimized Dockerfile for ASGI applications, from https://github.com/tiangolo/uvicorn-gunicorn-docker.
Additional Dependencies
- PostgreSQL: Robust, fully-featured, scalable, open-source.
- Redis: Fast, simple, broker for the Arq task queue.
- Pydantic: Core to FastAPI. Define how data should be in pure, canonical python; validate it with pydantic.
- Alembic: Handles database migrations. Compatible with GINO.
- SQLAlchemy_Utils: Provides essential handles & datatypes. Compatible with GINO.
- Sentry: Open-source, cloud-hosted error + event monitoring.
- Pre-Commit: automatic formatting (
black+isort) and linting (flake8). - Taskipy: Small, flexible task runner for Poetry.