1. Connect a source

Keel reads your database through a read-only connection. It never writes through this connection, and it only reads the data it needs to profile columns (bounded samples) and to answer semantic queries you run. (The licensed Keel Migrate module writes to a migration target, and only through your private agent with a separate write credential: see Run and cut over.)

Create a read-only principal first

Open Sources › Connect source, pick the kind, and use Copy read-only role script: every connector ships a least-privilege script for its engine (for example a keel_reader role with SELECT on the schemas in scope). Each engine's script, and how it is verified, is on its page under Connect sources. Keel's Test connection warns — it does not fail — when the principal can write.

The connect sheet

Sources › Connect source opens a three-step sheet:

1. Kind — PostgreSQL, SQL Server / Azure SQL, MySQL / MariaDB, Oracle, Amazon Redshift, Snowflake, Google BigQuery or Databricks SQL. The fields that follow come from the connector's connection schema; see the connector reference for each kind's fields and authentication methods.
2. Connection and scope — host, port, database, user and secret (password, key pair or service-account JSON); Network (Direct, or Private agent — see Private agent); Schemas in scope and Exclude as comma-separated globs (sales.*, *_tmp).
3. Test — Keel registers the source, then a worker runs the checklist: network, authentication, metadata access, least privilege and query-log access. Each check reports pass, warn or fail with a Keel-written message; provider error text is never passed through.

Choose Save and scan to start the first scan straight away. Cancelling the sheet after a test deletes the draft source.

What Keel does with the secret

• The password or key goes to the secret store (envelope-encrypted per tenant, or Azure Key Vault); the source keeps only a reference. It is write-only: no API response, log line, trace or audit record contains it.
• Replace it at any time (PUT …/sources/{id}/secret); the old secret is retired. Changing connection details or the secret resets the source to Untested.

Network safety

In Direct mode, Keel refuses private, loopback, link-local and cloud-metadata addresses (Sources.BlockedHost) and re-checks the resolved addresses when it connects. Cloud warehouses only reach their provider's hosts (Sources.HostNotAllowed); an administrator can allow extra hosts for private links with Keel:Connectors:AllowedCloudHosts. The local stack sets Keel:Connectors:AllowPrivateNetworks=true so the sample databases on 127.0.0.1 work — never set it in a multi-tenant deployment.

Health

After registration the Scheduler re-tests every source that hasn't been tested for 6 hours. Status is Healthy, Degraded (no table matches the scope) or Failing (a check failed); a failing source notifies Owners and Admins.

With the API

curl -X POST "$KEEL/api/v1/workspaces/$WS/sources" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
        "name": "warehouse",
        "kind": "PostgreSql",
        "host": "db.example.com", "port": 5432, "database": "analytics",
        "username": "keel_reader", "secret": "…",
        "networkMode": "Direct",
        "include": ["sales.*"], "exclude": ["*_tmp"],
        "options": { "tls": "require" }
      }'
# → 201 { "id": "…" }
curl -X POST "$KEEL/api/v1/workspaces/$WS/sources/$SOURCE:test" -H "Authorization: Bearer $TOKEN"
# → 202 with a job; the checklist is stored on the source when the job completes

Reference: Sources API.