{"id":51232117,"url":"https://github.com/msanvarov/fastapi-rest-postgres-boilerplate","last_synced_at":"2026-06-28T17:01:35.069Z","repository":{"id":362757440,"uuid":"1260632118","full_name":"msanvarov/fastapi-rest-postgres-boilerplate","owner":"msanvarov","description":"backend with fastapi and postgres","archived":false,"fork":false,"pushed_at":"2026-06-05T19:43:41.000Z","size":327,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-05T20:13:14.832Z","etag":null,"topics":["backend","docker","fastapi","postgresql"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/msanvarov.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-05T17:47:04.000Z","updated_at":"2026-06-05T19:53:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/msanvarov/fastapi-rest-postgres-boilerplate","commit_stats":null,"previous_names":["msanvarov/fastapi-rest-postgres-boilerplate"],"tags_count":null,"template":true,"template_full_name":null,"purl":"pkg:github/msanvarov/fastapi-rest-postgres-boilerplate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msanvarov%2Ffastapi-rest-postgres-boilerplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msanvarov%2Ffastapi-rest-postgres-boilerplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msanvarov%2Ffastapi-rest-postgres-boilerplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msanvarov%2Ffastapi-rest-postgres-boilerplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/msanvarov","download_url":"https://codeload.github.com/msanvarov/fastapi-rest-postgres-boilerplate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msanvarov%2Ffastapi-rest-postgres-boilerplate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34896652,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-28T02:00:05.809Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backend","docker","fastapi","postgresql"],"created_at":"2026-06-28T17:01:33.173Z","updated_at":"2026-06-28T17:01:35.063Z","avatar_url":"https://github.com/msanvarov.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FastAPI Async Boilerplate\n\nA production-grade FastAPI starter with PostgreSQL, async SQLAlchemy 2.0,\nexplicit concurrency limits, and the tooling you actually want on day one.\n\n## Highlights\n\n- **uv** for package management, **ruff** for lint + format, **mypy --strict**\n  for typing, **pytest** for tests, **pre-commit** for git hooks (incl.\n  `gitleaks` for secret scanning and `conventional-pre-commit` for commit\n  message hygiene).\n- **Async-first**: SQLAlchemy 2.0 + asyncpg, `httpx.AsyncClient` with HTTP/2,\n  Redis-backed sliding-window rate limiting, `structlog` with context-vars\n  that flow across `await` boundaries.\n- **Bounded concurrency**: process-wide `asyncio.Semaphore` instances guard\n  DB connections, outbound HTTP, and a CPU-bound `ThreadPoolExecutor`.\n  Helpers (`gather_with_concurrency`, `bounded_map`, `run_cpu_bound`,\n  `BackgroundTaskSupervisor`, `timeout_after`) make the safe path the\n  default — see `src/app/core/concurrency.py`.\n- **Clean architecture**: `endpoints → services → repositories → models`.\n  Services own transaction boundaries via an explicit `UnitOfWork`.\n- **Observability**: per-request `X-Request-ID`, structured access logs,\n  `/health/live` + `/health/ready` for k8s probes, stable JSON error envelope.\n- **Hardening**: Argon2id passwords (offloaded to a thread-pool), JWT access\n  + refresh with rotation, trusted-host + CORS + gzip middleware, timeout\n  middleware that converts hangs to `504 Gateway Timeout`.\n- **Ops**: multi-stage non-root Dockerfile (~80 MB), gunicorn + uvicorn\n  workers, Alembic with async env, GitHub Actions CI matrix.\n\n## Project layout\n\n```\nsrc/app\n├── api/v1            # versioned routers + per-resource endpoints\n├── core              # config, logging, security, concurrency primitives\n├── db                # async engine, session, UoW, models, base\n├── middleware        # request-id, timeout, rate-limit\n├── repositories      # data access — no business rules\n├── services          # business logic — own the transaction\n├── schemas           # pydantic v2 request/response models\n└── utils             # http client, etc.\n```\n\n## Quickstart\n\n```bash\n# 1. Install deps and git hooks\nmake install\nmake env          # copies .env.example -\u003e .env\nmake hooks\n\n# 2. Boot Postgres + Redis\nmake db-up\n\n# 3. Migrate + run\nmake migrate\nmake run          # http://localhost:8000/docs\n```\n\n## Common tasks\n\n| Command            | Action                                  |\n| ------------------ | --------------------------------------- |\n| `make fmt`         | Format + autofix with ruff              |\n| `make check`       | Lint + type-check                       |\n| `make test`        | Pytest with coverage                    |\n| `make migration m=\"...\"` | Generate a new Alembic revision   |\n| `make migrate`     | Apply pending migrations                |\n| `make docker-up`   | Run the full stack in Docker            |\n\n## Concurrency model — the parts to read first\n\n| Primitive                    | What it guards                                          |\n| ---------------------------- | ------------------------------------------------------- |\n| `ConcurrencyLimits.db`       | DB connections in flight per worker                     |\n| `ConcurrencyLimits.http`     | Outbound HTTP calls per worker                          |\n| `ConcurrencyLimits.cpu` + executor | CPU-bound work (Argon2, hashing, image processing) |\n| `gather_with_concurrency`    | Bounded `asyncio.gather` — never unbounded fan-out      |\n| `BackgroundTaskSupervisor`   | Strong-refs fire-and-forget tasks; logs failures        |\n| `timeout_after` + middleware | Per-coroutine and per-request deadlines                 |\n\nOpen `src/app/core/concurrency.py` and `src/app/services/user_service.py`\nfor the canonical usage examples — registration hashes the password via\n`run_cpu_bound` *outside* the DB transaction so we never hold a connection\nwhile burning CPU.\n\n## Environment variables\n\nSee `.env.example` for the full list. Key knobs:\n\n- `DB_SEMAPHORE_LIMIT` — concurrent DB-bound coroutines per worker\n- `HTTP_SEMAPHORE_LIMIT` — concurrent outbound HTTP per worker\n- `CPU_SEMAPHORE_LIMIT` — threadpool size for CPU-bound work\n- `REQUEST_TIMEOUT_SECONDS` — per-request deadline\n- `RATE_LIMIT_PER_MINUTE` — sliding-window cap per client identity\n\n## Testing\n\n```bash\nmake test          # all\nmake test-unit     # unit only (no DB)\nmake test-int     # integration (needs Postgres+Redis)\n```\n\nIntegration tests boot the full ASGI app via `httpx.ASGITransport` and run\nagainst the Postgres in `docker compose` (locally) or the GitHub Actions\nservice container (CI).\n\n## License\n\nMIT.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmsanvarov%2Ffastapi-rest-postgres-boilerplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmsanvarov%2Ffastapi-rest-postgres-boilerplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmsanvarov%2Ffastapi-rest-postgres-boilerplate/lists"}