rikrdo/mercadodevida
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
75293f39bc3c6cae21031ed4e37fbe1d1808c569
mercadodevida/specs/F-002-database-foundation/DESIGN.md
rikrdo 425fedd13e feat(F-002): database foundation with migrations and dev compose 
- node-pg-migrate + pg: baseline migration (extensions, app_meta) with working down
- src/infrastructure/db fail-fast pool and typed query helper
- docker-compose: postgres:16-alpine + redis:7-alpine with one-command up
- table naming convention <module>_<table> documented in README
- integration tests (6) against real PostgreSQL; strict identifier validation
  for test DDL after security-gate hardening round
- deps justified in spec/tech.md; all gates approved; verify.sh green
2026-08-14 22:00:16 +02:00

2.5 KiB
Raw Blame History

DESIGN — F-002 Database foundation with module-owned schemas

Affected modules

  • src/infrastructure/db (new): pool factory + migration runner entry.

Modules touched

  • src/infrastructure/db
  • project/migrations/ (new folder, SQL files)
  • project/docker-compose.yml (new)

Modules NOT touched

  • All business modules. No HTTP API change. No shared/ change.

New interfaces

  • src/infrastructure/db/pool.ts: createPoolFromEnv(): Pool (fail fast if DATABASE_URL missing), query(text, params) helper typed over pg.
  • npm scripts: db:up, db:down, db:status, docker:up, docker:down, test:integration.

API changes

  • None.

Database changes

  • Baseline migration 001_baseline.js (node-pg-migrate, pgm.sql):
    • CREATE EXTENSION IF NOT EXISTS citext;
    • CREATE EXTENSION IF NOT EXISTS pgcrypto;
    • CREATE TABLE app_meta (key text PRIMARY KEY, value text NOT NULL, updated_at timestamptz NOT NULL DEFAULT now());
    • Down: drop table, drop extensions.
  • Migration version tracking table owned by the migration tool.

Naming convention (documented rule)

<module>_<table>        e.g. catalog_products, inventory_stock, orders_orders
<module>_<table>_id_seq sequences owned by their table
  • A module never queries tables without its own prefix.
  • Migrations are immutable once merged; fixes ship as new migrations.

Events

  • None.

External integrations

  • Docker Compose: postgres:16-alpine (port 5432), redis:7-alpine (port 6379), named volumes.

Cache changes

  • None (Redis present but unused until cache ticket).

Security considerations

  • Compose credentials are dev-only and public by design; documented as such.
  • .env.example committed, real .env gitignored.
  • No secrets in migration files.

Toolchain decisions

  • Migration tool: node-pg-migrate (pure npm dependency, battle-tested, SQL-first via pgm.sql, supports up/down and dry-run). Rejected: hand-rolled runner (reinvention), Flyway/golang-migrate (foreign toolchains for a Node monolith).
  • Driver: pg (standard).
  • Env loading: Node 22 --env-file flag; no dotenv dependency.

Test strategy

  • Integration tests (*.itest.ts) run only when TEST_DATABASE_URL is set: describe.skipIf — explicit, no magic.
  • They verify: fresh up creates schema; second up is no-op; down reverts cleanly; app_meta usable via pool helper.

Migration strategy

  • Greenfield; compose starts empty volume, migrations run from zero.

Rollback strategy

  • db:down reverts last migration; compose volumes can be removed with docker compose down -v.