Connection Management — User Guide

DATTA's connection registry is the central point for linking the platform to any external data source — relational databases, warehouses, query engines, Neo4j, OpenSearch, Kafka, Pulsar, Cassandra, MongoDB, BigQuery, files and dozens more. You register the source once, in a few clicks, and the platform catalogs its content automatically the moment you connect — with no duplicates and with credentials always protected.

This guide covers the end-user and administrator experience. For architecture and deployment, see data access and the connections runbook.

Where you create connections

The dedicated screen is Sistema›Conexões — that is where you list, create, edit and revoke connections. But you never have to leave your workflow: the same registration dialog, with the same behavior, opens from:

• DATTABI — Preparar Dados, while building a dataset for a dashboard.
• The Extract pipeline designer, in the source component.
• Extract Quick, in the source component — here the + Nova conexão button takes you to Sistema›Conexões, by design.
• The Data Catalog, when creating a dataset.

No part of the platform keeps connections in its own database: the registry is single and registration is idempotent — registering the same configuration twice returns the same connection, never a duplicate. Creating a connection without cataloging it is an anti-pattern on the platform (Project Guidelines §7).

What the connections screen shows

The list has the columns Nome, Tipo, Host, Visibilidade, Status, Última catalogação and Ações.

Step by step: registering a connection

1. Open Sistema›Conexões and click + Nova conexão.
2. Pick the source Tipo from the list (the categories are detailed below).
3. Fill in host, port, database, user and password.
4. Set the Visibilidade: PRIVATE (only you), WORKSPACE (workspace users, when passed explicitly) or PUBLIC (every user of the instance — requires an administrator profile).
5. Adjust the type-specific options (TLS, SSL, SASL mechanism, etc.).
6. On submit, the platform:
   • Tests before saving and shows the test result right away — you only persist what you already know works.
   • Deduplicates: if a connection with the same type+host+port+database+user already exists, it is reused and only your credential is bound to it.
   • Triggers automatic cataloging in the background (see the next section).
   • Closes the dialog and hands the ready-to-use connection back to the flow you came from.

Types offered in the selector:

• Relational: PostgreSQL, MySQL, MariaDB, SQLite, H2, CockroachDB, TimescaleDB, MSSQL, Oracle, IBM Db2, SAP HANA, Firebird, Vertica, Exasol.
• Warehouses: Snowflake, Redshift, Azure Synapse, Databricks, BigQuery.
• Query engines: Trino, PrestoDB, Spark Thrift, Hive, Impala, Phoenix, Drill, Druid, Pinot.
• Columnar / analytical: DuckDB, ClickHouse, Apache Doris, StarRocks.
• Time-series: QuestDB, IoTDB, InfluxDB 3.x (Flight SQL).
• Native: Neo4j, OpenSearch, Elasticsearch, Cassandra, MongoDB, Kafka, Pulsar.

Automatic cataloging on connect (ACOC)

Every connection creation automatically enqueues a cataloging scan. There is no opt-out for regular users.

What the scan does

• Introspection: schemas, tables, columns, indexes, labels, collections, topics — depending on the source type.
• Quality metrics: freshness (latest MAX(timestamp)), completeness (% nulls), distinct-value counts per column and personal data detection (CPF, CNPJ, e-mail, card and phone — the pattern list is configurable).
• Preview sample: 100 rows kept in the platform cache.
• Publication to the catalog: every discovered dataset is registered (or updated) in the Knowledge Catalog.
• Audit trail: CONNECTION.AUTO_CATALOG_STARTED, ..._COMPLETED and ..._FAILED.
• Real-time progress: the screen follows the scan as it advances.

The scan blocks nothing

The connection is usable immediately after registration returns. The scan runs in the background and datasets show up in the dataset browser as they are cataloged.

Protection limits (administrator)

Disabling automatic cataloging for a connection requires a justification, which is recorded in the audit trail (CONNECTION.AUTO_CATALOG_DISABLED).

Manual re-cataloging

Administrators can force a new scan at any time — useful to capture structural changes (DDL) at the source. The action is restricted to the administrator profile.

Visibility: who sees which connection

Cataloged datasets inherit the connection's visibility — and administrators can restrict further, dataset by dataset.

Credentials: individual and protected

• Credentials are never stored in plain text: the platform's credential vault uses envelope encryption (a master key kept as an installation secret, with one data key per binding).
• Everyone has their own: two people can use the same physical connection with different credentials, each with their own access level at the source.
• Rotation: administrators can force a global rotation — users are notified and the password is asked again on their next operation. Rotating your credential changes only your binding, affecting nobody else.

Fingerprint and deduplication

fingerprint = sha256(type + "|" + host + "|" + port + "|" + database + "|" + user)

Note: the credential does not go into the fingerprint. That is what guarantees that, if Ana and Bob register postgres://analytics.local:5432/warehouse with different users, there is one connection in the catalog and two credential bindings.

Edit, revoke and rotate

• Edit: changes host, port or settings. If the change points to a different physical source, it produces a new fingerprint — therefore a new connection — and the old one is marked deprecated.
• Revoke: marks the connection as REVOKED. Every DATTAX script that references it starts failing with an explanatory message in Portuguese, never a cryptic error.
• Rotate credential: changes only the current user's credential binding.

Every mutation produces an audit event: CONNECTION.CREATE, CONNECTION.UPDATE, CONNECTION.REVOKE and CONNECTION.ROTATE_CREDENTIAL.

Supported source types (summary)

The full driver list, with installation and governance, is in the JDBC drivers guide.

Troubleshooting

"Não foi possível conectar" when creating

• Confirm the host is reachable from the platform (network, tunnel, firewall) and that port, database and credential are correct.
• TLS handshake error: uncheck the TLS option or ask an administrator to trust the source's certificate.
• For security, the platform keeps an allowed-hosts list (SSRF protection); administrators can extend it in the installation configuration.

The scan hangs or fails

• The screen shows the state of the running scan for each connection.
• Administrators can re-enqueue the scan from the same screen.
• If the protection limits described above were hit, the scan is deferred and resumed automatically.

Expired credential

• The dialog shows: "Sua credencial expirou. Informe novamente a senha para continuar."
• Only your credential binding is affected; everyone else keeps working.

Orphaned connection (no bound user)

• Happens when the last user with a binding is deactivated.
• Administrators can list orphaned connections and, from there, revoke or reassign one to another user from the connections screen.

Automation

Everything the screen does — create, create idempotently, list, read the detail, test, re-catalog, follow the progress and revoke connections, plus reassigning credential bindings — is also available through the platform API. Paths, parameters and permissions are in the API reference.

References

• JDBC drivers.
• Data access.
• Operational connections runbook.