Il client open-source di applicazione per i database di schema. Eseguitelo su qualsiasi macchina in grado di raggiungere il vostro PostgreSQL, effettuate l'associazione una volta e manterrà quel database allineato con i vostri arricchimenti — inizializzandosi da uno snapshot e applicando poi un feed di delta in tempo reale tramite un singolo WebSocket in uscita. La vostra stringa di connessione non lascia mai quella macchina.
Ogni istruzione è protetta da revisione, quindi un batch riconsegnato converge sulle stesse righe. Un errore SQL annulla il batch e lo interrompe: un delta problematico non viene mai saltato silenziosamente.
Il client preleva stato, non operazioni: ogni delta trasporta la riga (o le righe) corrente completa di un'entità modificata come INSERT … ON CONFLICT … DO UPDATE idempotente, così la destinazione converge anche se un batch è stato perso.
I database sync possono essere utilizzati in diversi modi — n8n, Make.com, MCP, webhook grezzi o il feed delta REST. Il sync client è la soluzione completamente automatizzata: la meno da costruire e la meno esposta a fughe di dati.
Nessuno scenario n8n, nessun cron, nessun codice di collegamento. Abbinatelo una volta e si inizializza dallo snapshot, quindi applica ogni delta man mano che arriva.
La stringa di connessione viene passata sulla riga di comando o memorizzata localmente in modalità 600 — non viene mai inviata a Entity Enricher. Il client si connette solo verso l'esterno.
Ogni delta è un upsert idempotente e protetto da revisione. Se il client si interrompe a metà batch, il batch viene riconsegnato dopo la scadenza del suo lease e la riapplicazione converge sulle stesse righe.
Un errore SQL annulla il batch e segnala il delta fallito. Il server mette in quarantena l'intero batch di quell'arricchimento e reinvia la coda senza di esso, così il client resta connesso e continua ad applicare: una singola riga difettosa non può bloccare tutto ciò che la segue, e il lavoro in quarantena resta elencato finché non se ne occupa.
Registrate prima un database su uno schema, quindi associate un client ed eseguitelo su una macchina in grado di raggiungere il vostro database.
Nella pagina Database Sync, registrare un database sullo schema che si desidera replicare e verificarne le chiavi di database. Vedere Database Sync per il modello completo. Questo passaggio dichiara il dialetto di destinazione che il client applicherà.
Incolla questo in un terminale. Lo script verifica una firma cosign prima dell'installazione.
curl -fsSL https://entityenricher.ai/install-eedatabase.sh | sh
Windows: iwr -useb https://entityenricher.ai/install-eedatabase.ps1 | iex. Oppure scarica un binario firmato dalle Release, o compila dal sorgente (Go ≥ 1.23): go build -o ee-database .
Il codice sorgente e le release firmate si trovano su TOT-Concept/ee-database (MIT).
Eseguite ee-database pair. Si apre una scheda del browser su /database/connect con un codice breve: confermatelo e scegliete quale database questo client deve sincronizzare.
ee-database pair --server https://entityenricher.ai Open this URL in your browser to confirm pairing: https://entityenricher.ai/database/connect?code=7QX-KP2 Code: 7QX-KP2 Waiting for confirmation...
Preferisce un token? Ne generi uno nella pagina Database Sync (Client di sincronizzazione → Associa un client) e lo passi direttamente: ee-database pair --server … <refresh-token>.
Alla prima esecuzione il client recupera lo snapshot .sql e lo applica, quindi si connette e trasmette i delta in streaming. --save-dsn memorizza la stringa di connessione in locale, così le esecuzioni successive non richiedono argomenti.
Ogni esecuzione verifica anche automaticamente i diritti di provisioning del login (creazione database, DDL, DML) e ne riporta il risultato nella scheda del client Sync, così un permesso mancante è visibile prima che i delta non riescano ad applicarsi. Se non è ancora pubblicato alcuno schema collegato, il client rimane connesso e attende: la prima pubblicazione avvia il feed da sola, senza bisogno di riavvio.
ee-database run --dsn "postgres://user:pass@localhost:5432/mydb" --save-dsn
«Accanto» significa adiacente in rete, non sul server del database: funziona qualsiasi macchina o container in grado di raggiungere il DSN — incluso PostgreSQL gestito in cloud (Azure, OVHcloud, AWS RDS…), che di solito impone il TLS: …/mydb?sslmode=require.
Più database sulla stessa macchina? Un sync host sposta la procedura di associazione un livello più in alto: associ la macchina una sola volta e ogni database sync che le assegna viene rivendicato, predisposto e mantenuto sincronizzato automaticamente — registrare un nuovo sync non richiede mai un'altra sessione da terminale. Richiede il client 1.5.0 o successivo, che si associa una volta per server anziché una volta per macchina: così un solo host può servire più istanze di Entity Enricher affiancate.
Nella pagina Database Sync, fare clic sul pulsante Sync hosts della barra degli strumenti e aggiungere un host con il nome della macchina. Un token di accoppiamento monouso viene mostrato una sola volta, incorporato in un comando host pair pronto da copiare e incollare, con i passaggi di configurazione guidati.
Eseguire il comando sulla macchina in grado di raggiungere il server del database. Il parametro --dsn è una stringa di connessione di base che indica il server, senza nome del database: ogni sincronizzazione assegnata ne deriva il proprio database. Come ogni DSN viene memorizzato localmente in modalità 600 e non viene mai inviato a Entity Enricher.
ee-database host pair --server https://entityenricher.ai \ --dsn "postgres://user:pass@host:5432/" <token>
L'associazione verifica automaticamente i diritti di provisioning del login (creazione database, DDL, DML) e si interrompe subito in caso di permesso mancante. Preferisci un login con privilegi minimi? Aggiungi --admin-dsn e il provisioning crea invece ciascun ruolo e database mancante tramite la connessione amministrativa: il DSN amministrativo è usato solo al momento del provisioning, mai memorizzato.
ee-database host run
L'host mantiene un WebSocket del piano di controllo e reagisce alle assegnazioni effettuate nell'interfaccia: seleziona l'host durante la registrazione di un database, oppure in un secondo momento nella scheda Panoramica del database. Ogni sincronizzazione assegnata viene reclamata, il relativo database viene creato se assente (con nome in snake_case a partire dal nome della sincronizzazione; sovrascrivibile per singola sincronizzazione tramite database_names nel config.json dell'host), quindi sincronizzato dal ciclo ordinario descritto di seguito.
Un database già associato a un altro client viene segnalato e saltato, mai preso in gestione. La revoca dell'host nella UI disconnette la macchina istantaneamente, incluse tutte le credenziali per singolo database che aveva rivendicato; le assegnazioni e i dati già sincronizzati rimangono, così un host riassociato riprende da dove si era fermato quello precedente.
I delta escono da Entity Enricher attraverso una rigorosa outbox FIFO per database. Il server concede in lease la finestra visibile per 120 secondi e la invia come un unico batch; il client applica l'intero batch in un'unica transazione e risponde ack , il che fa avanzare il cursore e attiva immediatamente la finestra successiva. Un client che si arresta a metà batch è coperto dalla scadenza del lease e da un nuovo invio lato server — nulla va perso o viene sottoposto a commit due volte.
Il bootstrap e lo stato a regime condividono lo stesso percorso di codice. Saltare il bootstrap con --skip-bootstrap se il database è già popolato.
Ogni istruzione contiene un _sync_revision in modo che una riga più vecchia non sovrascriva mai una più recente, anche fuori ordine.
Un errore SQL annulla il batch e segnala il delta fallito insieme all'intera istruzione incriminata. Il server mette in quarantena il batch di quell'arricchimento e reinvia la coda senza di esso: il client continua ad applicare il resto. Solo un errore che non indica alcun delta produce un'uscita con codice diverso da zero.
Ogni finestra applicata riporta la forma che ha scritto, tabella per tabella — così dimensionare un ri-arricchimento notturno non richiede mai un'archeologia dei log su delta già confermati e rimossi.
applying 12 delta(s) (10831 .. 10842) in one transaction applied 12 delta(s) in 84ms — 38 statement(s): mushroom 4 upserts, mushroom_common_names 12 upserts + 4 prunes, mushroom_human_uses 14 upserts + 4 prunes acked up to delta 10842
Un upsert corrisponde a una riga, quindi i conteggi sono conteggi di righe; un prune è l'unico DELETE protetto da revisione che elimina le righe figlie o di giunzione che un nuovo payload non rivendica più. Le righe figlie vengono riconciliate sul posto — mai cancellate e reinserite. Aggiunga --verbose per ottenere una riga per delta, con il relativo tipo di entità, la durata effettiva e la propria forma.
Il dialetto di destinazione è determinato dalla registrazione dello schema-database in Entity Enricher: il client applica l'SQL generato dal server. PostgreSQL è il dialetto di lancio; i renderer MySQL / MariaDB, SQL Server e Oracle sono in programma (il driver MySQL è già incluso). L'applicazione di istruzioni multiple è gestita per driver (protocollo semplice pgx, multiStatements per MySQL).
Se il database di destinazione esiste già, al login servono soltanto CONNECT sul database e USAGE + CREATE sullo schema di destinazione. (Da PostgreSQL 15, public non concede più CREATE a tutti per impostazione predefinita.)
Tutto il resto deriva dalla proprietà: è il client stesso a creare le tabelle di replica, quindi ne è il proprietario, e la proprietà implica le letture e le scritture necessarie ai delta dei dati. La proprietà non è opzionale: il feed include anche istruzioni di migrazione (ALTER TABLE …, CREATE INDEX …) che PostgreSQL riserva al proprietario della tabella e nessuna combinazione di grant può sostituirla.
Se le tabelle della replica esistono già con un proprietario diverso, il controllo preliminare dei diritti dell'esecuzione viene comunque superato — il login può creare nuove tabelle — ma il primo delta di migrazione fallisce. Le trasferisca con ALTER TABLE … OWNER TO <login> (oppure conceda al login l'appartenenza al ruolo proprietario) anziché aggiungere permessi.
Un'istruzione che il suo database rifiuta — di solito per un duplicato preesistente sotto un nuovo indice univoco — non ferma il flusso. Il batch viene annullato, il client segnala il delta fallito insieme all'intera istruzione incriminata (mai troncata) e il server mette in quarantena il batch di quell'arricchimento e reinvia la coda senza di esso. Il suo client continua ad applicare tutto ciò che segue.
Il lavoro in quarantena resta elencato nella scheda Quarantena della pagina Database Sync finché non se ne occupa: corregga la causa nel proprio database e proceda a reiniettare — operazione che riproietta l'entity dal suo stato attuale anziché rieseguire l'istruzione obsoleta — oppure lo scarti se la riga non è più rilevante.
Un bootstrap fallito è diverso: lo snapshot è un'unica transazione, quindi nulla viene applicato parzialmente, e il client lo salva nella directory del profilo dell'associazione come snapshot-failed.sql (modalità 0600, sostituito a ogni tentativo, rimosso al primo successo successivo), così può ispezionarlo o rieseguirlo con psql -f.
Il client avvia il WebSocket su :443/wss. L'host del database non accetta mai connessioni in entrata — nessuna porta da aprire, nessun ingress da configurare.
Una credenziale è associata a un singolo database sync. Un nuovo abbinamento la ruota ed espelle immediatamente la connessione live precedente.
Il refresh token valido 365 giorni (memorizzato in modalità 600) viene scambiato con token di accesso da 15 minuti che autenticano il WebSocket. La revoca dall'interfaccia disconnette un client attivo entro ~1 secondo.
Un host gestito si associa con una breve chiave eeh_… anziché con un JWT: il server ne conserva solo l'hash, non scade mai e solo la revoca dell'host nell'interfaccia la termina.
Un lock per profilo impedisce a due processi di eseguire la stessa associazione contemporaneamente: altrimenti si espellerebbero a vicenda la sessione WebSocket in un ciclo continuo.
Esegua il client con un ruolo dedicato e limitato allo schema sincronizzato, così che un token compromesso non possa toccare nient'altro — ma lasci che sia quel ruolo a creare le tabelle di replica, in modo che ne risulti proprietario. Le istruzioni di migrazione richiedono la proprietà, non i permessi.
| Comando | Che cosa fa |
|---|---|
| ee-database pair --server URL | Abbinamento tramite device-code confermato dal browser. Scegliere quale database sincronizzare. |
| ee-database pair --server URL <token> | Accoppiamento tramite un token emesso nella pagina Database Sync (compatibile con l'uso headless). |
| ee-database run --dsn DSN [--save-dsn] [--skip-bootstrap] | Eseguire il bootstrap dallo snapshot (se non saltato), quindi connettersi e applicare i delta. |
| ee-database run … --create-missing | Crea prima il database di destinazione se non esiste, utilizzando le credenziali del DSN stesso (postgres richiede CREATEDB, mysql il privilegio CREATE). |
| ee-database run … --create-missing --admin-dsn DSN | Inizializza tramite una connessione amministrativa tutto ciò a cui fa riferimento il DSN di destinazione: il ruolo/utente mancante (con la password del DSN) e il database di sua proprietà. Il DSN di destinazione non necessita quindi di alcun diritto di creazione; il DSN amministrativo non viene mai memorizzato. |
| ee-database run --all | Sincronizza tutti i database associati contemporaneamente da un unico processo (ciascuno richiede un DSN salvato). |
| ee-database run … --verbose | Registra la forma di scrittura e la durata effettiva di ogni delta, non solo il riepilogo per finestra. Accettato anche da host run. |
| ee-database host pair --server URL --dsn BASE_DSN [--admin-dsn DSN] <token> | Accoppiare questa macchina una sola volta come host di sincronizzazione gestito — il DSN di base indica il server di database (senza nome del database) e non lascia mai la macchina; il token proviene dalla finestra di dialogo Sync hosts (il pulsante Sync hosts nella barra degli strumenti della pagina Database Sync). Un accoppiamento per server: è possibile accoppiare in parallelo più server Entity Enricher. |
| ee-database host run [--server URL] | Modalità gestita: ogni database sync assegnato a questo host viene rivendicato, creato se assente e mantenuto sincronizzato automaticamente — nessun abbinamento per singolo database, su tutti i server abbinati contemporaneamente (--server limita a uno solo). Un database già abbinato a un altro client viene segnalato, mai preso in carico. |
| ee-database host status / host disconnect [--server URL] | Mostra o rimuove gli abbinamenti host di questa macchina. Per revocarli lato server, utilizzi la scheda Host di sincronizzazione. |
| ee-database status | Mostra lo stato dell'associazione, l'URL del server e i database associati. |
| ee-database disconnect | Elimina le credenziali locali di un'associazione. Revoca lato server dall'interfaccia. |
| ee-database version | Versione per la stampa. |
Le credenziali sono memorizzate in modalità 600, un profilo per ciascun database associato, in ~/.config/ee-database/profiles/ — l'associazione va effettuata una volta per database e --database NAME ne seleziona uno quando ne sono associati più di uno. Preferisce evitare del tutto l'automazione? Lo stesso feed è disponibile come semplice REST: GET /api/databases//changes e poi POST /api/databases//ack — consulti Database Sync.
Il client è rilasciato con licenza MIT e risiede in un repository pubblico, così chiunque può verificare esattamente ciò che viene eseguito sul proprio database.
Sorgente: github.com/TOT-Concept/ee-database
Release: github.com/TOT-Concept/ee-database/releases — ogni binario viene firmato con cosign prima della pubblicazione.
Verifica l'installer: curl -fsSL https://entityenricher.ai/install-eedatabase.sh | less