Stage 2 · L10

Connect the persistence story to PostgreSQL and Compose

Core · original Session 2; extended normalization/cardinality visuals

Stage 02 replaces the synthetic catalogue with PostgreSQL rows. The application connects through SQLAlchemy's psycopg dialect. A URL begins postgresql+psycopg:// and supplies connection coordinates; the server process and the database are separate resources. equipment.database reads only LAB_DATABASE_URL and does not search .env files or provide a hidden production fallback.

The development Compose example binds PostgreSQL only to 127.0.0.1:55440 and uses a learner-owned named volume. A host-run application uses 127.0.0.1:55440. A container on the same Compose network uses the service name database and internal port 5432. Inside an app container, localhost means that container, not the database container. DNS/service names and host-published ports describe different paths.

Start the database, wait for its health check, then run python -m alembic upgrade head. Readiness of PostgreSQL does not mean your equipment table exists. Start the app only after migration, seed one row, and GET /equipment/1. Restarting the app now leaves the row in the separate database. The /health/live route proves application liveness; /health/ready executes SELECT 1 but does not certify every table or business query.

Use only the supplied synthetic local password for this private exercise. An environment variable prevents a secret from being hard-coded in Python but does not automatically make it secret from your shell history or process/container inspection. Do not reuse a real credential, print production URLs, or check .env into Git. The check runner creates its own random fixture credential and never prints it.

The isolated fixture owns an internal network and disposable tmpfs. The persistent Compose path was separately run through02→09 using one project name: a down/up restart retained the seeded rows, and later identity/audit migrations preserved existing rental IDs, owners and states. Keep one unique COMPOSE_PROJECT_NAME across copied checkpoint folders. Use docker compose down to stop your database; add --volumes only when intentionally discarding your learner data.

docker compose up -d --wait database
docker compose exec -T database pg_isready -U aabha_local -d aabha_local_learning
# Host-run application address: 127.0.0.1:55440
# Same-network container address: database:5432

The host app uses 127.0.0.1:55440; the networked container uses database:5432. Container localhost names itself. pg_isready proves the PostgreSQL process accepts connections, not that equipment exists. docker compose down retains the named volume; intentionally adding --volumes discards it. No session, flush or transaction implementation is required in this exercise.