Registers an external-system connection (database, object store, git host, SFTP, or REST API) used by schema discovery and federated queries.
CREATE CONNECTION [IF NOT EXISTS] <name>
TYPE = <connection_type>
[DESCRIPTION '<text>']
OPTIONS (<key> = '<value>', ...)
[CREDENTIAL = <vault_entry_name>]
[CREDENTIAL STORAGE = <backend_name>]
[MAX_CONNECTIONS = <n>]
[TIMEOUT = <seconds>]## Overview CREATE CONNECTION registers an external-system connection in external_connections. Connections are named handles used by schema discovery (list_remote_schemas, list_remote_tables, get_remote_table_schema), federated queries, and CREATE EXTERNAL TABLE. The statement mirrors the 'Create Connection' wizard on the GUI Connections page. ## Behavior - A row is inserted into external_connections with entity_ref set to 'con::<name>', connection_type parsed from the TYPE keyword, options serialized as JSON, and credential_id / credential_storage_id resolved from CREDENTIAL and CREDENTIAL STORAGE respectively. - Exactly one auth path should be used: CREDENTIAL for per-connection vault secrets (username/password, tokens, private keys) or CREDENTIAL STORAGE for cloud-native auth (IAM role, managed identity, ADC). Supplying both is accepted but only one is exercised at runtime, depending on the connection type. - The command does not probe the connection. Use TEST CONNECTION after CREATE to verify reachability. - IF NOT EXISTS makes the statement idempotent. The second execution with the same name returns the existing row unchanged. ## Connection types and typical options ### Databases postgresql, mysql, sql_server, oracle. Typical OPTIONS: host, port, database, ssl_enabled, connection_timeout. Auth via CREDENTIAL = <vault_entry> holding username+password or equivalent. ### Object stores azure_adls, s3, gcs, local. Typical OPTIONS: bucket (s3, gcs), container + account_name (azure_adls), path (local). Auth via CREDENTIAL STORAGE = <backend> is preferred; the cloud backend handles IAM/managed-identity/ADC end to end. ### Git hosts github, azure_devops, gitlab, bitbucket. Typical OPTIONS: organization, api_url. Auth via CREDENTIAL holding a personal access token. ### SFTP Typical OPTIONS: host, port, path. Auth via CREDENTIAL holding a private key. ### REST API Typical OPTIONS: endpoint, method, expected_status, auth_type, api_key_header, timeout_secs. Auth via CREDENTIAL holding a bearer token or API key. ## Access Control Requires the admin role. The Control Plane enforces connections:write on POST /connections. ## Compatibility DeltaForge extension. Parts of the shape resemble federated-source registration in other systems, but the syntax is DeltaForge specific.
| Name | Type | Description |
|---|---|---|
name | Specifies the unique connection name. Enforced as unique across external_connections by a DB constraint. | |
connection_type | Specifies the kind of external system. Accepted values: postgresql, mysql, sql_server, oracle (databases); azure_adls, s3, gcs, local (object stores); github, azure_devops, gitlab, bitbucket (git hosts); sftp; rest_api. | |
description | Specifies an optional human-readable description shown in the GUI Connections page and in DESCRIBE output. | |
options | Specifies type-specific connection parameters. Databases: host, port, database, ssl_enabled, connection_timeout. Object stores: bucket/container, region/account_name, path. Git: organization, api_url. SFTP: host, port, path. REST: endpoint, method, expected_status, auth_type, api_key_header, timeout_secs. Sensitive values should never be placed inline; use CREDENTIAL or CREDENTIAL STORAGE instead. | |
credential_ref | Specifies the display_name of a VAULT/CREDENTIAL entry that holds auth material for this connection (username+password for databases, personal access token for git, private key for SFTP, API key for REST). At runtime the connection resolves the entry to retrieve the secret. | |
credential_storage_ref | Specifies the display_name of a CREDENTIAL STORAGE backend (Azure Key Vault, AWS Secrets Manager, GCP Secret Manager). Used for object-store connections whose auth is handled end-to-end by the cloud backend (IAM role, managed identity, ADC) rather than a per-entry vault credential. | |
max_connections | Specifies the connection-pool size cap. | |
timeout_secs | Specifies the connection-open timeout in seconds. | |
if_not_exists | When true, skip silently if a connection with this name already exists. |
-- PostgreSQL with vault-managed password
CREATE CONNECTION prod_pg
TYPE = postgresql
DESCRIPTION 'Production OLTP'
OPTIONS (
host = 'db.prod.example.com',
port = '5432',
database = 'app',
ssl_enabled = 'true'
)
CREDENTIAL = prod_pg_password
MAX_CONNECTIONS = 10
TIMEOUT = 15;-- S3 using a CREDENTIAL STORAGE backend for cloud-native auth
CREATE CONNECTION raw_data_s3
TYPE = s3
OPTIONS (bucket = 'company-raw', region = 'us-east-1')
CREDENTIAL STORAGE = prod_aws_sm;-- Azure Data Lake Gen2
CREATE CONNECTION analytics_adls
TYPE = azure_adls
OPTIONS (account_name = 'analyticsdatalake', container = 'curated')
CREDENTIAL STORAGE = prod_azure_kv;-- GitHub with a personal access token
CREATE CONNECTION repo_sync
TYPE = github
OPTIONS (organization = 'my-org', api_url = 'https://api.github.com')
CREDENTIAL = github_pat;-- SFTP with a private-key credential
CREATE CONNECTION inbound_sftp
TYPE = sftp
OPTIONS (host = 'sftp.partner.com', port = '22', path = '/inbound')
CREDENTIAL = inbound_sftp_key;-- REST API
CREATE CONNECTION crm_api
TYPE = rest_api
OPTIONS (
endpoint = 'https://api.crm.example.com',
method = 'GET',
expected_status = '200',
timeout_secs = '30'
)
CREDENTIAL = crm_api_token;