Data Source Connectivity: Secure, Deterministic Access

Colrows connects to your data stores with a focus on governance, not just accessibility. We treat every data source as a trusted partner in your deterministic semantic stack, ensuring security at the compiler level.

The connectivity landscape

Most tools treat data sources as open fields to query at will. Colrows establishes connections that enforce governance from the start. The connection to your warehouse is the first point of truth in your deterministic pipeline.

Supported datasources

Colrows connects to warehouses, lakehouses, and operational databases over JDBC. The semantic graph is warehouse agnostic. One definition. Many backends. Dialect-perfect SQL at the edge. The Product list in Add Datasource offers these engines:

Each datasource authenticates with one of three methods: Username / Password, Private Key (upload a JSON key file, such as a service account key), or Custom (key-value credential properties for the driver).

How to connect

Only organization administrators can add, test, edit, or delete a datasource.

1. Open Administration → Connections → Datasources and select + Datasource

   The Add Datasource dialog has five steps: General, Connection, SSL, SSH, and Discovery Settings.

2. General

   Enter a Name (up to 50 characters), pick the Product and Cloud Platform (AWS, GCP, Azure, or Other), set Restricted Access (see below), and add an optional Description. The product can't be changed after the datasource is created.

3. Connection

   Enter the JDBC Connection String and the Database. For Trino, the field is Trino catalog and is required; a catalog in the URL is optional but must match it. Choose the Authentication method and enter its credentials. You can also set the query timeout (seconds), fetch size, connection timeout (milliseconds), and extra JDBC properties.

   # PostgreSQL
   Connection String  = jdbc:postgresql://db.acme.internal:5432/analytics
   Database           = analytics
   Authentication     = Username / Password

   Keep credentials out of the connection string. Colrows rejects a URL that contains a password, token, or secret parameter, or a user@host or Oracle user/password@ form, with Datasource URLs must not contain credentials.

4. SSL and SSH (optional)

   Turn on Use SSL or Use SSH if the database needs them. The network section below lists the fields.

5. Test and add

   Select Test Connection to check the settings, then Add Datasource. Discovery starts with conservative database limits, and the Discovery Settings step opens so you can review them.

6. Prepare the database

   In Consensus → Pipelines, pick the datasource and open Update Settings. One saved plan drives the first setup, manual updates, and scheduled updates. It reads metadata for the schemas and tables in the datasource's data scope, runs the enrichment you select, and then updates AI search:

   • Profile Columns and Generate Categories - read eligible column values. Off by default.
   • Generate Missing Descriptions - fill missing table and column descriptions and keep existing text. On by default.
   • Discover Relationships with AI - identify relationships and send uncertain results for review. Off by default.
   • Use Query History - collect query history and identify observed joins. Needs query history access for the connection. Off by default.

   Select Save and Prepare Database to run it, or Add Update Schedule to run the same plan on a schedule. See SaaS Architecture to understand how this connection feeds the compiler.

Restricted access

The Restricted Access switch (restrictedAccess in the API) decides whether Colrows applies data access and masking policies to queries on this datasource. When it is on, every query is checked against the user's policies before it runs. When it is off, Colrows skips that evaluation and queries run with the datasource's own database permissions. It is off by default, both in the Add Datasource dialog and when restrictedAccess is left out of a create request, so turn it on for any datasource that holds governed data. See Data Access Control.

Credential handling

• Colrows stores passwords, private keys, custom credential values, JDBC property values, and the SSH password and passphrase separately from the datasource record. Reading a datasource returns the authentication type, the username, and the names of custom credential properties, never the secret values.
• When you edit a datasource, leave a secret field blank to keep the stored value. This applies to the password, private key, and custom credential values, the SSH password, passphrase, and private key, and the JDBC properties.
• The datasource JSON includes databaseUpdatePlan, the saved update plan, with the boolean fields profiles, descriptions, relationships, and queryHistory.

Driver setup

For self-hosted deployments, JDBC drivers live in the drivers directory under the Colrows home, which is /opt/colrows/drivers in the container image. Contact support for an engine that is not in the list.

Network options

• Direct connection - Colrows reaches the database at the host in the connection string. Works for any database reachable from Colrows.
• SSH tunnel - turn on Use SSH and enter the bastion's hostname, port, and username, with either a password or a private key (and its passphrase, if it has one). Useful when the database has no public endpoint.
• SSL - turn on Use SSL and supply the server root certificate, and optionally a client key and client certificate. Certificates are optional for MySQL, PostgreSQL, TimescaleDB, and Trino.

For private connectivity beyond these options, contact us.

Cross-source semantics

Each query compiles to dialect-perfect SQL for one datasource and runs there. Colrows does not run federated queries that join tables across datasources. Connect each warehouse or database as its own datasource.