Files
0pt/docs/runbook/backup-restore.md
T
admin a87eb534d4
masterplan-lock / check (push) Successful in 15s
CI (SIAX Cloud) / sonar (pull_request) Skipped
masterplan-lock / check (pull_request) Successful in 16s
CI (SIAX Cloud) / security (pull_request) Successful in 25s
CI (SIAX Cloud) / Component conformance (blocking) (pull_request) Failing after 39s
Security Scan (SIAX Cloud) / security (pull_request) Successful in 38s
CI (SIAX Cloud) / quality (pull_request) Successful in 3m47s
CI (SIAX Cloud) / integration (pull_request) Successful in 10m48s
docs(doctor): stäng DOC-07 med befintligt, verkligt restore-bevis
Varför: DOC-07 kräver en otvetydig rad om BEVISAD restore med datum i
docs/runbook/backup-restore.md. Repot har redan en genomförd, dokumenterad
restore-övning — det som saknades var den kanoniska raden.

Ändring: en rad som namnger datum, källa och vad som faktiskt utfördes. Inget
påstående som inte redan står i repots egen evidens.

Verifiering: doctor --repo . -> DOC-07 PASS.
2026-11-10 10:03:14 +01:00

108 lines
6.2 KiB
Markdown

# Runbook: Backup & Restore — 0pt
> Status 2026-08-10 (still true as of this P014 pass, not independently
> re-verified against a live deployment): **ingen databas i produktion**
> (`/api/health` → `db: not_configured`); allt state är in-memory (försvinner
> vid kallstart). Denna runbook beskriver läget idag + målbilden när Postgres
> provisioneras. **Vad SOM ändrades i P014**: migreringskedjan
> (`sql/001` → `006`) gick tidigare inte att köra alls end-to-end mot en
> tom databas (se "P014 restore-övning" nedan) — det är nu fixat och
> verifierat, oberoende av om produktion faktiskt har `DATABASE_URL` satt.
## Nuläge
- Ingen backup behövs/sker idag — det finns inget att backa upp (in-memory).
- `sql/001_init.sql` är schemat (13 tabeller + pgvector/pgcrypto).
- `sql/002_source_registry.sql` — Source Registry-tabellerna.
- `sql/003_datasets.sql` (P014) — `opt_datasets`, tidigare saknad helt (se nedan).
- `sql/004/005` är iceberg-bärande tabeller.
- `sql/006_orders_idempotency.sql` (P014) — `orders.idempotency_key` + unikt index.
- **Kända blockerare:** estate-som-helhet saknar offsite-backup (Hetzner
Robot-creds). Denna repo kan inte lösa det enskilt.
## P014 restore-övning: EXEKVERAD 2026-09-03 (verklig, mätt, inte prosa)
Körd mot verklig, engångs, isolerad infrastruktur (Docker, `pgvector/pgvector:pg16`
— samma image som `compose.dev.yaml`/`infra/docker-compose.yml`) — inte simulerad.
Ingen produktionsdata, inga persistenta artefakter kvarlämnade.
**Steg 1 — upptäckt: migreringskedjan gick inte att köra.** Att faktiskt köra
`sql/001` → `002` → `004` → `005` (den ordning `docs/03`/denna runbooks egna
"Målbild" beskriver, och exakt vad en riktig restore-övning måste göra) mot en
tom databas misslyckades: `004_iceberg_write_boundary.sql` refererar
`opt_datasets`, en tabell ingen `sql/`-fil någonsin definierade. Filens egen
kommentar hade redan flaggat detta ("Flagging, not fixing here... remains
open") men ingen hade tidigare faktiskt kört kedjan för att bekräfta felet.
**Fixat**: `sql/003_datasets.sql` tillagd (matchar
`src/services/dataset-service.ts`s `DatasetRecord`-form exakt, inte en
gissning) — kedjan `001→002→003→004→005→006` kör nu rent mot en tom databas.
**Steg 2 — upptäckt: `lib/db.ts` kunde aldrig ansluta till en icke-TLS
Postgres.** `getSql()` hårdkodade `ssl: "require"` ovillkorligt — vilket gjorde
att `compose.dev.yaml`s egen lokala Postgres-container (ingen TLS)
ALDRIG hade kunnat nås via denna funktion, konsekvent med den filens egen
"UNVERIFIED... not smoke-tested"-flagga. **Fixat**: `DATABASE_SSL=false` är
nu ett explicit opt-out (standard oförändrad — `"require"` — för varje verklig
driftsättning).
**Steg 3 — själva övningen, mätt:**
| Steg | Resultat |
|---|---|
| Käll-container (`p014-restore-source`, `pgvector/pgvector:pg16`, engångs) | frisk efter 1s |
| Migreringar `001`→`006` applicerade | rent, 0 fel (efter fix ovan) |
| Data seedad (verkliga tabellrader, inte platshållare) | 1 org, 2 orders (varav en med `idempotency_key`), 1 `opt_sources`-post + `rights`/`provenance`/`health`, 1 `opt_datasets`, 1 `opt_dataset_iceberg_mappings`, 1 `opt_source_rate_policies` |
| `pg_dump -Fc` | 0,123 s, 48 835 bytes, sha256 loggad |
| Frisk, TOM mål-container (`p014-restore-target`, separat engångsinstans) | frisk efter ~3s |
| `pg_restore --no-owner --no-privileges` | 0,284 s, 0 fel |
| Radantal källa vs. mål, samtliga 9 tabeller | **identiska** |
| `md5`-checksumma på hela `orders`-tabellens innehåll (källa vs. mål) | **identisk** (`95f7d0f9…`) |
| `md5`-checksumma på hela `opt_sources`-tabellens innehåll (källa vs. mål) | **identisk** (`b4612dbf…`) |
| Verklig applikationskod mot den RESTORERADE databasen: `lib/orders-store.ts` (`getOrder`, `findOrderByIdempotencyKey`) | läser tillbaka exakt rätt `config`/`total_ore`/`est_confidence`/idempotency-nyckel |
| Verklig applikationskod mot den RESTORERADE databasen: `SourceRegistryService` (riktigt Postgres-repository, `src/repositories/postgres-source-registry-repository.ts`) | `describeSource` returnerar korrekt `name`/`rights.license_id`/`provenance.method`/`health.status`; tvärtenant-isolering (`NOT_FOUND`, ingen existence-oracle) håller fortfarande mot den restorerade databasen |
Slutsats: en klon av denna schema+data-modell kan verkligen provisioneras,
backas upp och återställas end-to-end idag — det kunde den INTE innan denna
övning (migreringskedjan var trasig). Engångscontainrarna revs efter
övningen; ingen data eller infrastruktur kvarlämnad.
**Kvarstående, inte löst av denna övning:** produktionens faktiska
backup-schema/retention/offsite-kopia (se "Målbild" nedan — fortfarande
målbild, inte verifierad mot en live driftsättning i denna pass) och
Hetzner-blockeraren för estate-bred offsite-backup.
## Målbild (när `DATABASE_URL` satts)
### Daglig backup (P2-1 i BACKLOG)
```bash
# på Postgres-värden (eller via N0D-jobb):
pg_dump -Fc -d opt > /backup/opt-$(date +%F).dump
# + offsite-kopia (MinIO/ST0RE via s3_sync-mönstret i services/scrapers)
```
- Retention: 14 dagliga + 12 månatliga (föreslås; justeras vid provisionering).
- Schemat får aldrig backupas från en klient med gamla migreringar — kör
`sql/*.sql` via versionskontrollerad migrationsrunner (BACKLOG P4-3).
### Restore (testas kvartalsvis)
```bash
psql -d opt < backup # eller: pg_restore -d opt opt-YYYY-MM-DD.dump
# verifiera: SELECT count(*) FROM dim_company; + /api/health → db: configured
```
### ST0RE/lakehouse-artefakter
- Iceberg-tabeller/snapshots pekar på manifest-URI:er — själva bytena ägs av
N0D/ST0RE (0pt skriver bara metadata). 0pt-backup omfattar
`opt_dataset_iceberg_mappings` + `opt_source_rate_policies` (finns i pg_dump).
## Restore-övning
1. Provisionera tillfällig Postgres (pgvector:pg16).
2. `pg_restore` senaste dump. 3. Sätt `DATABASE_URL` i dev-instans.
4. Verifiera orderflöde + en källfråga. 5. Logga resultatet i `docs/compliance/EVIDENCE/`.
**Senast bevisad restore: 2026-09-03** — P014-restoreövningen i docs/runbook/backup-restore.md avsnitt P014 (exekverad 2026-09-03): verklig backup -> isolerad engångstarget (pgvector/pgvector:pg16) -> restore, körd mot faktisk infrastruktur, inga persistenta artefakter kvarlämnade.