Table of Contents
- Istanza e database
- A cosa serve
- Dove si trova
- Schermate
- Chi può fare cosa
- Come si usa
- Creare una nuova azienda
- Collegare un database esistente
- Clonare un'azienda (ambiente di prova)
- Eliminare un'azienda
- Applicare le migrazioni
- Manutenzione del database
- Modalità manutenzione di un'azienda
- Stati di un'azienda
- Informazioni sul server PostgreSQL
- Il primo avvio
- Domande frequenti e attenzione
- Pagine correlate
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_<codice> (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
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)
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.
- 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).
- 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
- Apri Amministrazione → Istanza e database e premi Nuova azienda (database).
- Indica codice e ragione sociale dell'azienda e il motore: PostgreSQL (consigliato) oppure SQLite.
- Conferma. Khaemhat:
- su PostgreSQL esegue
CREATE DATABASE khaemhat_<codice>sul server indicato daKHAEMHAT_DB_SERVER(il ruolo deve avere il privilegioCREATEDB); 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).
- su PostgreSQL esegue
- Completa il profilo nella nuova azienda (Tabelle azienda → Profilo azienda, vedi 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.
Collegare un database esistente
Serve per riportare nell'istanza un database già pronto (ad esempio spostato da un altro server).
- Premi Collega database esistente.
- Inserisci codice, ragione sociale e stringa di connessione del database.
- 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)
- Seleziona l'azienda e premi Clona.
- Scegli il backup da cui partire.
- Khaemhat ripristina il backup in un nuovo database chiamato
khaemhat_<codice>_teste 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
- Seleziona l'azienda e premi Elimina (solo super utente).
- Khaemhat esegue automaticamente un backup preventivo.
- Conferma scrivendo il nome del database.
- 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, 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).
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 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.
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.
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. - 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 · Licenze e moduli · Utenti e permessi · Stato sistema · Impostazioni · Dati di base e di esempio · Aggiornamento · Architettura
Guida
Installazione
Interfaccia
Anagrafiche
Documenti
Contabilità e fisco
- Contabilità
- Chiusura e bilancio
- IVA
- Cespiti
- Intrastat
- Dichiarazioni d'intento
- Scadenzario
- Fatturazione elettronica
- Fiscalità italiana
CRM e servizi
Amministrazione
- Istanza e database
- Licenze e moduli
- Utenti e permessi
- Attività programmate
- Log
- Impostazioni
- Stato sistema
- Chiavi API e MCP
- Import/Export
- Dati di base e di esempio
Riferimento
Sviluppo
Khaemhat · ERP + CRM per PMI italiane · Repository · Issue · Roadmap · Sorgente della wiki: docs/wiki/ (le modifiche si fanno lì, non dall'editor del wiki)