+# SQLite Database

+

+Madagascar Local Authority folosește SQLite ca store runtime pentru registry și Work Orders.

+

+Locația implicită în checkout:

+

+```text

+var/host-manager.sqlite

+```

+

+Locația runtime pe jumper:

+

+```text

+/usr/local/xdev-host-manager/var/host-manager.sqlite

+```

+

+Path-ul poate fi schimbat cu:

+

+```text

+HOST_MANAGER_DB=/path/to/host-manager.sqlite

+```

+

+## Rol

+

+SQLite este sursa de adevăr runtime. Fișierele din `config/` nu mai sunt store-ul live:

+

+- `config/hosts.yaml` seed-uiește documentul `hosts_yaml` dacă baza este nouă.

+- `config/work-orders.yaml` seed-uiește documentul `work_orders_yaml` dacă baza este nouă.

+- `config/local-hosts.tsv` este manifest generat explicit din registry-ul SQLite.

+- `/download/hosts.yaml`, `/download/local-hosts.tsv` și `/download/monitoring.json` sunt randate din SQLite.

+

+Aplicația nu face commit/push automat după modificări. Exportul și arhivarea rămân pași operaționali separați.

+

+## Schema curentă

+

+Schema este creată automat de `scripts/host_manager.pl` la prima citire/scriere a store-ului.

+

+```sql

+CREATE TABLE IF NOT EXISTS documents (

+    name TEXT PRIMARY KEY,

+    content TEXT NOT NULL,

+    updated_at TEXT NOT NULL

+);

+```

+

+Setări aplicate la conectare:

+

+```sql

+PRAGMA journal_mode = WAL;

+PRAGMA foreign_keys = ON;

+```

+

+În schema curentă există o singură tabelă generică, `documents`. Conținutul operațional rămâne serializat în formatul YAML strict deja folosit de aplicație. Alegerea este deliberată pentru migrarea minimă: sursa de adevăr se mută din working tree în SQLite fără să schimbăm încă parserul, UI-ul sau formatul exporturilor.

+

+## Documente

+

+### `hosts_yaml`

+

+Conține registry-ul de hosturi în formatul `config/hosts.yaml`.

+

+Este citit de:

+

+- `GET /api/hosts`

+- `GET /download/hosts.yaml`

+- `GET /download/local-hosts.tsv`

+- `GET /download/monitoring.json`

+- `POST /api/render/local-hosts-tsv`

+

+Este scris de:

+

+- `POST /api/hosts/upsert`

+- `POST /api/hosts/delete`

+- `POST /api/work-orders/confirm`, când o acțiune modifică registry-ul

+

+Aplicația normalizează la salvare:

+

+```yaml

+policy:

+  storage_authority: "sqlite"

+  runtime_database: "<HOST_MANAGER_DB>"

+```

+

+### `work_orders_yaml`

+

+Conține Work Orders în formatul `config/work-orders.yaml`.

+

+Este citit de:

+

+- `GET /api/work-orders`

+- `POST /api/work-orders/checklist`

+- `POST /api/work-orders/confirm`

+

+Este scris de:

+

+- `POST /api/work-orders/checklist`

+- `POST /api/work-orders/confirm`

+

+## Seed inițial

+

+La prima accesare a unui document:

+

+1. Aplicația caută rândul în `documents`.

+2. Dacă rândul există, conținutul din SQLite câștigă.

+3. Dacă rândul lipsește, aplicația citește fișierul seed din `config/`.

+4. Dacă fișierul seed lipsește, aplicația creează un document gol valid.

+5. Documentul este inserat în SQLite și de atunci SQLite devine autoritatea.

+

+Important: după seed, modificările ulterioare ale fișierelor `config/hosts.yaml` sau `config/work-orders.yaml` nu schimbă automat baza existentă.

+

+## Fișiere SQLite

+

+Cu WAL activ, runtime-ul poate avea trei fișiere:

+

+```text

+var/host-manager.sqlite

+var/host-manager.sqlite-wal

+var/host-manager.sqlite-shm

+```

+

+Toate trei aparțin store-ului runtime. Nu se comit în git și nu se înlocuiesc prin deploy de cod.

+

+## Inspecție

+

+Pe jumper:

+

+```bash

+cd /usr/local/xdev-host-manager

+sqlite3 var/host-manager.sqlite '.schema'

+sqlite3 var/host-manager.sqlite 'select name, updated_at, length(content) from documents order by name;'

+sqlite3 var/host-manager.sqlite 'select content from documents where name = "hosts_yaml";'

+sqlite3 var/host-manager.sqlite 'select content from documents where name = "work_orders_yaml";'

+```

+

+Pentru export YAML curent:

+

+```bash

+curl -fsS -b cookies.txt https://hosts.madagascar.xdev.ro/download/hosts.yaml

+```

+

+Endpoint-urile de download sunt OTP-protected; exemplul presupune o sesiune validă.

+

+## Backup

+

+Backup recomandat, cu serviciul oprit sau prin API-ul SQLite:

+

+```bash

+cd /usr/local/xdev-host-manager

+sqlite3 var/host-manager.sqlite ".backup 'backups/host-manager/host-manager.sqlite.$(date +%Y%m%d_%H%M%S).bak'"

+```

+

+Pentru o copie brută, include și fișierele WAL/SHM sau oprește serviciul înainte:

+

+```bash

+sudo systemctl stop host-manager

+sudo cp -a var/host-manager.sqlite* backups/host-manager/

+sudo systemctl start host-manager

+```

+

+## Restore

+

+Restore-ul înlocuiește sursa de adevăr runtime și trebuie făcut explicit:

+

+```bash

+sudo systemctl stop host-manager

+sudo cp backups/host-manager/host-manager.sqlite.YYYYMMDD_HHMMSS.bak var/host-manager.sqlite

+sudo chown host-manager:host-manager var/host-manager.sqlite

+sudo systemctl start host-manager

+curl -fsS http://127.0.0.1:8088/healthz >/dev/null

+```

+

+Dacă se restaurează o copie brută, tratează `host-manager.sqlite`, `host-manager.sqlite-wal` și `host-manager.sqlite-shm` ca set coerent.

+

+## Evoluție probabilă

+

+Schema generică `documents` este potrivită pentru tranziția curentă. Dacă aplicația are nevoie de query-uri structurale, validări SQL sau merge/audit mai granular, următorul pas ar trebui să fie o migrare versionată către tabele dedicate, de exemplu:

+

+- `hosts`

+- `host_names`

+- `host_roles`

+- `host_sources`

+- `work_orders`

+- `work_order_checklist`

+- `work_order_actions`

+

+Până atunci, contractul stabil este numele documentelor din `documents` și formatele YAML randate de aplicație.

+- [`.doc/database.md`](.doc/database.md)

+- [.doc/database.md](.doc/database.md) - SQLite runtime store schema, seed rules, backup and restore.