# 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.