# Istanza e database > **Stato:** parziale · **Ultima revisione:** 2026-11-11 · **Versione software:** 0.2.0 (milestone M2 e M12) > **Modulo di licenza:** CORE (aziende oltre la prima: MULTI) · **Livello richiesto:** amministratore; azioni distruttive solo super utente · **Specifica:** SPEC §5.3, §5.4, §7.1, §12.1, §13 > **Nella versione 0.2.0** ci sono la creazione della prima azienda al primo avvio, la creazione e il collegamento > di altre aziende (dal codice, con il modulo MULTI), gli stati *attiva / manutenzione / sola lettura / disattivata* > con le sessioni chiuse quando un'azienda va in manutenzione e il contesto azienda per pagine e API (header > `X-Company`). Le schermate descritte qui arrivano in M12. ## A cosa serve Un'installazione di Khaemhat (una **istanza**, cioè un container) può servire più aziende. Ogni azienda ha il **proprio database**; tutte condividono un unico **database di sistema** che contiene solo l'amministrazione. La pagina **Istanza e database** è il punto da cui si vedono tutti i database dell'istanza e da cui si creano, collegano, clonano, migrano, mantengono ed eliminano le aziende. | Database | Nome | Cosa contiene | |---|---|---| | **Database di sistema** | `khaemhat_system` (variabile `KHAEMHAT_SYSTEM_DB`) | elenco delle aziende con la loro connessione (cifrata), super utente e amministratori, modelli dei ruoli, impostazioni di sistema, licenze e storico attivazioni, attività programmate e loro esecuzioni, politiche e insiemi di backup, log applicativo, audit di sicurezza, chiavi di protezione dei cookie, chiavi API di istanza, notifiche e sessioni degli account di istanza | | **Database aziendale** | `khaemhat_` (es. `khaemhat_demo`) | tutti i dati operativi dell'azienda (anagrafiche, documenti, magazzino, contabilità…), i suoi **utenti**, ruoli e permessi, sessioni, preferenze, chiavi API, notifiche, allegati, storico delle modifiche (`audit_log`) e profilo azienda | Le aziende condividono **solo** l'amministrazione: un utente aziendale vive nel database della sua azienda e non vede le altre. Le tabelle operative non hanno un campo "azienda": la separazione è data dal database stesso. ## Dove si trova **Amministrazione → Istanza e database**. Il menu **Amministrazione** è visibile solo agli account di istanza (super utente e amministratori). Facendo doppio clic su un database si apre il suo **dettaglio** in una nuova scheda. ## Schermate ![078 · Amministrazione · istanza, database di sistema e per azienda](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/078-admin-istanza-database.png) *Mockup 078 — elenco dei database dell'istanza (sistema, aziende, ambiente di prova, archivio SQLite in sola lettura) con server, dimensione, stato dello schema, ultimo backup e stato; sotto, le informazioni sul server PostgreSQL e i riquadri informativi (anteprima ridotta)* ![079 · Amministrazione · dettaglio database: backup, cloud, ripristino, manutenzione](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/079-admin-database-backup-ripristino.png) *Mockup 079 — dettaglio del database `khaemhat_demo`: schede Backup e ripristino, Manutenzione, Migrazioni, Utenti dell'azienda, Connessione; politica di backup, backup disponibili, verifica integrità e ricostruzioni (anteprima ridotta)* ### L'elenco dei database (078) | Colonna | Significato | |---|---| | **Database** | nome fisico (`khaemhat_system`, `khaemhat_demo`, …); clic per aprire il dettaglio | | **Azienda / uso** | ragione sociale o uso (sistema, ambiente di prova, archivio) | | **Server** | motore e versione (PostgreSQL o SQLite) e indirizzo del server o percorso del file | | **Dimensione** | spazio occupato | | **Schema** | *Allineato* oppure numero di migrazioni in attesa | | **Ultimo backup** | data e ora dell'ultimo backup riuscito | | **Stato** | *Attiva*, *Manutenzione*, *Sola lettura*, *Disattivata*; per le aziende attive anche gli utenti collegati | | **Note** | ad esempio *predefinita*, *clonata da…*, modulo richiesto | In alto a destra: **Nuova azienda (database)** e **Collega database esistente**. Nella barra a icone: **Backup adesso**, **Clona**, **Elimina** e le altre azioni sul database selezionato. ### Il dettaglio del database (079) Intestazione con dimensione, numero di migrazioni applicate e ultimo backup. Azioni principali: **Backup adesso**, **Ripristina…**, **Prova di ripristino**. Schede: - **Backup e ripristino** — politica di backup, elenco dei backup, ripristino: vedi [Backup e ripristino](Backup-e-ripristino). - **Manutenzione** — verifica integrità, ricostruzioni, operazioni sul motore (vedi sotto). - **Migrazioni** — migrazioni applicate e in attesa per modulo. - **Utenti dell'azienda** — gli utenti che vivono in quel database (vedi [Utenti e permessi](Utenti-e-permessi)). - **Connessione** — motore e parametri di connessione (la stringa di connessione è conservata cifrata). ## Chi può fare cosa | Operazione | Amministratore | Super utente | |---|---|---| | Vedere l'elenco dei database e i dettagli | sì | sì | | Applicare le migrazioni | sì | sì | | Manutenzione del database, verifica integrità, ricostruzioni, statistiche | sì | sì | | Backup, copie remote, verifica e prova di ripristino | sì | sì | | Ripristino di un backup | avvia la richiesta | **conferma** (notifica + codice TOTP) | | **Nuova azienda**, **Collega database esistente**, **Clona** | no | sì | | **Modalità manutenzione** di un'azienda | no | sì | | **Elimina** un database aziendale | no | sì | La tabella segue SPEC §7.1. Il server verifica sempre il livello: un pulsante non disponibile non compare. ## Come si usa ### Creare una nuova azienda 1. Apri **Amministrazione → Istanza e database** e premi **Nuova azienda (database)**. 2. Indica **codice** e **ragione sociale** dell'azienda e il **motore**: PostgreSQL (consigliato) oppure SQLite. 3. Conferma. Khaemhat: - su PostgreSQL esegue `CREATE DATABASE khaemhat_` sul server indicato da `KHAEMHAT_DB_SERVER` (il ruolo deve avere il privilegio `CREATEDB`); con SQLite crea il file nella cartella dati; - applica le migrazioni dell'azienda; - carica le **tabelle di base** (paesi, comuni, codici IVA, piano dei conti…; vedi [Dati di base e di esempio](Dati-di-base-e-esempio)). 4. Completa il profilo nella nuova azienda (**Tabelle azienda → Profilo azienda**, vedi [Tabelle azienda](Tabelle-azienda)) e crea i suoi utenti. Oltre la prima azienda serve il modulo **MULTI** e la licenza deve consentire il numero di aziende (`maxCompanies`); senza, il pulsante segnala il modulo mancante. Vedi [Licenze e moduli](Licenze-e-moduli). ### Collegare un database esistente Serve per riportare nell'istanza un database già pronto (ad esempio spostato da un altro server). 1. Premi **Collega database esistente**. 2. Inserisci codice, ragione sociale e **stringa di connessione** del database. 3. Khaemhat verifica la connessione e lo stato dello schema; se mancano migrazioni le propone. La stringa di connessione viene salvata **cifrata** (AES-256-GCM con la chiave `KHAEMHAT_SECRET_KEY`). ### Clonare un'azienda (ambiente di prova) 1. Seleziona l'azienda e premi **Clona**. 2. Scegli il backup da cui partire. 3. Khaemhat ripristina il backup in un nuovo database chiamato `khaemhat__test` e lo aggiunge all'elenco come ambiente di prova (nota *clonata da…*). Il clone è un'azienda a tutti gli effetti, utile per provare procedure (chiusura d'esercizio, import) senza toccare i dati reali. Ricordati che i canali SDI e le e-mail del clone vanno controllati prima di usarlo. ### Eliminare un'azienda 1. Seleziona l'azienda e premi **Elimina** (solo super utente). 2. Khaemhat esegue **automaticamente un backup preventivo**. 3. Conferma **scrivendo il nome del database**. 4. Il database viene eliminato; il file del backup preventivo resta nel **cestino per 30 giorni**. **Attenzione:** è l'unica operazione che cancella un intero database. Prima di procedere verifica che il backup preventivo sia andato a buon fine e, se l'azienda è un archivio, valuta lo stato *Sola lettura* invece dell'eliminazione. ### Applicare le migrazioni Le migrazioni sono gli aggiornamenti dello schema del database portati da una nuova versione di Khaemhat. - Il **database di sistema** viene migrato sempre all'avvio del container. - I **database aziendali** vengono migrati all'avvio oppure dal pannello, secondo un'impostazione di sistema. - Dal pannello: seleziona il database (colonna **Schema** con *N migrazioni in attesa*) e scegli **Applica migrazioni**; durante l'operazione l'azienda è messa in **modalità manutenzione**. - Ogni database tiene la propria tabella `schema_version` (modulo, versione, nome, data, checksum). L'esito finisce nel [Log](Log), sezione *Migrazioni*. - Le migrazioni sono transazionali e idempotenti. **Il ritorno a una versione precedente non è supportato**: se un database contiene migrazioni sconosciute alla versione in esecuzione (ad esempio dopo un downgrade dell'immagine), Khaemhat si rifiuta di partire. Per tornare indietro serve il ripristino di un backup (vedi [Aggiornamento](Aggiornamento)). ### Manutenzione del database Nella scheda **Manutenzione** del dettaglio: | Operazione | Cosa fa | |---|---| | **Verifica integrità** | controlli applicativi: chiavi esterne orfane, totali documento = righe, giacenze = movimenti, partite = scadenze - incassi, registrazioni non quadrate; mostra l'esito e il numero di anomalie | | **Ricostruzioni** | ricalcolo di giacenze, partite, totali documenti, numeratori, saldi dei conti | | **Manutenzione del motore** | PostgreSQL: `VACUUM ANALYZE`, `REINDEX`; SQLite: `integrity_check` | | **Statistiche tabelle** | righe e spazio per tabella | Queste operazioni possono essere pianificate come [Attività programmate](Attivita-programmate) di tipo *verifica* o *script di manutenzione* (sempre dal catalogo interno, mai comandi liberi). ### Modalità manutenzione di un'azienda La modalità manutenzione mette un'azienda "a riposo" per operazioni delicate (migrazioni, ripristino): - gli utenti collegati vengono **disconnessi** e non possono rientrare; - le chiamate API per quell'azienda ricevono **503**; - le altre aziende dell'istanza continuano a funzionare. La attiva il super utente; Khaemhat la attiva da solo durante migrazioni dal pannello e ripristini. Il pulsante **Modalità manutenzione** è disponibile anche in [Stato sistema](Stato-sistema). ## Stati di un'azienda | Stato | Significato | |---|---| | **Attiva** | uso normale | | **Manutenzione** | accesso sospeso agli utenti, API 503 (vedi sopra) | | **Sola lettura** | i dati si consultano ma non si modificano: tipico per archivi di esercizi passati (ad esempio un archivio SQLite) | | **Disattivata** | l'azienda resta registrata ma non è utilizzabile | Un'azienda può essere marcata **predefinita**: è quella proposta alla pagina di accesso. ## Informazioni sul server PostgreSQL Il riquadro **Server PostgreSQL** (078) mostra: | Voce | Esempio nel mockup | |---|---| | Server e versione | `khaemhat-db:5432` · PostgreSQL 17 (minima richiesta 16) | | Ruolo applicativo | `khaemhat` — `CREATEDB` sì, superuser no | | Connessioni | in uso sul massimo, con il pool per database | | Spazio dati | occupazione del volume di PostgreSQL | | Spazio `/data` | occupazione della cartella dati di Khaemhat (allegati, backup, inbox) | | Versione client | `pg_dump` / `pg_restore` 17 inclusi nell'immagine | | Estensioni | estensioni presenti (es. `pg_stat_statements`) | Se la versione del server è **inferiore a 16** compare un avviso. Il client nell'immagine è la versione 17: funziona con server 16 e 17; per un server 18 serve un'immagine aggiornata. Il server può essere sullo stesso host Docker o remoto/gestito: basta la stringa di connessione. **SQLite** è pensato per demo, prova e archivi in sola lettura; per le installazioni reali si usa PostgreSQL. ## Il primo avvio Al primo avvio il container: migra il database di sistema → crea il super utente da `KHAEMHAT_SUPERUSER*` → crea la prima azienda da `KHAEMHAT_COMPANY_CODE` / `KHAEMHAT_COMPANY_NAME` → la migra → carica le tabelle di base → carica i dati di esempio se richiesto. Le variabili vengono rilette solo se la tabella corrispondente è vuota: dopo il primo avvio le aziende si gestiscono da questa pagina. Dettagli in [Primi passi](Primi-passi). ## Domande frequenti e attenzione - **Posso ripristinare il database di sistema dal pannello?** No: il database di sistema si ripristina solo da riga di comando (`scripts/restore-system.sh`) con l'istanza ferma. Vedi [Backup e ripristino](Backup-e-ripristino). - **Perché non vedo "Elimina" o "Nuova azienda"?** Sono riservati al super utente. - **Il codice dell'azienda si può cambiare?** Il codice determina il nome del database: comportamento in caso di modifica da definire in sviluppo. - **Il numero massimo di connessioni per database** si regola nelle impostazioni di sistema (pool separato per database). ## Pagine correlate [Backup e ripristino](Backup-e-ripristino) · [Licenze e moduli](Licenze-e-moduli) · [Utenti e permessi](Utenti-e-permessi) · [Stato sistema](Stato-sistema) · [Impostazioni](Impostazioni) · [Dati di base e di esempio](Dati-di-base-e-esempio) · [Aggiornamento](Aggiornamento) · [Architettura](Architettura)