How Connections Work

A connection defines how Qualytics authenticates and communicates with your data infrastructure. It stores the credentials, host information, and configuration needed to reach a specific system - whether it is a relational database, a cloud data warehouse, or a file storage bucket.

Connection Types

Qualytics supports three connection types, each designed for a different class of data source:

Connection vs. Datastore

A connection and a datastore serve different roles:

• A connection holds the credentials and endpoint information (host, port, username, password, access keys) needed to authenticate with a system.
• A datastore represents a specific data scope within that system (a database + schema for JDBC, a root path for DFS).

This separation means one connection can be shared across multiple datastores. For example, a single Snowflake connection (host, role, warehouse, credentials) can serve datastores for production.public, production.sales, and production.finance - each pointing to a different schema.

Connection Lifecycle

Creating a Connection

When you add a source datastore with a new connection, the connection is created alongside the datastore in a single step:

1. You provide the connection credentials (host, credentials, parameters).
2. You configure the datastore-specific properties (database, schema, or root path).
3. You click Test Connection to validate access before saving the connection and datastore.
4. On success, clicking Finish creates both the connection and the datastore.

Reusing a Connection

When you add a source datastore with an existing connection, you skip the credential setup:

1. You select a previously created connection from the dropdown.
2. The connection properties are displayed as read-only - they cannot be modified from the datastore form.
3. You only configure the datastore-specific properties (database, schema, or root path).
4. The test connection verifies that the existing credentials can reach the new datastore scope.

Testing a Connection

The Test Connection step checks that Qualytics can authenticate and reach the selected database, schema, or storage path. For an enrichment destination, it can also create and remove a temporary object to verify write access. The test reports success or an error describing the failure.

Testing does not save the connection or datastore configuration. Click Finish to save it.

Editing a Connection

Connection properties can be updated through the Manage Connections page in Settings. When credentials change, Qualytics verifies access again before saving them.

Deleting a Connection

A connection can only be deleted if it has no datastores associated with it. If any datastores still use the connection, the deletion will fail with a 409 Conflict error - you must delete or reassign those datastores first.

Advanced Options

Some connectors offer an Advanced section in the connection form, collapsed because the values it holds are rarely changed. Expand it to review or set these options. They belong to the connection, so they apply to every datastore that shares it.

Max Parallelization

Max Parallelization limits how many queries Qualytics runs at the same time against a datastore reached through this connection. It is available on every JDBC connector.

Leave the field empty for no explicit limit, which is the default. Qualytics then chooses how much to run in parallel based on the size of your deployment. Enter a whole number between 1 and 100 to hold it lower, for a database that cannot handle the default amount of parallel reads without slowing down other work on it.

Lowering Max Parallelization means Profile and Scan operations read less data at a time, so they take longer to finish. Raise it again once the source database can handle more.

Network Requirements

Qualytics requires direct network access from your deployment to your data infrastructure. Consider the following:

• Firewall rules: the addresses your deployment connects from must be allowed to reach your database or storage endpoint.
• Private endpoints: for databases in private VPCs, configure VPC peering, private endpoints, or a VPN tunnel between your deployment and your network.
• IP allowlisting: if your database requires IP allowlisting, add the addresses your deployment connects from to the allowlist.
• Port access: ensure the required port is open (for example, 5432 for PostgreSQL, 443 for Snowflake, BigQuery, or S3).

Finding the addresses to allow

You do not need to ask anyone for the addresses. The datastore form shows them for you: once you pick a connector, an information banner below the form lists the addresses your datastore connections originate from, grouped as Public addresses and Private addresses. Each group is either configured for your deployment or, when nothing is configured, estimated from it; an estimated group is marked as such and may not be complete (see the note below). Each address has a copy button, so you can paste it straight into your security group, firewall rule, or network policy.

Allow only the group that matches how your deployment reaches the source. A source you connect to over the internet needs the public addresses; a source inside the same private network needs the private ones.

The same banner appears on the Add Datastore form, on the enrichment destination form, and in the Enrichment Destination step when you create a new destination while adding a source datastore. It does not appear in the Enrichment Destination dialog opened from an existing datastore, so copy the addresses from one of those forms when you need them there.

Secrets Management

Qualytics supports integration with external secrets managers to avoid storing credentials directly. Instead of entering a password, you configure a secrets manager integration and reference secrets using the ${key} syntax in any connection property.

How It Works

1. Authentication: Qualytics sends a POST request to your secrets manager's login URL with the provided credentials payload.
2. Token extraction: The authentication token is extracted from the response using a JSONPath expression.
3. Secret retrieval: A GET request is sent to the secret URL with the token in the configured header.
4. Variable substitution: The retrieved secrets are used to replace ${key} references in connection properties at runtime.

Configuration Fields

Authentication Methods

Different connectors support different authentication methods. Basic (username and password) is the default method available on all JDBC connectors. The other methods are additional options for specific connectors:

Credential Security

Qualytics encrypts stored connection credentials. Grant each connection only the access its datastores need: read access for source data, and the connector's documented write permissions for an enrichment datastore. Use secrets management when your organization manages credentials outside Qualytics.