---
title: "Create connection"
method: POST
path: "/v1/connections"
tags: ["Connections"]
---

# Create connection

`POST /v1/connections`

Creates a new database connection. See the **Parameters**

## Request body

- object
  - `dialect` 'athena' | 'bigquery' | 'clickhouse' | 'databricks' | 'databricks_lakebase' | 'exasol' | 'mariadb' | 'motherduck' | 'mssql' | 'mysql' | 'oracle' | 'postgres' | 'redshift' | 'sap_hana' | 'snowflake' | 'starrocks' | 'trino', required — The database dialect.
  - `name` string, required — A descriptive name for the connection
  - `host` string — The hostname or IP address of the database server. - **MotherDuck** - Not required - **Snowflake** - Provide only the account identifier (e.g., `myaccount` not `myaccount.snowflakecomputing.com`) - **BigQuery** - Automatically determined from the service account
  - `port` integer — The port number for the database connection. Not required for Snowflake, MotherDuck, BigQuery, Databricks, and Athena.
  - `database` string — The default database/catalog to connect to. - **BigQuery** - Provide the project ID - **Athena** - Provide the data catalog
  - `username` string — The username to authenticate with. - **MotherDuck** - Not required - **BigQuery** - Provide client email from the service account
  - `passwordUnencrypted` string, required — The password to authenticate with. - **BigQuery** - This must be the JSON service account key file content - **Snowflake** with keypair authentication - Can be omitted
  - `baseRole` string — The default role for users accessing the connection. Available roles include: - `VIEWER` - Can view the model - `QUERIER` - Can view and query the model - `QUERY_TOPICS` - Can query specific topics. Equivalent to **Restricted Querier.** - `MODELER` - Can edit and model the data - `CONNECTION_ADMIN` - Full administrative access to the connection - `NO_ACCESS` - No access to the model - [Custom roles](/administration/users/custom-roles) defined for your organization
  - `warehouse` string — **Required for**: - **Snowflake** - Specify the warehouse - **Databricks** - Specify the HTTP path
  - `includeSchemas` string — Comma-separated list of schemas to include. Leave empty to include all schemas.
  - `includeOtherCatalogs` string — Comma-separated list of other catalogs/databases to include. **Only applicable for databases that support multi-catalog queries:** BigQuery, Snowflake, MotherDuck, Databricks, Trino, Athena.
  - `defaultSchema` string — **Required for MSSQL.** The default schema to use.
  - `queryTimeoutSeconds` integer — The timeout in seconds for queries. Maximum value is `3600` (1 hour). Only applicable for databases that support query timeouts.
  - `region` string — **Required for BigQuery and Athena connections.** - **BigQuery** - Specify a region like `us` - **Athena** - Specify an AWS region like `us-east-1`
  - `maxBillingBytes` string — **Applicable for BigQuery.** Maximum bytes that can be billed for a BigQuery query.
  - `scratchSchema` string — Schema to use for data input (upload) tables. If not specified, a suitable default will be chosen.
  - `systemTimezone` string — The timezone to use for the system.
  - `queryTimezone` string — The timezone to use for queries.
  - `allowsUserSpecificTimezones` boolean — Whether to allow users to specify their own timezones.
  - `alwaysScopeViewNames` boolean — Whether to prefix generated view names with their schema and catalog, e.g. `my_catalog_public__orders` instead of `orders`. Defaults to `true` for dialects that support multiple catalogs, and `false` otherwise. See [View name generation](/connect-data/view-name-generation) for more information.
  - `trustServerCertificate` boolean — **Applicable for MSSQL, Exasol, and ClickHouse.** Whether to trust the server certificate.
  - `privateKey` string — **Applicable for Snowflake only.** An RSA key for keypair authentication. Omni will automatically add PEM headers if none are provided.
  - `acceptsLicense` boolean — **Applicable for Oracle.** Whether to accept the license terms.
  - `authenticationType` string — **Applicable for BigQuery, MSSQL, Snowflake, Databricks, and Athena.** The authentication method to use.
  - `awsRoleArn` string — **Applicable for Athena.** The AWS role ARN to assume for the connection.
  - `enableDbSemanticLayerIntegration` boolean — Whether to enable the database's semantic layer integration: - **Snowflake** - [Snowflake semantic views](/connect-data/snowflake-semantic-views) - **Databricks** - [Databricks Unity Catalog](/connect-data/databricks-unity-catalog-integration)
  - `enableDbSemanticLayerTopics` boolean — **Applicable for Snowflake and Databricks.** Whether to enable database semantic layer topics.
  - `externalOauthAudience` string — **Applicable for Snowflake.** The audience for [external OAuth authentication](/connect-data/oauth/snowflake/external-okta).
  - `externalOauthAuthorizationUrl` string — **Applicable for Snowflake.** The authorization URL for [external OAuth authentication](/connect-data/oauth/snowflake/external-okta).
  - `externalOauthTokenUrl` string — **Applicable for Snowflake.** The token URL for [external OAuth authentication](/connect-data/oauth/snowflake/external-okta).
  - `hostOverride` string — **Applicable for Snowflake.** Override for the host value.
  - `inferRelationshipsFromColumnNames` boolean — Whether to automatically infer relationships from column-name conventions during schema refresh.
  - `inferRelationshipsFromForeignKeys` boolean — **Applicable for Postgres and Snowflake.** Whether to automatically infer relationships from foreign key constraints.
  - `oauthClientId` string — **Applicable for [Snowflake](/connect-data/oauth/snowflake/native) and Databricks.** The OAuth client ID for native OAuth.
  - `oauthClientSecretUnencrypted` string — **Applicable for Snowflake and Databricks.** The unencrypted OAuth client secret for [native OAuth](/connect-data/oauth/snowflake/native).
  - `offloadedSchemas` string — **Applicable for all dialects.** Comma-separated list of schemas to offload. See [Offloading schemas](/connect-data/offloading-schemas) for more information.
  - `useMachineAuth` boolean — **Applicable for Athena and Databricks.** Whether to use machine authentication.

## Response `201`

Connection created successfully

- object
  - `success` boolean
  - `data` string, uuid — Connection ID

## Other responses

- `400` — Bad Request - Invalid parameters or request body
- `403` — Forbidden - Insufficient permissions
- `429` — Too Many Requests - Rate limit exceeded (60 requests/minute)

---

[API](https://skmtc.net/omni/apis/omni-api.md) · [All operations](https://skmtc.net/omni/apis/omni-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/omni/omni-api/revisions/6b02f7349d0e/schema)