3
Istanza e database
Khaemhat CI edited this page 2026-11-11 14:57:26 +00:00

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

078 · Amministrazione · istanza, database di sistema e per azienda

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

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

  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_<codice> 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).
  4. 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).

  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_<codice>_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, 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