Skip to content

Commit

Permalink
Update reuse_connections default for dbt-snowflake (#5780)
Browse files Browse the repository at this point in the history 
## What are you changing in this pull request and why?

The default for `reuse_connections` has been
[updated](dbt-labs/dbt-snowflake#1082) for
`dbt-snowflake`. This change will affect `versionless` and will be
released as part of `v1.9`.

## Checklist
<!--
Uncomment when publishing docs for a prerelease version of dbt:
- [ ] Add versioning components, as described in [Versioning
Docs](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/single-sourcing-content.md#versioning-entire-pages)
- [ ] Add a note to the prerelease version [Migration
Guide](https://github.com/dbt-labs/docs.getdbt.com/tree/current/website/docs/docs/dbt-versions/core-upgrade)
-->
- [x] Review the [Content style
guide](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/content-style-guide.md)
so my content adheres to these guidelines.
- [x] For [docs
versioning](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/single-sourcing-content.md#about-versioning),
review how to [version a whole
page](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/single-sourcing-content.md#adding-a-new-version)
and [version a block of
content](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/single-sourcing-content.md#versioning-blocks-of-content).
- [x] Add a checklist item for anything that needs to happen before this
PR is merged, such as "needs technical review" or "change base branch."

---------

Co-authored-by: Matt Shaver <[email protected]>
  • Loading branch information
@mikealfare @matthewshaver
mikealfare and matthewshaver authored Jul 19, 2024
1 parent 19ac30c commit 10322bd
Showing 1 changed file with 203 additions and 5 deletions.
208 changes: 203 additions & 5 deletions website/docs/docs/core/connect-data-platform/snowflake-setup.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,8 @@ import SetUpPages from '/snippets/_setup-pages-intro.md';

Snowflake can be configured using basic user/password authentication as shown below.

<VersionBlock lastVersion="1.8">

<File name='~/.dbt/profiles.yml'>

```yaml
Expand Down Expand Up @@ -56,7 +58,7 @@ my-snowflake-db:
connect_timeout: 10 # default: 10
retry_on_database_errors: False # default: false
retry_all: False # default: false
reuse_connections: False # default: false
reuse_connections: False
```
</File>
Expand Down Expand Up @@ -91,9 +93,80 @@ my-snowflake-db:
connect_timeout: 10 # default: 10
retry_on_database_errors: False # default: false
retry_all: False # default: false
reuse_connections: False # default: false
reuse_connections: False
```
</VersionBlock>
<VersionBlock firstVersion="1.9">
<File name='~/.dbt/profiles.yml'>
```yaml
my-snowflake-db:
target: dev
outputs:
dev:
type: snowflake
account: [account id]

# User/password auth
user: [username]
password: [password]

role: [user role]
database: [database name]
warehouse: [warehouse name]
schema: [dbt schema]
threads: [1 or more]
client_session_keep_alive: False
query_tag: [anything]

# optional
connect_retries: 0 # default 0
connect_timeout: 10 # default: 10
retry_on_database_errors: False # default: false
retry_all: False # default: false
reuse_connections: True # default: True if client_session_keep_alive is False, otherwise None
```
</File>
### User / Password + DUO MFA authentication
Snowflake integrates the DUO Mobile app to add 2-Factor authentication to basic user/password as seen below.
```yaml
my-snowflake-db:
target: dev
outputs:
dev:
type: snowflake
account: [account id]

# User/password auth
user: [username]
password: [password]
authenticator: username_password_mfa

role: [user role]
database: [database name]
warehouse: [warehouse name]
schema: [dbt schema]
threads: [1 or more]
client_session_keep_alive: False
query_tag: [anything]

# optional
connect_retries: 0 # default 0
connect_timeout: 10 # default: 10
retry_on_database_errors: False # default: false
retry_all: False # default: false
reuse_connections: True # default: True if client_session_keep_alive is False, otherwise None
```
</VersionBlock>
Along with adding the `authenticator` parameter, be sure to run `alter account set allow_client_mfa_caching = true;` in your Snowflake warehouse. Together, these will allow you to easily verify authentication with the DUO Mobile app (skipping this results in push notifications for every model built on every `dbt run`).

### Key pair authentication
Expand All @@ -102,6 +175,8 @@ To use key pair authentication, specify the `private_key_path` in your configura

Starting from [dbt version 1.7](/docs/dbt-versions/core-upgrade/upgrading-to-v1.7), dbt introduced the ability to specify a `private_key` directly as a string instead of a `private_key_path`. This `private_key` string can be in either Base64-encoded DER format, representing the key bytes, or in plain-text PEM format. Refer to [Snowflake documentation](https://docs.snowflake.com/en/user-guide/key-pair-auth) for more info on how they generate the key.

<VersionBlock lastVersion="1.8">

<File name='~/.dbt/profiles.yml'>

```yaml
Expand Down Expand Up @@ -131,7 +206,7 @@ my-snowflake-db:
connect_timeout: 10 # default: 10
retry_on_database_errors: False # default: false
retry_all: False # default: false
reuse_connections: False # default: false
reuse_connections: False
```

</File>
Expand Down Expand Up @@ -173,7 +248,7 @@ my-snowflake-db:
connect_timeout: 10 # default: 10
retry_on_database_errors: False # default: false
retry_all: False # default: false
reuse_connections: False # default: false
reuse_connections: False
```

</File>
Expand Down Expand Up @@ -211,14 +286,137 @@ my-snowflake-db:
connect_timeout: 10 # default: 10
retry_on_database_errors: False # default: false
retry_all: False # default: false
reuse_connections: False # default: false
reuse_connections: False
```

</File>

</TabItem>
</Tabs>

</VersionBlock>

<VersionBlock firstVersion="1.9">

<File name='~/.dbt/profiles.yml'>

```yaml
my-snowflake-db:
target: dev
outputs:
dev:
type: snowflake
account: [account id]
user: [username]
role: [user role]
# Keypair config
private_key_path: [path/to/private.key]
# or private_key instead of private_key_path
private_key_passphrase: [passphrase for the private key, if key is encrypted]
database: [database name]
warehouse: [warehouse name]
schema: [dbt schema]
threads: [1 or more]
client_session_keep_alive: False
query_tag: [anything]
# optional
connect_retries: 0 # default 0
connect_timeout: 10 # default: 10
retry_on_database_errors: False # default: false
retry_all: False # default: false
reuse_connections: True # default: True if client_session_keep_alive is False, otherwise None
```

</File>

### SSO Authentication

To use SSO authentication for Snowflake, omit a `password` and instead supply an `authenticator` config to your target.
`authenticator` can be one of 'externalbrowser' or a valid Okta URL.

Refer to the following tabs for more info and examples:

<Tabs>
<TabItem value="externalbrowser" label="externalbrowser">

<File name='~/.dbt/profiles.yml'>

```yaml
my-snowflake-db:
target: dev
outputs:
dev:
type: snowflake
account: [account id] # Snowflake <account_name>
user: [username] # Snowflake username
role: [user role] # Snowflake user role
# SSO config
authenticator: externalbrowser
database: [database name] # Snowflake database name
warehouse: [warehouse name] # Snowflake warehouse name
schema: [dbt schema]
threads: [between 1 and 8]
client_session_keep_alive: False
query_tag: [anything]
# optional
connect_retries: 0 # default 0
connect_timeout: 10 # default: 10
retry_on_database_errors: False # default: false
retry_all: False # default: false
reuse_connections: True # default: True if client_session_keep_alive is False, otherwise None
```

</File>

</TabItem>

<TabItem value="oktaurl" label="Okta URL">

<File name='~/.dbt/profiles.yml'>

```yaml
my-snowflake-db:
target: dev
outputs:
dev:
type: snowflake
account: [account id] # Snowflake <account_name>
user: [username] # Snowflake username
role: [user role] # Snowflake user role
# SSO config -- The three following fields are REQUIRED
authenticator: [Okta account URL]
username: [Okta username]
password: [Okta password]
database: [database name] # Snowflake database name
warehouse: [warehouse name] # Snowflake warehouse name
schema: [dbt schema]
threads: [between 1 and 8]
client_session_keep_alive: False
query_tag: [anything]
# optional
connect_retries: 0 # default 0
connect_timeout: 10 # default: 10
retry_on_database_errors: False # default: false
retry_all: False # default: false
reuse_connections: True # default: True if client_session_keep_alive is False, otherwise None
```

</File>

</TabItem>
</Tabs>

</VersionBlock>

**Note**: By default, every connection that dbt opens will require you to re-authenticate in a browser. The Snowflake connector package supports caching your session token, but it [currently only supports Windows and Mac OS](https://docs.snowflake.com/en/user-guide/admin-security-fed-auth-use.html#optional-using-connection-caching-to-minimize-the-number-of-prompts-for-authentication).

Refer to the [Snowflake docs](https://docs.snowflake.com/en/sql-reference/parameters.html#label-allow-id-token) for info on how to enable this feature in your account.
Expand Down

0 comments on commit 10322bd

Please sign in to comment.