mirror of
https://github.com/Tria-plc/edr-platform.git
synced 2026-08-26 18:42:49 +00:00
47 lines
2.8 KiB
Markdown
47 lines
2.8 KiB
Markdown
---
|
|
name: edr-db
|
|
description: Query, EXPLAIN-validate, and inspect the remote EDR freight dev database. Use whenever you need to check data, verify a raw SQL statement before shipping it, list a table's columns, check schema drift, or see which migrations are recorded. psql is NOT installed on this machine — this runner is the sanctioned path. Triggers - "check the db", "query edr_dev", "does column X exist", "validate this SQL", "is migration recorded", "seed check", diagnosing a 400/500 whose cause may be data or schema.
|
|
---
|
|
|
|
# EDR dev-DB runner
|
|
|
|
One script, runs from anywhere in the repo (resolves `pg` from `apps/edr-freight-api`):
|
|
|
|
```bash
|
|
node .claude/skills/edr-db/query.cjs "SELECT ... " # run SQL, console.table output
|
|
node .claude/skills/edr-db/query.cjs explain "SELECT ..." # EXPLAIN-validate only (no rows touched)
|
|
node .claude/skills/edr-db/query.cjs columns <table> # freight.<table> column list
|
|
node .claude/skills/edr-db/query.cjs migrations [like] # migration rows, newest first (freight.migrations + iam.typeorm_migrations)
|
|
node .claude/skills/edr-db/query.cjs drift <table> # bare column names, for diffing vs the entity
|
|
```
|
|
|
|
Connection comes from `DB_HOST` / `DB_PORT` / `DB_USER` / `DB_PASSWORD` / `DB_NAME`,
|
|
defaulting to the shared dev database (`edr_dev`).
|
|
|
|
## Rules that go with it
|
|
|
|
- **HARD RULE: every raw SQL statement you write into a service must pass
|
|
`explain` here before you ship it.** A typo'd column is a runtime 500 the
|
|
type-checker cannot catch.
|
|
- Never assume a recorded migration applied — check `migrations <name>` **and**
|
|
`columns <table>` together. Recorded-but-absent = schema drift; fix with a
|
|
NEW repair migration (idempotent DDL, no-op `down()`), never by editing the
|
|
recorded one.
|
|
- Writes to dev data are fine for seeding/diagnosis but keep them idempotent
|
|
(`WHERE NOT EXISTS` guards) — watch-mode API instances race `migrationsRun`,
|
|
and non-idempotent statements have double-run here before.
|
|
- Timestamps for new migrations: must be unique across `src/migrations/` AND
|
|
higher than `SELECT max(timestamp) FROM freight.migrations`.
|
|
- Freight and IAM keep separate histories: `freight.migrations` for
|
|
`apps/edr-freight-api/src/migrations/*`, `iam.typeorm_migrations` for the
|
|
`@tria-plc/iamapi-common` migrations. `public.migrations` is the pre-split
|
|
table, left in place for rollback — never write to it.
|
|
|
|
## Diagnosing a pasted 400/500 (the recurring loop)
|
|
|
|
1. Find the route: grep the path segment in `apps/edr-freight-api/src/modules/*/**.controller.ts`.
|
|
2. Read the service method — list its guard `throw`s. Most "bugs" are a guard
|
|
working as designed (handover unsigned, fee unpaid, not PAID, wrong direction).
|
|
3. Check the actual DB state for that record with this runner.
|
|
4. Only then decide: guard doing its job (fix the UI affordance) vs real defect.
|