docs(adr): update docs and ADRs for Alembic adoption (#2)

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: nanotaboada

.github/copilot-instructions.md

@@ -11,7 +11,8 @@ and in-memory caching.
 - **Language**: Python 3.13
 - **Framework**: FastAPI + Uvicorn
 - **ORM**: SQLAlchemy 2.0 (async) + aiosqlite
-- **Database**: SQLite
+- **Database**: SQLite (local/test), PostgreSQL-compatible
+- **Migrations**: Alembic (async, `render_as_batch=True`)
 - **Validation**: Pydantic
 - **Caching**: aiocache (in-memory, 10-minute TTL)
 - **Testing**: pytest + pytest-cov + httpx
@@ -22,14 +23,15 @@ and in-memory caching.
 
 ```text
 main.py         — application entry point: FastAPI setup, router registration
+alembic.ini     — Alembic configuration (sqlalchemy.url set dynamically)
+alembic/        — Alembic migration environment and version scripts
 routes/         — HTTP route definitions + dependency injection     [HTTP layer]
 services/       — async business logic + cache management           [business layer]
 schemas/        — SQLAlchemy ORM models (database schema)           [data layer]
-databases/      — async SQLAlchemy session setup
+databases/      — async SQLAlchemy session setup + get_database_url()
 models/         — Pydantic models for request/response validation
-storage/        — SQLite database file (players-sqlite3.db, pre-seeded)
 scripts/        — shell scripts for Docker (entrypoint.sh, healthcheck.sh)
-tools/          — standalone seed scripts (run manually, not via Alembic)
+tools/          — legacy standalone seed scripts (superseded by Alembic migrations)
 tests/          — pytest integration tests
 ```
 
@@ -65,12 +67,13 @@ concerns only; business logic belongs in services. Never skip a layer.
 - **Logging**: `logging` module only; never `print()`
 - **Line length**: 88; complexity ≤ 10
 - **Import order**: stdlib → third-party → local
-- **Tests**: integration tests against the real pre-seeded SQLite DB via
-  `TestClient` — no mocking. Naming pattern
+- **Tests**: integration tests against the real SQLite DB (seeded via
+  Alembic migrations) via `TestClient` — no mocking. Naming pattern
   `test_request_{method}_{resource}_{context}_response_{outcome}`;
-  docstrings single-line, concise; `tests/player_stub.py` for test data;
+  docstrings single-line, concise; `tests/player_fake.py` for test data;
   `tests/conftest.py` provides a `function`-scoped `client` fixture for
-  isolation; `tests/test_main.py` excluded from Black
+  isolation; `tests/test_main.py` excluded from Black;
+  `tests/test_migrations.py` covers Alembic downgrade paths
 - **Decisions**: justify every decision on its own technical merits; never use
   "another project does it this way" as a reason — that explains nothing and
   may mean replicating a mistake
@@ -87,6 +90,9 @@ uv venv
 source .venv/bin/activate  # Linux/macOS; use .venv\Scripts\activate on Windows
 uv pip install --group dev
 
+# Apply migrations (required once before first run, and after down -v)
+uv run alembic upgrade head
+
 # Run application
 uv run uvicorn main:app --reload --port 9000       # http://localhost:9000/docs
 
@@ -98,6 +104,11 @@ uv run pytest --cov=./ --cov-report=term           # with coverage (target >=80%
 uv run flake8 .
 uv run black --check .
 
+# Migration workflow
+uv run alembic upgrade head                        # apply all pending migrations
+uv run alembic downgrade -1                        # roll back last migration
+uv run alembic revision --autogenerate -m "desc"   # generate migration from schema
+
 # Docker
 docker compose up
 docker compose down -v
@@ -149,9 +160,10 @@ Never suggest a release tag with a coach name not on this list.
 
 ### Ask before changing
 
-- Database schema (`schemas/player_schema.py` — no Alembic; changes require
-  manually updating `storage/players-sqlite3.db` and the seed scripts in
-  `tools/`)
+- Database schema (`schemas/player_schema.py`) and Alembic migrations
+  (`alembic/versions/`) — schema changes require a new migration file;
+  seed data changes require updating the relevant migration and any test
+  fixtures that reference specific UUIDs
 - `models/player_model.py` design decisions — especially splitting or merging
   request/response models; discuss the rationale before restructuring
 - Dependencies (`pyproject.toml` with PEP 735 dependency groups)
@@ -164,8 +176,8 @@ Never suggest a release tag with a coach name not on this list.
 ### Never modify
 
 - `.env` files (secrets)
-- `storage/players-sqlite3.db` directly — schema changes go through
-  `schemas/player_schema.py` and `tools/` seed scripts
+- `alembic/versions/` migration files once merged to `master` — migrations
+  are append-only; fix forward with a new migration, never edit history
 - Production configurations
 
 ### Creating Issues
@@ -194,10 +206,11 @@ shape is new → add async service method in `services/` with error handling and
 rollback → add route in `routes/` with `Depends(generate_async_session)` →
 add tests following the naming pattern → run pre-commit checks.
 
-**Modify schema**: Update `schemas/player_schema.py` → manually update
-`storage/players-sqlite3.db` (preserve all 26 seeded players) → update
-`models/player_model.py` if the API shape changes → update services and tests
-→ run `pytest`.
+**Modify schema**: Update `schemas/player_schema.py` → run
+`uv run alembic revision --autogenerate -m "description"` to generate a
+migration → review and adjust the generated file in `alembic/versions/` →
+run `uv run alembic upgrade head` → update `models/player_model.py` if the
+API shape changes → update services and tests → run `pytest`.
 
 **After completing work**: Propose a branch name and commit message for user
 approval. Do not create a branch, commit, or push until the user explicitly

README.md

@@ -21,7 +21,7 @@ Proof of Concept for a RESTful Web Service built with **FastAPI** and **Python 3
 - 📚 **Interactive Documentation** - Auto-generated Swagger UI with VS Code and JetBrains REST Client support
 - ⚡ **Performance Caching** - In-memory caching with aiocache and async SQLite operations
 - ✅ **Input Validation** - Pydantic models enforce request/response schemas with automatic error responses
-- 🐳 **Containerized Deployment** - Production-ready Docker setup with pre-seeded database
+- 🐳 **Containerized Deployment** - Production-ready Docker setup with migration-based database initialization
 - 🔄 **Automated Pipeline** - Continuous integration with Black, Flake8, and automated testing
 
 ## Tech Stack
@@ -171,6 +171,10 @@ uv pip install --group dev
 ### Run
 
 ```bash
+# Apply database migrations (required once before the first run, and after
+# docker compose down -v)
+uv run alembic upgrade head
+
 uv run uvicorn main:app --reload --port 9000
 ```
 
@@ -190,7 +194,7 @@ Once the application is running, you can access:
 docker compose up
 ```
 
-> 💡 **Note:** On first run, the container copies a pre-seeded SQLite database into a persistent volume. On subsequent runs, that volume is reused and the data is preserved.
+> 💡 **Note:** On first run, the entrypoint applies Alembic migrations (`alembic upgrade head`), which creates the database and seeds all 26 players. On subsequent runs, migrations are a no-op and the volume data is preserved.
 
 ### Stop
 
@@ -200,7 +204,7 @@ docker compose down
 
 ### Reset Database
 
-To remove the volume and reinitialize the database from the built-in seed file:
+To remove the volume and re-apply migrations from scratch on next start:
 
 ```bash
 docker compose down -v
@@ -224,8 +228,14 @@ docker pull ghcr.io/nanotaboada/python-samples-fastapi-restful:latest
 ## Environment Variables
 
 ```bash
-# Database storage path (default: ./storage/players-sqlite3.db)
-STORAGE_PATH=./storage/players-sqlite3.db
+# Full async database URL (SQLite default, PostgreSQL compatible)
+# SQLite (local/test):
+DATABASE_URL=sqlite+aiosqlite:///./players-sqlite3.db
+# PostgreSQL (Docker/production):
+DATABASE_URL=postgresql+asyncpg://postgres:password@localhost:5432/playersdb
+
+# Legacy: SQLite file path — used only when DATABASE_URL is not set
+STORAGE_PATH=./players-sqlite3.db
 
 # Python output buffering: set to 1 for real-time logs in Docker
 PYTHONUNBUFFERED=1

docs/adr/0002-no-alembic-manual-seed-scripts.md

@@ -4,8 +4,8 @@ Date: 2026-03-21
 
 ## Status
 
-Accepted. Migration to Alembic is under consideration — tracked in
-issue #2.
+Superseded by [ADR-0010](0010-alembic-migration-based-schema-management.md).
+Alembic was adopted in issue #2.
 
 ## Context
 

docs/adr/0009-docker-and-compose-strategy.md

@@ -49,14 +49,13 @@ locally.
   (for the health check); copies the pre-built wheels from the builder;
   installs them with `--no-index --find-links` (no network access, no
   build tools required); removes the wheelhouse after installation.
-- **Entrypoint script**: on first start, copies the pre-seeded database
-  from the image's read-only `hold/` directory to the writable named
-  volume at `/storage/`, then runs both seed scripts to ensure the schema
-  and data are up to date. On subsequent starts, the volume file is
-  preserved and seed scripts run again (they are idempotent).
+- **Entrypoint script**: runs `alembic upgrade head` before launching
+  Uvicorn. Alembic creates the database and seeds all 26 players on first
+  start; on subsequent starts it is a no-op (already at head). No
+  pre-seeded file is bundled in the image.
 - **Compose (`compose.yaml`)**: defines a single service with port
   mapping (`9000`), a named volume (`storage`), and environment variables
-  (`STORAGE_PATH`, `PYTHONUNBUFFERED=1`). Health checks are declared in
+  (`DATABASE_URL`, `PYTHONUNBUFFERED=1`). Health checks are declared in
   the Dockerfile (`GET /health`); Compose relies on that declaration.
 - A non-root `fastapi` user is created in the runtime stage following the
   principle of least privilege.
@@ -81,10 +80,11 @@ locally.
 - The wheelhouse is an intermediate artifact: if a wheel cannot be
   pre-built (e.g. binary-only distributions without a source distribution),
   the builder stage will fail.
-- The seed scripts run on every container start. They are idempotent but
-  add latency to startup and must remain so as the project evolves.
-- The SQLite database file is versioned and bundled, meaning schema changes
-  require a Docker image rebuild.
+- `alembic upgrade head` runs on every container start. It is a no-op
+  when no migrations are pending but adds a small DB round-trip to startup
+  time.
+- Schema changes now require an Alembic migration rather than a Docker
+  image rebuild; see ADR-0010.
 
 **When to revisit:**
 

docs/adr/0010-alembic-migration-based-schema-management.md

@@ -0,0 +1,83 @@
+# ADR-0010: Alembic — Migration-Based Schema Management
+
+Date: 2026-04-09
+
+## Status
+
+Accepted. Supersedes [ADR-0002](0002-no-alembic-manual-seed-scripts.md).
+
+## Context
+
+ADR-0002 decided against Alembic in favour of standalone seed scripts in
+`tools/`, citing low schema churn and the simplicity of a single committed
+SQLite file. Issue #2 was opened to revisit this decision when the project
+matured.
+
+Several factors made the status quo unsustainable:
+
+- Committing a binary `.db` file to the repository means every schema
+  change produces an opaque, unreviewable diff. Reviewers cannot tell what
+  data changed or why.
+- The Docker entrypoint copied a pre-seeded file from the image into the
+  container volume — coupling the data to the image build and requiring a
+  full rebuild whenever the dataset changed.
+- The project targets future PostgreSQL support (issue #542), which a
+  SQLite-only committed file cannot accommodate.
+- As a cross-language educational reference, the project should demonstrate
+  production-grade database lifecycle practices, and Alembic is the standard
+  tool for SQLAlchemy projects.
+
+## Alternatives Considered
+
+- **Keep the committed `.db` file + seed scripts**: Already rejected in
+  issue #2; the coupling to the binary file blocks PostgreSQL support and
+  produces unreadable diffs.
+- **Prisma Client Python**: Requires Node.js alongside Python, uses its own
+  schema DSL instead of SQLAlchemy models, and has less mature Python
+  support. Rejected because it would introduce a second source of truth for
+  the schema.
+
+## Decision
+
+We will use Alembic as the schema and seed data migration tool.
+
+Three migration files replace the committed database and the standalone
+seed scripts:
+
+- `001_create_players_table.py` — autogenerated from the SQLAlchemy `Player`
+  schema; creates the `players` table.
+- `002_seed_starting11.py` — inserts the 11 Starting XI players using
+  deterministic UUID v5 values.
+- `003_seed_substitutes.py` — inserts the 15 Substitute players using
+  deterministic UUID v5 values.
+
+`alembic/env.py` is configured for async SQLAlchemy (`asyncio.run` via
+thread executor), reads `DATABASE_URL` from the environment (SQLite default,
+PostgreSQL compatible), and sets `render_as_batch=True` for SQLite `ALTER
+TABLE` compatibility. Each migration's `downgrade()` function deletes only
+the rows it inserted (by UUID), so migrations are independently reversible.
+
+`alembic upgrade head` is run by `entrypoint.sh` before Uvicorn starts
+(Docker). For local development, it is run once manually:
+`uv run alembic upgrade head`.
+
+## Consequences
+
+**Positive:**
+- Schema and seed data changes are versioned, reviewable, and reversible.
+- The committed `.db` file is removed from the repository; `*.db` is
+  added to `.gitignore`.
+- `DATABASE_URL` environment variable enables the same codebase to target
+  both SQLite (local/test) and PostgreSQL (Docker/production) without code
+  changes — a prerequisite for issue #542.
+- UUID v5 seed values are deterministic across environments, so test
+  fixtures that reference player IDs remain stable.
+
+**Negative:**
+- Local development requires `uv run alembic upgrade head` before the first
+  server start (or after a `docker compose down -v`).
+- Alembic's offline mode (`alembic --sql`) is not exercised by integration
+  tests; `alembic/env.py` offline path is excluded from coverage.
+- `render_as_batch=True` means SQLite schema changes use a copy-transform-
+  replace strategy rather than `ALTER TABLE` — this is invisible to callers
+  but must be understood when debugging migration failures.

tests/test_migrations.py

@@ -18,48 +18,48 @@
 from alembic import command
 from alembic.config import Config
 
-_DB_PATH = os.getenv("STORAGE_PATH", "./players-sqlite3.db")
-_alembic_config = Config(str(Path(__file__).resolve().parent.parent / "alembic.ini"))
+DB_PATH = os.getenv("STORAGE_PATH", "./players-sqlite3.db")
+ALEMBIC_CONFIG = Config(str(Path(__file__).resolve().parent.parent / "alembic.ini"))
 
 
 def test_migration_downgrade_003_removes_substitutes_only():
     """Downgrade 003→002 removes the 15 seeded substitutes, leaves Starting XI."""
-    command.downgrade(_alembic_config, "-1")
+    command.downgrade(ALEMBIC_CONFIG, "-1")
 
-    conn = sqlite3.connect(_DB_PATH)
+    conn = sqlite3.connect(DB_PATH)
     total = conn.execute("SELECT COUNT(*) FROM players").fetchone()[0]
     subs = conn.execute("SELECT COUNT(*) FROM players WHERE starting11=0").fetchone()[0]
     conn.close()
 
-    command.upgrade(_alembic_config, "head")
+    command.upgrade(ALEMBIC_CONFIG, "head")
 
     assert total == 11
     assert subs == 0
 
 
 def test_migration_downgrade_002_removes_starting11_only():
     """Downgrade 002→001 removes the 11 seeded Starting XI, leaves table empty."""
-    command.downgrade(_alembic_config, "-2")
+    command.downgrade(ALEMBIC_CONFIG, "-2")
 
-    conn = sqlite3.connect(_DB_PATH)
+    conn = sqlite3.connect(DB_PATH)
     total = conn.execute("SELECT COUNT(*) FROM players").fetchone()[0]
     conn.close()
 
-    command.upgrade(_alembic_config, "head")
+    command.upgrade(ALEMBIC_CONFIG, "head")
 
     assert total == 0
 
 
 def test_migration_downgrade_001_drops_players_table():
     """Downgrade 001→base drops the players table entirely."""
-    command.downgrade(_alembic_config, "base")
+    command.downgrade(ALEMBIC_CONFIG, "base")
 
-    conn = sqlite3.connect(_DB_PATH)
+    conn = sqlite3.connect(DB_PATH)
     table = conn.execute(
         "SELECT name FROM sqlite_master WHERE type='table' AND name='players'"
     ).fetchone()
     conn.close()
 
-    command.upgrade(_alembic_config, "head")
+    command.upgrade(ALEMBIC_CONFIG, "head")
 
     assert table is None