Creating a Connection

This guide walks through creating a connection in DataRecs, for any of the 10 supported connection types.

Prerequisites

• A DataRecs account with access to a workspace.
• Network connectivity from DataRecs to your data source (your admin may need to allowlist DataRecs egress IPs for database sources).
• Credentials with read access.

Credentials shape by connector type

credentials is a flat JSON object whose fields depend on type — not a nested config.address/config.auth structure. POST /connections/test validates credentials against the real source without creating anything — use it before POST /connections.

Type	Required credentials fields
postgres, mysql, db2, oracle, mssql	host, port, username, password (database is also read; include it for database-scoped sources)
bigquery	access_mode (direct or impersonation), billing_project_id; target_service_account_email is required when access_mode is impersonation
google_sheets	access_mode (direct or impersonation); target_service_account_email required when access_mode is impersonation; optional read_protection (boolean)
excel_sharepoint	tenant_id (required), site_id (optional). Only these two keys are accepted — client_id/client_secret are platform-level secrets, not per-connection credentials, and are rejected
tableau	server_url, username, password
looker	base_url, client_id, client_secret

google_sheets and excel_sharepoint are keyless: they use Workload Identity impersonation rather than a stored database password, which is why their credential shape is access-mode/service-account metadata rather than a secret.

Create the connection

Console

1. Navigate to Connections in the sidebar.
2. Click New Connection.
3. Select your connection type.
4. Fill in the fields for that type (see the table above).
5. Click Test Connection to validate.
6. Once the test passes, click Save.

CLI

Database credentials go through a file — there’s no --host/--port/--username flag path for SQL sources:

connection.json

{
  "name": "production-mysql",
  "type": "mysql",
  "workspace_id": "<workspace-id>",
  "credentials": {
    "host": "db.example.com",
    "port": 3306,
    "database": "mydb",
    "username": "readonly_user",
    "password": "..."
  }
}

datarecs connections test --file connection.json
datarecs connections create --file connection.json

Google Sheets and Excel/SharePoint connections (keyless, no --file needed for credentials) use dedicated flags instead — see cli/overview.

Terraform

resource "datarecs_connection" "prod_mysql" {
  name         = "production-mysql"
  type         = "mysql"
  workspace_id = datarecs_workspace.main.id
  credentials = {
    host     = "db.example.com"
    port     = "3306"
    database = "mydb"
    username = "readonly_user"
    password = var.db_password
  }
}

tofu plan
tofu apply

type and workspace_id force replacement if changed (RequiresReplace); credentials updates in place — that’s how you rotate a password. See the full resource schema.

REST API

curl -X POST https://api.datarecs.io/connections \
  -H "Authorization: Bearer $DATARECS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-mysql",
    "type": "mysql",
    "workspace_id": "<workspace-id>",
    "credentials": {
      "host": "db.example.com",
      "port": 3306,
      "database": "mydb",
      "username": "readonly_user",
      "password": "REDACTED"
    }
  }'

workspace_id (the owning workspace) and a flat nested credentials object are both required — there is no config.address/config.auth wrapper.

What happens behind the scenes

1. DataRecs validates connectivity by opening a test connection to your data source (or, for keyless connectors, by verifying the impersonation grant).
2. Credentials are envelope-encrypted and stored in OpenBao, tenant-scoped.
3. For database sources, a Kubernetes Network Policy is created to allow egress from your tenant’s namespace to your database host, and nothing else.

Sharing a connection across workspaces

A connection has one owning workspace (workspace_id — controls who can modify it and its sharing) and can optionally be shared into others via workspace_ids. If omitted, a connection is only usable from its owning workspace.

Troubleshooting

Issue	Solution
Connection timeout	Verify your database is reachable from DataRecs. Check firewall rules and allowlisted egress IPs.
Authentication failed	Double-check username and password. Ensure the user has read privileges on the tables you’ll reconcile.
excel_sharepoint credentials rejected	Only tenant_id and site_id are accepted in credentials for this type — remove any other keys.
BigQuery/Google Sheets impersonation fails	target_service_account_email is required whenever access_mode is impersonation.