Create database connection

Creates a new database connection for the specified environment with secure credential storage and connection validation.

POST/organizations/{organizationName}/environments/{environmentName}/connections

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

organizationName*string

The unique identifier of the organization

Match^[a-zA-Z0-9_ -]+$

environmentName*string

The unique identifier of the environment

Match^[a-zA-Z0-9_ -]+$

Query Parameters

dryRun?boolean

Whether to test the connection without saving it

Defaultfalse

Request Body

application/json

resource?string

Resource path to the connection

name?string

Name of the connection

type?string

Type of database connection

Value in

"postgres"
"bigquery"
"snowflake"
"trino"
"databricks"
"mysql"
"duckdb"
"motherduck"
"ducklake"
"publisher"

fingerprint?string

Optional, opaque, stable fingerprint of this connection's data identity. It is a hash of the configuration that determines which data the connection reaches (its data-locating settings), and deliberately excludes credentials and other secret values, so it stays constant across credential rotation and changes only when the connection is pointed at different data. When present, it is used as this connection's contribution to content-addressed build identifiers so that builds re-address only when the underlying data identity actually changes; consumers should treat it as an opaque token and use the supplied value verbatim rather than deriving their own. This field is optional — when omitted, a connection identity is derived locally instead.

attributes?

Connection capabilities and configuration attributes

proxy?

Optional network proxy through which the connection is reached. Applies to any connection type whose database is not directly reachable (e.g. behind a bastion). The proxy is established below the driver, so the driver connects to a local endpoint transparently. Modeled as a discriminated union on type so additional proxy mechanisms can be added later.

postgresConnection?

PostgreSQL database connection configuration

bigqueryConnection?

Google BigQuery database connection configuration

snowflakeConnection?

Snowflake database connection configuration

trinoConnection?

Trino database connection configuration

databricksConnection?

Databricks SQL warehouse connection configuration

mysqlConnection?

MySQL database connection configuration

duckdbConnection?

DuckDB database connection configuration. Publisher intentionally exposes only data-source intent here. Database files, working directories, filesystem/network policy, extension loading, setup SQL, temp directories, and resource knobs are owned by Publisher so environment configs cannot widen deployment policy through low-level DuckDB settings.

motherduckConnection?

MotherDuck database connection configuration

ducklakeConnection?

DuckLake lakehouse connection configuration

publisherConnection?

Malloy Publisher proxy connection. Proxies SQL to a remote Publisher dataplane instead of connecting to a warehouse directly. The remote dataplane owns authentication, access control, and read-only enforcement.

template?"bq_demo"

Create this connection from a managed sample template instead of supplying credentials. The server fills the connection type, configuration, and credentials from the named template (currently only bq_demo, our sample BigQuery dataset); any credential or table fields in the request are ignored and the connection name defaults to the template name when omitted. Create-only: never stored or returned.

Value in

"bq_demo"

includeTables?array<>

The list of tables to include, in the format {dataset/schema}.{table}. The first part represents the dataset or schema, and the second part is the table name. The second part can be a literal * to include all tables.

excludeAllTables?boolean

Whether to exclude all tables.

Defaultfalse

excludeTables?array<>

The list of tables to exclude, in the format {dataset/schema}.{table}. The first part represents the dataset or schema, and the second part is the table name. The second part can be a literal * to exclude all tables.

indexingStatus?string

Current indexing status of the connection. UNKNOWN means indexing is queued and starts automatically on creation (no manual action; "Start indexing" is an optional re-trigger). SCHEMA_INDEXING means schema indexing is in progress, MODEL_SUGGESTION_INDEXING means schema indexing finished (schema search is usable) and the model-suggestions pipeline is generating dimensions/measures/joins, INDEXED means both pipelines finished, SKIPPED means the connection is excluded from indexing, FAILED means schema indexing failed, RETRY means the connection was updated while indexing was in progress and will be re-indexed when the current job finishes.

Value in

"UNKNOWN"
"SCHEMA_INDEXING"
"INDEXED"
"SKIPPED"
"FAILED"
"RETRY"
"MODEL_SUGGESTION_INDEXING"

indexingStatusLastUpdated?string

ISO 8601 timestamp of when the indexing status was last updated

Formatdate-time

indexingProgress?

Aggregate per-pipeline indexing progress for a connection, polled from the entity-indexing service while the connection is being indexed. Populated on the single-connection read while indexing is in progress (SCHEMA_INDEXING / MODEL_SUGGESTION_INDEXING); null once INDEXED or when progress is unavailable.

Response Body

`application/json`

curl --request POST \  --url 'https://example.com/organizations/string/environments/string/connections' \  --header 'Authorization: Bearer <token>' \  --header 'Content-Type: application/json' \  --data '{}'

{  "resource": "string",  "name": "string",  "type": "postgres",  "fingerprint": "string",  "attributes": {    "dialectName": "string",    "isPool": true,    "canPersist": true,    "canStream": true  },  "proxy": {    "type": "ssh",    "ssh": {      "host": "string",      "port": 22,      "username": "string",      "privateKey": "string",      "privateKeyPass": "string",      "hostKey": "string"    }  },  "postgresConnection": {    "host": "string",    "port": 0,    "databaseName": "string",    "userName": "string",    "password": "string",    "connectionString": "string",    "sslmode": "disable"  },  "bigqueryConnection": {    "defaultProjectId": "string",    "billingProjectId": "string",    "location": "string",    "serviceAccountKeyJson": "string",    "maximumBytesBilled": "string",    "queryTimeoutMilliseconds": "string"  },  "snowflakeConnection": {    "account": "string",    "username": "string",    "password": "string",    "privateKey": "string",    "privateKeyPass": "string",    "warehouse": "string",    "database": "string",    "schema": "string",    "role": "string",    "responseTimeoutMilliseconds": 0  },  "trinoConnection": {    "server": "string",    "port": 0,    "catalog": "string",    "schema": "string",    "user": "string",    "password": "string",    "peakaKey": "string"  },  "databricksConnection": {    "host": "string",    "path": "string",    "token": "string",    "oauthClientId": "string",    "oauthClientSecret": "string",    "defaultCatalog": "string",    "defaultSchema": "string",    "setupSQL": "string"  },  "mysqlConnection": {    "host": "string",    "port": 0,    "database": "string",    "user": "string",    "password": "string"  },  "duckdbConnection": {    "attachedDatabases": [      {        "name": "string",        "type": "bigquery",        "attributes": {          "dialectName": "string",          "isPool": true,          "canPersist": true,          "canStream": true        },        "bigqueryConnection": {          "defaultProjectId": "string",          "billingProjectId": "string",          "location": "string",          "serviceAccountKeyJson": "string",          "maximumBytesBilled": "string",          "queryTimeoutMilliseconds": "string"        },        "snowflakeConnection": {          "account": "string",          "username": "string",          "password": "string",          "privateKey": "string",          "privateKeyPass": "string",          "warehouse": "string",          "database": "string",          "schema": "string",          "role": "string",          "responseTimeoutMilliseconds": 0        },        "postgresConnection": {          "host": "string",          "port": 0,          "databaseName": "string",          "userName": "string",          "password": "string",          "connectionString": "string",          "sslmode": "disable"        },        "gcsConnection": {          "keyId": "string",          "secret": "string"        },        "s3Connection": {          "accessKeyId": "string",          "secretAccessKey": "string",          "region": "us-east-1",          "endpoint": "string",          "sessionToken": "string"        },        "azureConnection": {          "authType": "service_principal",          "sasUrl": "string",          "tenantId": "string",          "clientId": "string",          "clientSecret": "string",          "accountName": "string",          "fileUrl": "string"        }      }    ]  },  "motherduckConnection": {    "accessToken": "string",    "database": "string"  },  "ducklakeConnection": {    "storage": {      "bucketUrl": "string",      "s3Connection": {        "accessKeyId": "string",        "secretAccessKey": "string",        "region": "us-east-1",        "endpoint": "string",        "sessionToken": "string"      },      "gcsConnection": {        "keyId": "string",        "secret": "string"      }    },    "catalog": {      "postgresConnection": {        "host": "string",        "port": 0,        "databaseName": "string",        "userName": "string",        "password": "string",        "connectionString": "string",        "sslmode": "disable"      }    }  },  "publisherConnection": {    "connectionUri": "string",    "accessToken": "string"  },  "template": "bq_demo",  "includeTables": [    "string"  ],  "excludeAllTables": false,  "excludeTables": [    "string"  ],  "indexingStatus": "UNKNOWN",  "indexingStatusLastUpdated": "2019-08-24T14:15:22Z",  "indexingProgress": {    "schemaProgress": {      "tablesTotal": 0,      "tablesProcessing": 0,      "tablesCompleted": 0,      "tablesFailed": 0,      "columnsTotal": 0,      "columnsCompleted": 0    },    "modelSuggestionsProgress": {      "tablesTotal": 0,      "tablesProcessing": 0,      "tablesCompleted": 0,      "tablesFailed": 0,      "joinWorkTotal": 0,      "joinWorkCompleted": 0,      "joinsGenerated": 0,      "dimensionsGenerated": 0,      "measuresGenerated": 0    }  }}

Create database connection

Authorization

Path Parameters

Query Parameters

Request Body

Response Body

200application/json

400application/json

401application/json

403application/json

404application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`