From 10322bdc7998548607efdd225505958f62c7991d Mon Sep 17 00:00:00 2001
From: Mike Alfare <13974384+mikealfare@users.noreply.github.com>
Date: Fri, 19 Jul 2024 13:34:04 -0400
Subject: [PATCH] Update `reuse_connections` default for `dbt-snowflake`
(#5780)
## What are you changing in this pull request and why?
The default for `reuse_connections` has been
[updated](https://github.com/dbt-labs/dbt-snowflake/issues/1082) for
`dbt-snowflake`. This change will affect `versionless` and will be
released as part of `v1.9`.
## Checklist
- [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 <60105315+matthewshaver@users.noreply.github.com>
---
.../connect-data-platform/snowflake-setup.md | 208 +++++++++++++++++-
1 file changed, 203 insertions(+), 5 deletions(-)
diff --git a/website/docs/docs/core/connect-data-platform/snowflake-setup.md b/website/docs/docs/core/connect-data-platform/snowflake-setup.md
index 24ad6f88d62..266840cafae 100644
--- a/website/docs/docs/core/connect-data-platform/snowflake-setup.md
+++ b/website/docs/docs/core/connect-data-platform/snowflake-setup.md
@@ -29,6 +29,8 @@ import SetUpPages from '/snippets/_setup-pages-intro.md';
Snowflake can be configured using basic user/password authentication as shown below.
+
+
```yaml
@@ -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
```
@@ -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
```
+
+
+
+
+
+
+```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
+ ```
+
+
+
+### 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
+```
+
+
+
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
@@ -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.
+
+
```yaml
@@ -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
```
@@ -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
```
@@ -211,7 +286,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
```
@@ -219,6 +294,129 @@ my-snowflake-db:
+
+
+
+
+
+
+```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
+```
+
+
+
+### 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:
+
+
+
+
+
+
+```yaml
+my-snowflake-db:
+ target: dev
+ outputs:
+ dev:
+ type: snowflake
+ account: [account id] # Snowflake
+ 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
+```
+
+
+
+
+
+
+
+
+
+```yaml
+my-snowflake-db:
+ target: dev
+ outputs:
+ dev:
+ type: snowflake
+ account: [account id] # Snowflake
+ 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
+```
+
+
+
+
+
+
+
+
**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.