Connect a database

Connect a database directly to Algenta — the engine reads your tables under a governed contract, never copies them, and keeps credentials encrypted at rest.

Algenta connects directly to your database. You register the connection once, Algenta opens a real connection to verify it, and from then on the engine reads your tables under a typed, governed contract — it never copies your database, never reaches beyond what you configured, and stores your credentials encrypted at rest. This page walks the direct-connection flow end to end for any supported SQL database or warehouse.

This is direct connectivity over the database's own wire protocol — not a sync, not an export, and not a third-party bridge. The engine queries your data in place, scoped to your organization. For the full connector model across all source types (object storage, REST, files), see Connectors overview.

Supported databases

Family	Types
Relational	postgres, oracle, mysql, mssql, sqlite
Warehouse	snowflake, bigquery, clickhouse, redshift
Graph, cache & search	neo4j, redis, elasticsearch

SQL databases accept a single connection_string DSN or provider-specific discrete fields. Oracle also accepts an Easy Connect DSN or an Autonomous Database TNS alias with optional mTLS wallet fields. For the exact config fields per type, see the Connectors reference; for worked walkthroughs see Oracle Database, Snowflake, BigQuery, and ClickHouse.

Connect it in four steps

A database moves through create → test → browse → connect before the engine reads a row. The example uses postgres; every SQL type follows the same shape.

1

Create the connector

POST /v1/connectors stores the connection with status untested. Keep the returned id — every step below uses it.

cURL

curl -sS -X POST "$ALGENTA_API_URL/v1/connectors" \
  -H "Authorization: Bearer $ALGENTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "analytics-pg",
    "connector_type": "postgres",
    "config": {
      "connection_string": "postgresql://reader:'"$ALGENTA_DB_PASSWORD"'@db.internal:5432/analytics"
    }
  }'

Python

import os

import httpx

api_url = os.environ.get("ALGENTA_API_URL", "https://api.algenta.ai")
resp = httpx.post(
    f"{api_url}/v1/connectors",
    headers={"Authorization": f"Bearer {os.environ['ALGENTA_API_KEY']}"},
    json={
        "name": "analytics-pg",
        "connector_type": "postgres",
        "config": {
            "host": "db.internal",
            "port": 5432,
            "database": "analytics",
            "user": "reader",
            "password": os.environ["ALGENTA_DB_PASSWORD"],
        },
    },
)
resp.raise_for_status()
print(resp.json()["id"], resp.json()["status"])  # "untested"

CLI

de connectors create connector.json     # POST /v1/connectors from a JSON body

2

Test the connection

POST /v1/connectors/{id}/test opens a real connection and runs SELECT 1. On success the status flips to live; on failure it goes to error with a message.

curl -sS -X POST "$ALGENTA_API_URL/v1/connectors/$CONNECTOR_ID/test" \
  -H "Authorization: Bearer $ALGENTA_API_KEY"

Expected result. The connector flips to live and the response reports the reachable database, e.g. {"success": true, "status": "live", "message": "Connection successful"}. A connector must be live before you can browse it.

3

Browse the schema

GET /v1/connectors/{id}/browse lists the tables the connection exposes, so you can pick what to onboard.

curl -sS "$ALGENTA_API_URL/v1/connectors/$CONNECTOR_ID/browse" \
  -H "Authorization: Bearer $ALGENTA_API_KEY"

4

Connect a table as a dataset

POST /v1/data/connect ties the connection to a selection — a table or a SQL query — and registers it as a queryable dataset. Reference the saved connector by connection_id.

curl -sS -X POST "$ALGENTA_API_URL/v1/data/connect" \
  -H "Authorization: Bearer $ALGENTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"connection_id": "'"$CONNECTOR_ID"'", "selection": {"table": "revenue_by_region"}}'

A fully-identified table returns status: "ready" with a dataset_id and a schema_summary. With that dataset_id you run deterministic, schema-checked queries through POST /v1/query.

Editing a connector's config resets it to untested and clears the previous error — re-run the test before browsing again. You can also validate a config without saving it via POST /v1/connectors/test. See the Connect a data source guide for the full walkthrough.

Next steps

Connectors referenceConnect a data sourceQuery governed dataConnectors overview