Snowflake 연결 관리하기¶

대체 구성 파일¶

Snowflake CLI 는 connections.toml 구성 파일도 지원합니다. 파일은 config.toml 파일과 동일한 디렉터리에 위치해야 하며 연결만 포함되어야 합니다. connections.toml 로 구성하려면 connections 을 제외한 다른 섹션 이름이 필요합니다. 예를 들어, [connections.myconnection] 은 [myconnection] 입니다.

연결 추가¶

새 연결을 생성하여 설정 파일 에 추가하려면 다음을 수행합니다.

1. snow connection add 명령을 실행합니다.

   snow connection add
   

   Copy

2. 메시지가 표시되면 필수 연결, 계정, 사용자 이름 매개 변수와 원하는 기타 선택 사항 매개 변수를 입력합니다.

   Enter connection name: <connection_name>
   Enter account: <account>
   Enter user: <user-name>
   Enter password: <password>
   Enter role: <role-name>
   Enter warehouse: <warehouse-name>
   Enter database: <database-name>
   Enter schema: <schema-name>
   Enter host: <host-name>
   Enter port: <port-number>
   Enter region: <region-name>
   Enter authenticator: <authentication-method>
   Enter private key file: <path-to-private-key-file>
   Enter token file path: <path-to-mfa-token>
   Do you want to configure key pair authentication? [y/N]: y
   Key length [2048]: <key-length>
   Output path [~/.ssh]: <path-to-output-file>
   Private key passphrase: <key-description>
   Wrote new connection <connection-name> to config.toml
   

다음과 같이 명령줄에서 특정 매개 변수에 대한 값을 추가할 수도 있습니다.

snow --config-file config.toml connection add -n myconnection2 --account myaccount2 --user jdoe2

기본적으로 snow connection add 명령은 명령줄에 선택적 매개 변수를 지정하지 않은 경우 이를 입력하라는 메시지를 표시합니다. account 와 같은 선택적 매개 변수를 지정하지 않고 연결을 추가하고 대화형 프롬프트를 건너뛰려면 다음과 같이 --no-interactive 옵션을 사용할 수 있습니다.

snow connection add -n myconnection2 --user jdoe2 --no-interactive

연결을 추가한 후 연결을 테스트하여 제대로 작동하는지 확인할 수 있습니다.

정의된 연결 나열¶

사용 가능한 연결을 나열하려면 다음과 같이 snow connection list 명령을 입력합니다.

snow connection list

+-------------------------------------------------------------------------------------------------+
| connection_name | parameters                                                       | is_default |
|-----------------+------------------------------------------------------------------+------------|
| myconnection    | {'account': 'myaccount', 'user': 'jondoe', 'password': '****',   | False      |
|                 | 'database': 'my_db', 'schema': 'my_schema', 'warehouse':         |            |
|                 | 'my-wh'}                                                         |            |
| myconnection2   | {'account': 'myaccount2', 'user': 'jdoe2'}                       | False      |
+-------------------------------------------------------------------------------------------------+

연결 테스트 및 진단하기¶

연결이 Snowflake에 성공적으로 연결되는지 테스트하려면 다음과 유사하게 snow connection test 명령을 입력합니다.

snow connection test -c myconnection2

+--------------------------------------------------+
| key             | value                          |
|-----------------+--------------------------------|
| Connection name | myconnection2                  |
| Status          | OK                             |
| Host            | example.snowflakecomputing.com |
| Account         | myaccount2                     |
| User            | jdoe2                          |
| Role            | ACCOUNTADMIN                   |
| Database        | not set                        |
| Warehouse       | not set                        |
+--------------------------------------------------+

연결 문제가 발생하면 Snowflake CLI 에서 직접 진단을 실행할 수 있습니다. Snowflake 지원팀에서는 연결 문제를 해결하기 위해 이 정보를 요청할 수도 있습니다.

진단 모음에서는 다음 snow connection test 명령 옵션을 사용합니다.

• 진단 보고서를 생성하는 --enable-diag.

• 생성된 보고서의 절대 경로를 지정하는 --diag-log-path.

• SYSTEM$ALLOWLIST() 또는 SYSTEM$ALLOWLIST_PRIVATELINK() SQL 명령의 출력을 포함하는 JSON 파일의 절대 경로를 지정하는 --diag-allowlist-path. 이 옵션은 연결에 정의된 사용자에게 시스템 허용 목록 함수를 실행할 권한이 없거나 계정 URL 에 연결이 실패한 경우에만 필요합니다.

다음은 myconnection2 연결에 대한 진단 보고서를 생성하여 ~/report/SnowflakeConnectionTestReport.txt 파일에 저장하는 예입니다.

snow connection test -c myconnection2 --enable-diag --diag-log-path $(HOME)/report

+----------------------------------------------------------------------------+
| key                  | value                                               |
|----------------------+-----------------------------------------------------|
| Connection name      | myconnection2                                       |
| Status               | OK                                                  |
| Host                 | example.snowflakecomputing.com                      |
| Account              | myaccount2                                          |
| User                 | jdoe2                                               |
| Role                 | ACCOUNTADMIN                                        |
| Database             | not set                                             |
| Warehouse            | not set                                             |
| Diag Report Location | /Users/<username>/SnowflakeConnectionTestReport.txt |
+----------------------------------------------------------------------------+

연결 문제가 있는지 보고서를 검토하고 네트워크 팀과 논의할 수 있습니다. 추가 지원을 위해 Snowflake 지원팀에 보고서를 제공할 수도 있습니다.

기본 연결 설정¶

snow connection set-default 명령을 사용하여 Snowflake CLI 에서 기본값으로 사용할 구성을 지정할 수 있으며, 설정된 경우 default_connection_name 구성 파일 및 SNOWFLAKE_DEFAULT_CONNECTION_NAME 변수를 재정의할 수 있습니다.

다음 예제에서는 기본 연결을 myconnection2 로 설정합니다.

snow connection set-default myconnection2

Default connection set to: myconnection2

Snowflake 자격 증명에 환경 변수 사용¶

구성 파일 대신 시스템 환경 변수에서 Snowflake 자격 증명을 지정할 수 있습니다. 다음 일반 환경 변수는 연결 매개 변수를 지정하기 위한 용도로만 사용할 수 있습니다.

• SNOWFLAKE_ACCOUNT

• SNOWFLAKE_USER

• SNOWFLAKE_PASSWORD

• SNOWFLAKE_DATABASE

• SNOWFLAKE_SCHEMA

• SNOWFLAKE_ROLE

• SNOWFLAKE_WAREHOUSE

• SNOWFLAKE_AUTHENTICATOR

• SNOWFLAKE_PRIVATE_KEY_PATH

• SNOWFLAKE_PRIVATE_KEY_RAW

• SNOWFLAKE_SESSION_TOKEN

• SNOWFLAKE_MASTER_TOKEN

• SNOWFLAKE_TOKEN_FILE_PATH

• SNOWFLAKE_OAUTH_CLIENT_ID

• SNOWFLAKE_OAUTH_CLIENT_SECRET

• SNOWFLAKE_OAUTH_AUTHORIZATION_URL

• SNOWFLAKE_OAUTH_TOKEN_REQUEST_URL

• SNOWFLAKE_OAUTH_REDIRECT_URI

• SNOWFLAKE_OAUTH_SCOPE

• SNOWFLAKE_OAUTH_DISABLE_PKCE

• SNOWFLAKE_OAUTH_ENABLE_REFRESH_TOKENS

• SNOWFLAKE_OAUTH_ENABLE_SINGLE_USE_REFRESH_TOKENS

• SNOWFLAKE_CLIENT_STORE_TEMPORARY_CREDENTIAL

연결 매개 변수를 snow 명령에 전달합니다.¶

연결이 필요한 모든 snow 명령에서 직접 연결 매개 변수를 전달할 수 있습니다. 연결 구성 매개 변수의 전체 목록을 보려면 다음과 같이 snow sql --help 명령을 실행합니다. 출력에는 연결 구성 옵션이 있는 섹션만 표시됩니다.

snow sql --help

╭─ Connection configuration ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --connection,--environment             -c      TEXT     Name of the connection, as defined in your config.toml. Default: default.
│ --host                                         TEXT     Host address for the connection. Overrides the value specified for the connection.
│ --port                                         INTEGER  Port for the connection. Overrides the value specified for the connection.
│ --account,--accountname                        TEXT     Name assigned to your Snowflake account. Overrides the value specified for the connection.
│ --user,--username                              TEXT     Username to connect to Snowflake. Overrides the value specified for the connection.
│ --password                                     TEXT     Snowflake password. Overrides the value specified for the connection.
│ --authenticator                                TEXT     Snowflake authenticator. Overrides the value specified for the connection.
│ --private-key-file,--private-key-path          TEXT     Snowflake private key file path. Overrides the value specified for the connection.
│ --token-file-path                              TEXT     Path to file with an OAuth token that should be used when connecting to Snowflake.
│ --database,--dbname                            TEXT     Database to use. Overrides the value specified for the connection.
│ --schema,--schemaname                          TEXT     Database schema to use. Overrides the value specified for the connection.
│ --role,--rolename                              TEXT     Role to use. Overrides the value specified for the connection.
│ --warehouse                                    TEXT     Warehouse to use. Overrides the value specified for the connection.
│ --temporary-connection                 -x               Uses connection defined with command line parameters, instead of one defined in config.
│ --mfa-passcode                                 TEXT     Token to use for multi-factor authentication (MFA).
│ --oauth-client-id                              TEXT     Value of the client ID provided by the identity provider for Snowflake integration.
│ --oauth-client-secret                          TEXT     Value of the client secret provided by the identity provider for Snowflake integration.
│ --oauth-authorization-url                      TEXT     Identity provider endpoint supplying the authorization code to the driver.
│ --oauth-token-request-url                      TEXT     Identity provider endpoint supplying the access tokens to the driver.
│ --oauth-redirect-uri                           TEXT     URI to use for the authorization code.
│ --oauth-scope                                  TEXT     Scope requested in the identity provider authorization request.
│ --oauth-disable-pkce                                    Disables Proof Key for Code Exchange (PKCE). Default: False.
│ --oauth-enable-refresh-tokens                           Enables a silent re-authentication when the actual access token becomes outdated. Default: False.
│ --oauth-enable-single-use-refresh-tokens                Whether to opt in to single-use refresh token semantics. Default: False.
│ --client-store-temporary-credential                     Store the temporary credential.
│ --enable-diag                                           Run the python connector diagnostic test.
│ --diag-log-path                                TEXT     Diagnostic report path.
│ --diag-allowlist-path                          TEXT     Diagnostic report path to optional allowlist.
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

인증에 개인 키 파일 사용¶

개인 키 파일을 인증에 사용하려면 연결 구성에서 authenticator 매개 변수를 SNOWFLAKE_JWT 로 설정하고 다음과 같이 개인 키가 있는 파일의 경로를 제공해야 합니다.

• 다음과 같이 snow connection add 명령에 --private_key-file 옵션을 지정합니다.

  snow connection add \
     --connection-name jwt \
     --authenticator SNOWFLAKE_JWT \
     --private-key-file ~/.ssh/sf_private_key.p8
  

  Copy

• 구성 파일 사용:

  [connections.jwt]
  account = "my_account"
  user = "jdoe"
  authenticator = "SNOWFLAKE_JWT"
  private_key_file = "~/sf_private_key.p8"
  

  Copy

키 페어 인증 구성에 대한 자세한 내용은 키 페어 인증 및 키 페어 순환 섹션을 참조하십시오.

Snowflake CLI 는 다음 순서로 연결 매개 변수에서 개인 키를 찾습니다.

1. private_key_file 을 지정하면 Snowflake CLI 는 지정된 파일 경로에서 키를 읽습니다.

2. private_key_path 를 지정하면 Snowflake CLI 는 지정된 파일 경로에서 키를 읽습니다.

3. private_key_file 또는 private_key_path 를 지정하지 않으면 Snowflake CLI 는 private_key_raw 매개 변수에서 직접 키를 읽습니다.

OAuth 인증 사용¶

OAuth를 사용하여 연결하려면 다음 중 하나를 수행하면 됩니다.

• 다음과 같이 snow connection add 명령에 --token-file-path 옵션을 지정합니다.

  snow connection add --token-file-path "my-token.txt"
  

  Copy

• config.toml 파일에서 다음과 같이 authenticator = "oauth"`를 설정하고 연결 정의에 ``token_file_path` 매개 변수를 추가합니다.

  [connections.oauth]
  account = "my_account"
  user = "jdoe"
  authenticator = "oauth"
  token_file_path = "my-token.txt"
  

  Copy

OAuth 2.0 Authorization Code 흐름 사용하기¶

OAuth 2.0 Authorization Code 흐름은 클라이언트 애플리케이션이 사용자의 자격 증명을 공개하지 않고 사용자를 대신하여 인증 서버로부터 액세스 토큰을 획득하는 보안 방법입니다. 이 흐름과 흐름의 매개 변수에 대한 자세한 내용은 Snowflake Connector for Python 설명서의 OAuth 2.0 Authorization Code 흐름 활성화하기 섹션을 참조하십시오.

OAuth 2.0 Authorization Code 흐름을 사용하려면 다음과 유사하게 config.toml 파일에 연결 정의를 추가하십시오.

[connections.oauth]
authenticator = "OAUTH_AUTHORIZATION_CODE"
user = "user"
account = "account"
oauth_client_id = "client_id"
oauth_client_secret = "client_secret"
oauth_redirect_uri = "http://localhost:8001/snowflake/oauth-redirect"
oauth_scope = "session:role:PUBLIC"

OAuth 2.0 Client Credentials 흐름 사용하기¶

OAuth 2.0 Client Credentials 흐름은 백엔드 서비스에 연결되는 Snowflake Connector for Python과 같은 머신 간(M2M) 인증을 위한 안전한 방법을 제공합니다. OAuth 2.0 Authorization Code 흐름과 달리, 이 방법은 사용자별 데이터에 의존하지 않습니다. 이 흐름과 흐름의 매개 변수에 대한 자세한 내용은 Snowflake Connector for Python 설명서의 OAuth 2.0 Client Credentials 흐름 활성화하기 섹션을 참조하십시오.

OAuth 2.0 Client Credentials 흐름을 사용하려면 다음과 유사한 config.toml 파일에 연결 정의를 추가하십시오.

[connections.oauth]
authenticator = "OAUTH_CLIENT_CREDENTIALS"
user = "user"
account = "account"
oauth_client_id = "client_id"
oauth_client_secret = "client_secret"
oauth_token_request_url = "http://identity.provider.com/token"
oauth_scope = "session:role:PUBLIC"

다단계 인증(MFA) 사용¶

MFA 를 사용하려면 다음을 수행하십시오.

1. Snowflake에서 다단계 인증 을 설정하고 authenticator 매개 변수를 snowflake (기본값)로 설정합니다.

2. 푸시 메커니즘 대신 Duo에서 생성한 비밀번호를 사용하려면 --mfa-passcode <passcode> 옵션을 사용하거나 config.toml 파일에서 passcode_in_password = true 를 설정하고 Python에서 MFA 사용하기 에 설명된 대로 비밀번호에 암호를 포함하십시오.

   참고

   인증을 위해 비밀번호에 암호를 사용하려면 첫 번째 snow 명령을 실행한 후 토큰이 유효한 한 더 이상 암호를 제공할 수 없습니다. 다음을 수행해야 합니다.

   • 비밀번호에서 암호를 제거합니다.

   • config.toml 파일에서 passcode_in_password = true 를 제거하거나 설명합니다.

MFA 캐싱 사용하기¶

MFA 캐시는 로그인 시 다단계 인증(MFA) 프롬프트의 빈도를 줄여주는 보안 기능입니다. MFA 메시지가 자주 표시되면 워크플로가 중단되고 생산성이 저하될 수 있습니다. MFA 캐싱은 지정된 기간 동안 MFA 세션 정보를 안전하게 저장하여 이 문제를 해결합니다. MFA 캐싱을 사용하면 캐시된 세션의 시간 내에 있는 경우 MFA 코드를 반복적으로 입력하지 않고도 인증할 수 있습니다.

MFA 캐싱을 활성화하려면:

1. 계정에 ALLOW_CLIENT_MFA_CACHING = true 를 설정합니다.

2. 파일에서 config.toml 연결에 authenticator = "username_password_mfa" 를 추가합니다.

자세한 내용은 MFA 토큰 캐싱을 사용하여 인증 도중 프롬프트 수 최소화하기 — 선택 사항 섹션을 참조하십시오.

SSO(Single Sign-On) 사용¶

Snowflake에서 Single Sign-On(SSO) 을 사용하도록 구성한 경우, 인증에서 SSO를 사용하도록 클라이언트 애플리케이션을 구성할 수 있습니다. 자세한 내용은 Snowflake에 연결하는 클라이언트 애플리케이션에서 SSO 사용하기 섹션을 참조하고 Python용 지침에 따라 연결을 구성하십시오.

외부 브라우저 사용하기¶

브라우저를 사용하여 Okta 또는 Active Directory Federation Services와 같은 SAML 2.0 호환 ID 공급자(IdP)와의 Snowflake CLI 연결을 인증할 수 있습니다.

외부 브라우저 인증을 사용하려면 다음 메서드 중 하나를 사용하십시오.

• snow connection add --authenticator 명령 옵션을 사용합니다.

  snow connection add --authenticator externalbrowser
  

  Copy

• config.toml 파일에서 authenticator 를 externalbrowser 로 설정합니다.

  [connections.externalbrowser]
  account = "my_account"
  user = "jdoe"
  authenticator = "externalbrowser"
  

  Copy

PAT (프로그래밍 방식 액세스 토큰) 사용하기¶

프로그래밍 방식 액세스 토큰(PAT)은 Snowflake 전용 인증 방식입니다. 이 기능을 사용하려면 먼저 해당 계정에 대해 기능을 활성화해야 합니다(자세한 내용은 전제 조건 참조). PAT 를 통한 인증에는 사람의 개입이 필요하지 않습니다.

연결에 PAT 를 사용하려면 아래와 같이 토큰이 있는 파일을 가리키도록 authenticator 를 PROGRAMMATIC_ACCESS_TOKEN 및 token_file_path 로 설정합니다.

[connections.externalbrowser]
account = "my_account"
user = "jdoe"
authenticator = "PROGRAMMATIC_ACCESS_TOKEN"
token_file_path = "path-to-pat-token"

PATs에 대한 자세한 내용은 인증을 위해 프로그래밍 방식의 액세스 토큰 사용 를 참조하십시오.