Database Connections Overview¶

Table of Contents¶

1. How Connections Work
2. Technology Guides
3. Prerequisite: Install the ODBC Driver on the digna Host
4. Create a Database Connection
5. ODBC Properties
6. Encrypting Property Values
7. Testing a Connection
8. Which Database the Connection Sees
9. Profiling Mode and Work Schema
10. Using a DSN Instead
11. Troubleshooting

How Connections Work¶

digna reaches every source technology over ODBC. A connection is a list of ODBC properties that you enter as key/value pairs. When digna opens the connection, it joins those pairs into a connection string — Key=Value, separated by ;, in the order you listed them — and hands it to the ODBC driver manager on the digna host.

Entering the properties yourself is what makes the setup DSN-less: the connection carries everything the driver needs, so no ODBC data source (DSN) has to be registered on the host. This is the recommended way to configure digna, because the connection definition lives entirely in digna and moves with it.

Technology Guides¶

The property names differ per driver, and each technology has one or two details that the others do not have. The guides below cover that part; this page covers the digna side, which is the same for all of them.

Prerequisite: Install the ODBC Driver on the digna Host¶

digna opens source connections from the server that runs the digna backend, not from the browser. The ODBC driver must therefore be installed on that machine, and its name must be registered with the local driver manager.

odbcinst -q -d

odbcinst -q -d

Instead of a registered name, all common driver managers also accept the full path to the driver library, for example Driver=/opt/simba/spark/lib/64/libsparkodbc_sb64.so. That is useful when the driver is installed but not registered.

Create a Database Connection¶

Open the Admin Panel, go to the Database Connections tab and click Add DB Connection. The screen asks for five things:

A connection is administered centrally and then assigned to one or more projects, so the same connection can serve several projects.

ODBC Properties¶

Click Add Property for every property, and fill in Key, Value and, for secrets, the Encrypted checkbox. Each technology guide lists the properties that technology needs.

What every property set has in common:

• Driver — the registered driver name, as described above.
• The address of the server — the key differs per driver: SERVER, HOST, DBCNAME, Server, or, for Oracle, the DBQ connect descriptor.
• Credentials — usually UID and PWD; Snowflake uses UID plus a token, and Databricks uses the literal user token plus the personal access token in PWD.
• The database or catalog to work in, where the technology has one — see Which Database the Connection Sees.

Anything else the driver documents can be added the same way — connection pooling, socket timeouts, Kerberos settings, proxy settings. digna does not interpret the properties; it only passes them on.

Encrypting Property Values¶

Tick Encrypted for every property that holds a secret — PWD, token, a client secret. The value is then encrypted before it is stored in the digna repository, masked in the screen, and decrypted only when the connection string is assembled.

Properties that are not secret — the driver name, host, port, database — are best left unencrypted, so they stay readable for whoever maintains the connection later.

Testing a Connection¶

Click Test in the Add DB Connection dialog before saving. The test uses the values currently in the form and performs a real connect, so it reports exactly what an inspection would hit — a wrong driver name, a rejected password, an unreachable host. Nothing is stored: the test connection is rolled back whether it succeeds or fails.

For a connection that already exists, hover its row in the Database Connections tab and click the plug icon to re-test it. That is the quickest way to check whether a source is reachable after a password rotation or a firewall change.

Which Database the Connection Sees¶

When you add a data source, digna offers the catalogs, schemas and tables that the connection can reach. How far that reaches depends on the technology:

Profiling Mode and Work Schema¶

The profiling mode determines how digna processes data and calculates metrics:

• Standard: Metrics are calculated directly on the source tables without copying the data.
• Permanent: Data for the inspected day is copied into a permanent table, and metrics are calculated on the copied data.
• Session: Data is copied into a session or temporary table, and metrics are calculated on this temporary data.

The mode decides what the connection user must be allowed to do:

Standard reads only, which makes it the mode to choose when digna is granted read-only access. Work Schema is only read for Permanent, but it is worth filling in anyway so the connection keeps working if the mode is changed later.

Using a DSN Instead¶

A DSN still works — DSN is just another property:

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

The DSN must be registered on the digna host, for the same user account that runs the digna backend, and as a System DSN when digna runs as a service. Everything that is configured in the DSN can be overridden by adding it as a property as well.

DSN-less is the documented default because it avoids that host-side state: the connection is fully described in digna, and a new digna host needs the driver installed but nothing configured.

Troubleshooting¶

Data source name not found / no default driver specified¶

Symptoms: - The Test button reports an error mentioning data source name not found, even though the setup is DSN-less

Causes & Solutions: 1. The Driver value does not match a registered driver name — compare it with the Drivers tab of ODBC Data Source Administrator (64-bit), or with odbcinst -q -d 2. The driver is installed on your workstation but not on the digna host 3. The driver is 32-bit while digna is 64-bit — install the 64-bit driver 4. The Driver property is missing altogether, and no DSN was given either 5. On Linux and macOS, the driver is installed but not registered — give the full path to the driver library instead, or register it in odbcinst.ini

The connection test times out¶

Symptoms: - Test hangs and then fails after roughly half a minute

Causes & Solutions: 1. Host or port unreachable from the digna host — check the firewall and, for cloud sources, the IP allow list 2. The host name is right but the port belongs to a different service 3. The source needs longer than the default 30 seconds to accept a connection — raise DIGNA_SOURCE_LOGIN_TIMEOUT_SEC in the [base] section of config.toml (0 waits indefinitely) and restart the backend 4. A serverless endpoint is resuming from idle — retry, and if it happens routinely, raise the login timeout as above

Authentication fails although the credentials are correct¶

Symptoms: - The driver reports invalid credentials, but the same user works in another SQL client

Causes & Solutions: 1. The password contains ; — wrap the value in braces: {p@ss;word} 2. A trailing space was copied into the value 3. The driver expects a specific authentication mechanism — for example AuthMech for the Hive and Databricks drivers, or authenticator for Snowflake 4. The value was stored encrypted and then edited — encrypted values cannot be read back, so re-enter the secret in full 5. A token has expired — personal access tokens and programmatic access tokens are issued with an expiry date

The data source screen does not offer the expected database or schema¶

Symptoms: - Catalogs, schemas or tables are missing when a data source is added

Causes & Solutions: 1. The connection points at a different database — see Which Database the Connection Sees 2. The connection user lacks read rights on the schema or on the data dictionary 3. Technology does not match the source, so digna queries the wrong data dictionary 4. For Snowflake, no default warehouse is assigned to the user and no Warehouse property was given, so metadata queries cannot run

Profiling fails while the connection test succeeds¶

Symptoms: - Test passes, but an inspection fails when work tables are created

Causes & Solutions: 1. Permanent profiling is selected and the connection user cannot create tables in Work Schema — grant the rights, or switch to Session or Standard 2. Work Schema is empty or names a schema that does not exist, while Permanent profiling is selected 3. Session profiling is selected and the connection user may not create temporary tables 4. A long-running profiling query hits the query timeout — raise DIGNA_SOURCE_QUERY_TIMEOUT_SEC in the [base] section of config.toml (default 3600 seconds, 0 disables the timeout)

Best Practices¶

DO:

• Install and register the driver on the digna host before configuring the connection
• Tick Encrypted for every password and token
• Click Test before saving, and re-test after a password rotation
• Name connections after the source and environment, for example sales_dwh_prod
• Give digna a dedicated database user, read-only where Standard profiling is enough
• Keep one connection per source database, and add a second one rather than switching the first

DON'T:

• Store secrets unencrypted, or share one database user between digna and other tools
• Use a 32-bit driver with a 64-bit digna installation
• Rely on a User DSN when digna runs as a service — it will not be visible
• Put a value containing ; into a property without braces
• Point Work Schema at a schema that holds source data

Support¶

Need help with a database connection?

• Email: support@digna.ai
• Documentation: https://docs.digna.ai
• Website: https://www.digna.ai

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