Panoramica delle connessioni ai database¶

Indice¶

1. Come funzionano le connessioni
2. Guide per tecnologia
3. Prerequisito: installare il driver ODBC sull'host digna
4. Creare una connessione al database
5. Proprietà ODBC
6. Cifrare i valori delle proprietà
7. Testare una connessione
8. Quale database vede la connessione
9. Modalità di profilazione e Work Schema
10. Usare invece un DSN
11. Risoluzione dei problemi

Come funzionano le connessioni¶

digna raggiunge ogni tecnologia sorgente tramite ODBC. Una connessione è un elenco di proprietà ODBC che inserisci come coppie chiave/valore. Quando digna apre la connessione, unisce quelle coppie in una stringa di connessione — Key=Value, separate da ;, nell'ordine in cui le hai elencate — e la consegna al gestore di driver ODBC sull'host digna.

Inserire tu stesso le proprietà è ciò che rende la configurazione senza DSN: la connessione porta con sé tutto ciò di cui il driver ha bisogno, quindi non occorre registrare alcuna origine dati ODBC (DSN) sull'host. È il modo consigliato di configurare digna, perché la definizione della connessione risiede interamente in digna e si sposta con esso.

Perché ODBC¶

Le versioni precedenti offrivano la scelta tra un driver per tecnologia e ODBC, selezionata con un interruttore Use ODBC. Dalla release 2026.06, digna si basa esclusivamente su ODBC. Un'unica interfaccia standard offre più di un insieme di driver su misura:

• Autenticazione — l'autenticazione fa parte di ODBC, quindi una connessione può usare tutto ciò che il suo driver supporta: password, token e PAT, Kerberos e Active Directory, MFA e single sign-on da browser, identità cloud, certificati client e TLS. I nuovi metodi arrivano con un aggiornamento del driver, senza attendere una release di digna.
• Driver mantenuti dai produttori dei database — il driver del produttore segue le nuove versioni del server e le correzioni di sicurezza, e puoi aggiornarlo secondo i tuoi tempi, indipendentemente da digna.
• Un solo modo di configurare tutto — ogni tecnologia è un elenco di proprietà chiave/valore, con la stessa interfaccia, la stessa cifratura dei valori sensibili e la stessa diagnostica, invece di un insieme di campi diverso per ogni sorgente.
• Regolazione e portata — le opzioni a livello di driver come timeout, impostazioni TLS, proxy e dimensioni di fetch sono disponibili per ogni sorgente, e qualsiasi tecnologia con un driver ODBC conforme può essere collegata, comprese quelle per cui digna non pubblica una guida dedicata.

Guide per tecnologia¶

I nomi delle proprietà variano da driver a driver, e ogni tecnologia ha uno o due dettagli che le altre non hanno. Le guide qui sotto coprono quella parte; questa pagina copre il lato digna, che è lo stesso per tutte.

Prerequisito: installare il driver ODBC sull'host digna¶

digna apre le connessioni sorgente dal server che esegue il backend digna, non dal browser. Il driver ODBC deve quindi essere installato su quella macchina, e il suo nome registrato presso il gestore di driver locale.

odbcinst -q -d

odbcinst -q -d

Invece di un nome registrato, tutti i gestori di driver comuni accettano anche il percorso completo alla libreria del driver, per esempio Driver=/opt/simba/spark/lib/64/libsparkodbc_sb64.so. È utile quando il driver è installato ma non registrato.

Creare una connessione al database¶

Apri l'Admin Panel, vai alla scheda Database Connections e fai clic su Add DB Connection. La schermata chiede cinque cose:

Una connessione viene amministrata centralmente e poi assegnata a uno o più progetti, così la stessa connessione può servire più progetti.

Proprietà ODBC¶

Fai clic su Add Property per ogni proprietà e compila Key, Value e, per i segreti, la casella Encrypted. Ogni guida di tecnologia elenca un insieme di esempio per quella tecnologia, che adatti alla tua versione del driver e al tuo server — vedi la nota qui sopra.

Qualunque sia il driver, un insieme di proprietà copre le stesse quattro cose:

• Driver — il nome del driver registrato, come descritto qui sopra.
• L'indirizzo del server — la chiave varia da driver a driver: SERVER, HOST, DBCNAME, Server oppure, per Oracle, il descrittore di connessione DBQ.
• Le credenziali — di solito UID e PWD; Snowflake usa UID più un token, e Databricks l'utente letterale token più il token di accesso personale in PWD.
• Il database o il catalogo in cui lavorare, quando la tecnologia ne ha uno — vedi Quale database vede la connessione.

Tutto ciò che il driver documenta può essere aggiunto allo stesso modo: pool di connessioni, timeout dei socket, impostazioni Kerberos, impostazioni proxy. digna non interpreta le proprietà; si limita a inoltrarle.

Cifrare i valori delle proprietà¶

Spunta Encrypted per ogni proprietà che contiene un segreto: PWD, token, un client secret. Il valore viene allora cifrato prima di essere memorizzato nel repository di digna, mascherato nella schermata e decifrato solo quando la stringa di connessione viene assemblata.

Le proprietà che non sono segrete — nome del driver, host, porta, database — è meglio lasciarle non cifrate, così restano leggibili per chi manterrà la connessione in seguito.

Testare una connessione¶

Fai clic su Test nella finestra Add DB Connection prima di salvare. Il test usa i valori attualmente presenti nel modulo ed esegue una connessione reale, quindi segnala esattamente ciò che incontrerebbe un'ispezione: un nome di driver errato, una password rifiutata, un host irraggiungibile. Non viene memorizzato nulla: la connessione di test viene annullata sia in caso di successo sia in caso di errore.

Per una connessione già esistente, passa il mouse sulla sua riga nella scheda Database Connections e fai clic sull'icona della spina per ritestarla. È il modo più rapido per verificare se una sorgente è raggiungibile dopo una rotazione di password o una modifica al firewall.

Quale database vede la connessione¶

Quando aggiungi una sorgente dati, digna offre i cataloghi, gli schemi e le tabelle che la connessione può raggiungere. Fin dove arrivi dipende dalla tecnologia:

Modalità di profilazione e Work Schema¶

La modalità di profilazione determina come digna elabora i dati e calcola le metriche:

• Standard: le metriche sono calcolate direttamente sulle tabelle sorgente, senza copiare i dati.
• Permanent: i dati del giorno ispezionato vengono copiati in una tabella permanente e le metriche sono calcolate sui dati copiati.
• Session: i dati vengono copiati in una tabella di sessione o temporanea e le metriche sono calcolate su quei dati temporanei.

La modalità decide cosa deve essere consentito all'utente della connessione:

Standard si limita a leggere, il che ne fa la modalità da scegliere quando a digna è concesso un accesso in sola lettura. Work Schema viene letto solo per Permanent, ma vale comunque la pena compilarlo perché la connessione continui a funzionare se la modalità viene cambiata in seguito.

Usare invece un DSN¶

Un DSN funziona ancora: DSN è semplicemente un'altra proprietà:

Key: DSN        Value: my_registered_dsn
Key: UID        Value: <user>
Key: PWD        Value: <password>        [Encrypted]

Il DSN deve essere registrato sull'host digna, per lo stesso account utente che esegue il backend di digna, e come System DSN quando digna viene eseguito come servizio. Tutto ciò che è configurato nel DSN può essere sovrascritto aggiungendolo anche come proprietà.

La modalità senza DSN è l'impostazione predefinita documentata perché evita quello stato lato host: la connessione è descritta interamente in digna, e un nuovo host digna ha bisogno del driver installato, ma di nulla di configurato.

Risoluzione dei problemi¶

Nome dell'origine dati non trovato / nessun driver predefinito specificato¶

Sintomi: - Il pulsante Test segnala un errore che menziona data source name not found, anche se la configurazione è senza DSN

Cause e soluzioni: 1. Il valore di Driver non corrisponde ad alcun nome di driver registrato: confrontalo con la scheda Drivers di Amministrazione origine dati ODBC (64 bit), oppure con odbcinst -q -d 2. Il driver è installato sulla tua workstation ma non sull'host digna 3. Il driver è a 32 bit mentre digna è a 64 bit: installa il driver a 64 bit 4. La proprietà Driver manca del tutto, e non è stato indicato nemmeno un DSN 5. Su Linux e macOS il driver è installato ma non registrato: indica invece il percorso completo alla libreria del driver, oppure registralo in odbcinst.ini

Il test di connessione va in timeout¶

Sintomi: - Test si blocca e poi fallisce dopo circa mezzo minuto

Cause e soluzioni: 1. Host o porta irraggiungibili dall'host digna: controlla il firewall e, per le sorgenti cloud, l'elenco degli indirizzi IP consentiti 2. Il nome host è corretto, ma la porta appartiene a un altro servizio 3. La sorgente ha bisogno di più dei 30 secondi predefiniti per accettare una connessione: alza DIGNA_SOURCE_LOGIN_TIMEOUT_SEC nella sezione [base] di config.toml (0 attende indefinitamente) e riavvia il backend 4. Un endpoint serverless si sta riattivando dall'inattività: riprova e, se accade di frequente, alza il timeout di login come sopra

L'autenticazione fallisce anche se le credenziali sono corrette¶

Sintomi: - Il driver segnala credenziali non valide, ma lo stesso utente funziona in un altro client SQL

Cause e soluzioni: 1. La password contiene ;: racchiudi il valore tra graffe: {p@ss;word} 2. Uno spazio finale è stato copiato dentro il valore 3. Il driver si aspetta un meccanismo di autenticazione specifico, per esempio AuthMech per i driver Hive e Databricks, oppure authenticator per Snowflake 4. Il valore è stato memorizzato cifrato e poi modificato: i valori cifrati non possono essere riletti, quindi reinserisci il segreto per intero 5. Un token è scaduto: i token di accesso personale e quelli di accesso programmatico vengono emessi con una data di scadenza

La schermata della sorgente dati non offre il database o lo schema previsto¶

Sintomi: - Mancano cataloghi, schemi o tabelle quando si aggiunge una sorgente dati

Cause e soluzioni: 1. La connessione punta a un altro database — vedi Quale database vede la connessione 2. All'utente della connessione mancano i diritti di lettura sullo schema o sul dizionario dati 3. Technology non corrisponde alla sorgente, quindi digna interroga il dizionario dati sbagliato 4. Per Snowflake non è assegnato alcun warehouse predefinito all'utente e non è stata indicata alcuna proprietà Warehouse, quindi le query sui metadati non possono essere eseguite

La profilazione fallisce mentre il test di connessione riesce¶

Sintomi: - Test passa, ma un'ispezione fallisce quando vengono create le tabelle di lavoro

Cause e soluzioni: 1. È selezionata la profilazione Permanent e l'utente della connessione non può creare tabelle in Work Schema: concedi i diritti, oppure passa a Session o Standard 2. Work Schema è vuoto o nomina uno schema inesistente, mentre è selezionata la profilazione Permanent 3. È selezionata la profilazione Session e l'utente della connessione non può creare tabelle temporanee 4. Una query di profilazione di lunga durata raggiunge il timeout delle query: alza DIGNA_SOURCE_QUERY_TIMEOUT_SEC nella sezione [base] di config.toml (3600 secondi di default, 0 disattiva il timeout)

Buone pratiche¶

DA FARE:

• Installare e registrare il driver sull'host digna prima di configurare la connessione
• Spuntare Encrypted per ogni password e ogni token
• Fare clic su Test prima di salvare, e ritestare dopo una rotazione di password
• Nominare le connessioni in base a sorgente e ambiente, per esempio sales_dwh_prod
• Dare a digna un utente di database dedicato, in sola lettura dove basta la profilazione Standard
• Mantenere una connessione per database sorgente, e aggiungerne una seconda anziché modificare la prima

DA NON FARE:

• Memorizzare segreti non cifrati, o condividere un utente di database tra digna e altri strumenti
• Usare un driver a 32 bit con un'installazione di digna a 64 bit
• Affidarsi a un DSN utente quando digna viene eseguito come servizio: non sarà visibile
• Inserire un valore che contiene ; in una proprietà senza graffe
• Puntare Work Schema su uno schema che contiene dati sorgente

Supporto¶

Hai bisogno di aiuto con una connessione al database?

• E-mail: support@digna.ai
• Documentazione: https://docs.digna.ai
• Sito web: https://www.digna.ai

Release: 2026.06
© 2026 digna GmbH — www.digna.ai