Python 커넥터를 사용하여 Snowflake에 연결하기¶

SnowCD를 사용한 Snowflake로의 네트워크 연결 확인하기¶

드라이버를 구성한 후에는 SnowCD 를 사용하여 Snowflake로의 네트워크 연결을 평가하고 문제를 해결할 수 있습니다.

초기 구성 프로세스 및 필요할 때 SnowCD를 사용하여 Snowflake로의 네트워크 연결을 평가하고 문제를 해결할 수 있습니다.

snowflake.connector 모듈 가져오기¶

snowflake.connector 모듈을 가져오려면 다음 명령을 실행하십시오.

import snowflake.connector

Copy

환경 변수, 명령줄, 구성 파일 또는 다른 적절한 소스에서 로그인 정보를 가져올 수 있습니다. 예:

PASSWORD = os.getenv('SNOWSQL_PWD')
WAREHOUSE = os.getenv('WAREHOUSE')
...

ACCOUNT 매개 변수에 계정 식별자 를 사용합니다. 계정 식별자에는 snowflakecomputing.com 접미사가 포함되지 않는다는 점에 유의하십시오.

자세한 내용 및 예는 account 매개 변수에 대한 사용법 노트(connect 메서드용) 를 참조하십시오.

자체 Amazon S3 버킷에서 데이터를 복사하는 경우에는 AWS_ACCESS_KEY_ID 및 AWS_SECRET_ACCESS_KEY가 필요합니다.

import os

AWS_ACCESS_KEY_ID = os.getenv('AWS_ACCESS_KEY_ID')
AWS_SECRET_ACCESS_KEY = os.getenv('AWS_SECRET_ACCESS_KEY')

Copy

참고

데이터가 Microsoft Azure 컨테이너에 저장되는 경우에는 COPY 문에 자격 증명을 직접 입력하십시오.

연결 정보를 읽은 후, 기본 인증자 또는 페더레이션 인증(활성화된 경우)을 사용하여 연결합니다.

세션 매개 변수 설정하기¶

Python 커넥터를 사용할 때 여러 가지 방법으로 QUERY_TAG와 같은 세션 매개 변수를 설정할 수 있습니다.

• 다음과 같이 session_parameters 라는 선택적 연결 매개 변수를 전달하여 Snowflake에 연결할 때 세션 수준의 매개 변수를 설정할 수 있습니다.

  con = snowflake.connector.connect(
      user='XXXX',
      password='XXXX',
      account='XXXX',
      session_parameters={
          'QUERY_TAG': 'EndOfMonthFinancials',
      }
  )
  

  Copy

  connect() 메서드로 전달된 session_parameters 딕셔너리에는 1개 이상의 세션 수준 매개 변수가 포함될 수 있습니다.

• 또한, 연결 후에 ALTER SESSION SET SQL 문을 실행하여 세션 매개 변수를 설정할 수도 있습니다.

  con.cursor().execute("ALTER SESSION SET QUERY_TAG = 'EndOfMonthFinancials'")
  

  Copy

세션 매개 변수에 대한 자세한 내용은 일반 매개 변수 페이지의 개별 매개 변수 설명을 참조하십시오.

기본 인증자를 사용하여 연결하기¶

로그인 매개 변수를 사용하여 Snowflake에 연결:

conn = snowflake.connector.connect(
    user=USER,
    password=PASSWORD,
    account=ACCOUNT,
    warehouse=WAREHOUSE,
    database=DATABASE,
    schema=SCHEMA
    )

Copy

기타 정보를 사용하여 확장해야 할 수 있습니다.

connections.toml 파일을 사용하여 연결하기¶

Python 커넥터를 사용하면 connections.toml 구성 파일에 연결 정의를 추가할 수 있습니다. 연결 정의는 연결 관련 매개 변수의 모음을 참조합니다. toml 파일 형식에 대한 자세한 내용은 TOML (Tom’s Obvious Minimal Language) 을 참조하십시오. Snowflake Python 라이브러리는 현재 TOML 버전 1.0.0을 지원합니다.

Python 커넥터는 다음 위치에서 connections.toml 파일을 순서대로 찾습니다.

• 컴퓨터에 ~/.snowflake 디렉터리가 있으면 Snowflake CLI는 ~/.snowflake/connections.toml 파일을 사용합니다. SNOWFLAKE_HOME 환경 변수에 위치를 설정하여 기본 ~/.snowflake 디렉터리를 재정의할 수 있습니다.

• 그렇지 않으면 Snowflake CLI는 운영 체제를 기반으로 다음 위치 중 하나에 있는 connections.toml 파일을 사용합니다.

  • Linux: ~/.config/snowflake/connections.toml. 하지만 XDG 변수를 사용하여 업데이트할 수 있습니다.

  • Windows: %USERPROFILE%\AppData\Local\snowflake\connections.toml

  • Mac: ~/Library/Application Support/snowflake/connections.toml

연결 구성 파일에 자격 증명을 추가하려면 다음을 수행하십시오.

1. 텍스트 편집기에서 편집할 connections.toml 파일을 엽니다. 예를 들어 Linux vi 편집기에서 파일을 열려면 다음을 수행하십시오.

   $ vi connections.toml
   

   Copy

2. 새 Snowflake 연결 정의를 추가합니다.

   예를 들어 계정 myaccount, 사용자 johndoe, 비밀번호 자격 증명, 데이터베이스 정보를 사용하여 myconnection 이라는 Snowflake 연결을 추가하려면 구성 파일에 다음 줄을 추가하십시오.

   [myconnection]
   account = "myaccount"
   user = "jdoe"
   password = "******"
   warehouse = "my-wh"
   database = "my_db"
   schema = "my_schema"
   

   Copy

   연결 정의는 Snowflake Python 커넥터 에서 제공되는 것과 동일한 구성 옵션을 지원합니다.

3. 선택 사항: 다음과 같이 연결을 더 추가합니다.

   [myconnection_test]
   account = "myaccount"
   user = "jdoe-test"
   password = "******"
   warehouse = "my-test_wh"
   database = "my_test_db"
   schema = "my_schema"
   

   Copy

4. 파일 변경 사항을 저장합니다.

5. Python 코드에서 다음과 유사하게 snowflake.connector.connect 에 대한 연결 이름을 입력합니다.

   with snowflake.connector.connect(
         connection_name="myconnection",
   ) as conn:
   

   Copy

   다음과 같이 connections.toml 파일의 연결에 대해 정의된 값을 재정의할 수도 있습니다.

   with snowflake.connector.connect(
         connection_name="myconnection",
         warehouse="test_xl_wh",
         database="testdb_2"
   ) as conn:
   

   Copy

기본 연결 설정하기¶

연결을 기본값으로 설정할 수 있으므로 Snowflake에 연결하려고 snowflake.connector.connect() 를 호출할 때마다 연결을 지정할 필요는 없습니다. 우선순위를 오름차순으로 나열한 다음 방법 중 하나로 기본 연결을 정의할 수 있습니다.

• default 라는 연결 정의를 만듭니다.

  1. connections.toml 파일에서 다음과 같이 연결 정의를 생성하고 이름을 default 로 지정합니다.

     [default]
     account = "myaccount"
     user = "jdoe-test"
     password = "******"
     warehouse = "my-test_wh"
     database = "my_test_db"
     schema = "my_schema"
     

     Copy

  2. 파일을 저장합니다.

• connections.toml 파일과 동일한 디렉터리에 있는 Snowflake config.toml 파일의 기본 연결로 명명된 연결을 지정합니다.

  1. 편집을 위해 config.toml 파일을 엽니다.

  2. 다음과 유사하게 default_connection_name 매개 변수를 설정합니다.

     default_connection_name = "myaccount"
     

     Copy

  3. 파일을 저장합니다.

• SNOWFLAKE_DEFAULT_CONNECTION_NAME 환경 변수를 설정합니다.

  경우에 따라 일반 기본 연결을 변경할 필요 없이 연결 테스트를 시도하는 등 일시적으로 기본 연결을 재정의할 수도 있습니다. 다음과 같이 SNOWFLAKE_DEFAULT_CONNECTION_NAME 환경 변수를 설정하여 connections.toml 및 config.toml 파일에 지정된 기본 연결을 재정의할 수 있습니다.

  SNOWFLAKE_DEFAULT_CONNECTION_NAME = myconnection_test
  

  Copy

기본 연결을 사용하려면 다음과 유사한 Python 코드를 실행하십시오.

with snowflake.connector.connect() as conn:
    with conn.cursor() as cur:
        print(cur.execute("SELECT 1;").fetchall())

Copy

인증에서 Single Sign-On(SSO) 사용하기¶

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

다단계 인증(MFA) 사용하기¶

Snowflake는 MFA 토큰 캐싱을 SSO와 결합하는 등의 캐싱 MFA 토큰을 지원합니다.

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

키 페어 인증 및 키 페어 순환 사용하기¶

Python Connector는 키 페어 인증 및 키 순환을 지원합니다.

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

1. 키 페어 인증 구성을 완료한 후에는 connect 함수에서 private_key 매개 변수를 개인 키 파일의 경로로 설정합니다.

2. 아래 샘플 코드를 수정하여 실행합니다. 이 코드는 개인 키 파일의 암호를 해독하여 Snowflake 드라이버로 전달하여 연결을 생성합니다.

• 보안 매개 변수를 업데이트합니다.

  • path: 생성한 개인 키 파일의 로컬 경로를 지정합니다.

• 연결 매개 변수 업데이트:

  • user: Snowflake 로그인 이름을 지정합니다.

  • account_identifier: 계정 식별자 를 지정합니다.

    자세한 내용은 account 매개 변수에 대한 사용법 노트(connect 메서드용) 섹션을 참조하십시오.

샘플 코드

import snowflake.connector
import os
from cryptography.hazmat.backends import default_backend
from cryptography.hazmat.primitives.asymmetric import rsa
from cryptography.hazmat.primitives.asymmetric import dsa
from cryptography.hazmat.primitives import serialization
with open("<path>/rsa_key.p8", "rb") as key:
    p_key= serialization.load_pem_private_key(
        key.read(),
        password=os.environ['PRIVATE_KEY_PASSPHRASE'].encode(),
        backend=default_backend()
    )

pkb = p_key.private_bytes(
    encoding=serialization.Encoding.DER,
    format=serialization.PrivateFormat.PKCS8,
    encryption_algorithm=serialization.NoEncryption())

ctx = snowflake.connector.connect(
    user='<user>',
    account='<account_identifier>',
    private_key=pkb,
    warehouse=WAREHOUSE,
    database=DATABASE,
    schema=SCHEMA
    )

cs = ctx.cursor()

Copy

프록시 서버 사용하기¶

프록시 서버를 사용하려면 다음 환경 변수를 구성합니다.

• HTTP_PROXY

• HTTPS_PROXY

• NO_PROXY

예:

Linux 또는 macOS

export HTTP_PROXY='http://username:password@proxyserver.company.com:80'
export HTTPS_PROXY='http://username:password@proxyserver.company.com:80'

Copy

Windows

set HTTP_PROXY=http://username:password@proxyserver.company.com:80
set HTTPS_PROXY=http://username:password@proxyserver.company.com:80

Copy

OAuth를 사용하여 연결하기¶

OAuth를 사용하여 연결하려면 연결 문자열에는 oauth 로 설정된 authenticator 매개 변수와 oauth_access_token 으로 설정된 token 매개 변수가 반드시 포함되어야 합니다. 자세한 내용은 클라이언트, 드라이버 및 커넥터 섹션을 참조하십시오.

ctx = snowflake.connector.connect(
    user="<username>",
    host="<hostname>",
    account="<account_identifier>",
    authenticator="oauth",
    token="<oauth_access_token>",
    warehouse="test_warehouse",
    database="test_db",
    schema="test_schema"
)

연결 시간 제한 관리하기¶

snowflake.connector.connect 를 호출하면 로그인 요청이 제출됩니다. 로그인 요청이 실패할 경우 커넥터는 연결 요청을 다시 보낼 수 있습니다. 다음 매개 변수는 커넥터가 요청 재시도를 중지하는 시간 제한을 설정합니다.

• login_timeout: 연결 요청을 계속해서 다시 보낼 시간(초)을 지정합니다. 해당 시간 내에 연결에 실패하면 커넥터가 로그인 요청을 계속 재시도하는 대신 현재 시도를 완료한 후 시간 제한 오류가 발생하며 실패합니다. 제한 시간이 지나면 더 이상의 재시도가 금지됩니다. 그러나 현재 진행 중인 시도는 자연스럽게 종료됩니다.

• network_timeout: cursor.execute 의 쿼리 요청과 같은 다른 요청에 대해 네트워크 문제가 해결될 때까지 기다리는 시간을 지정합니다. network_timeout 초 경과했을 때 현재 시도가 실패하면 시간 초과가 발생하고 해당 요청 재시도가 이루어지지 않습니다. network_timeout 초 경과 후에도 현재 시도를 마칠 수 있으며(자체적으로 실패함), 그 이후에는 시간 초과가 발생합니다.

• socket_timeout: 소켓 수준에서 연결 및 요청 시간 제한을 지정합니다.

다음 예에서는 SNOWFLAKE_JWT 인증자의 socket_timeout 을 재정의합니다.

# this request itself stops retrying after 60 seconds as it is a login request
conn = snowflake.connector.connect(
login_timeout=60,
network_timeout=30,
socket_timeout=10
)

# this request stops retrying after 30 seconds
conn.cursor.execute("SELECT * FROM table")

다음 예에서는 socket_timeout 을 큰 값으로 설정하는 효과를 보여줍니다.

# even though login_timeout is 1, connect will take up to n*300 seconds before failing
# (n depends on possible socket addresses)
# this issue arises because socket operations cannot be cancelled once started
conn = snowflake.connector.connect(
login_timeout=1,
socket_timeout=300
)

다음 예에서는 SNOWFLAKE_JWT 인증자의 소켓 시간 제한을 재정의하는 방법을 보여줍니다.

# socket timeout for login request overriden by env variable JWT_CNXN_WAIT_TIME
conn = snowflake.connector.connect(
authenticator="SNOWFLAKE_JWT",
socket_timeout=300
)

# socket timeout for this request is still 300 seconds
conn.cursor.execute("SELECT * FROM table")

MAX_CON_RETRY_ATTEMPTS 환경 변수는 로그인 요청의 최대 재시도 횟수를 제한합니다. 요청 시간이 초과되지 않았지만 최대 재시도 횟수에 이른 경우에는 요청이 즉시 실패합니다. 기본값은 1이며, 커넥터가 한 번만 재시도한다는 의미입니다.

재시도에 대한 연결 백오프 정책 관리하기¶

어떤 상황에서는 시간 제한으로 인해 실패한 요청을 재시도하려고 커넥터가 사용하는 속도나 빈도를 변경할 수도 있습니다. 예를 들어 동시에 매우 많은 시도가 발생하는 것을 발견한 경우 재시도 백오프 정책을 정의하여 이러한 요청을 분산할 수 있습니다. 백오프 정책은 재시도 간 대기 시간을 지정합니다.

Python용 Snowflake 커넥터는 Python 생성기 함수를 지정하는 backoff_policy 연결 매개 변수로 백오프 정책을 구현합니다. 생성기 함수를 사용하면 다음 재시도 요청을 보내기 전에 대기(백오프)하는 시간을 지정할 수 있습니다.

Snowflake는 원하는 매개 변수로 사전 정의된 생성기 함수를 생성하도록 다음과 같은 도우미를 제공합니다. 직접 만들고 싶지 않다면 다음을 사용할 수 있습니다.

• 반복할 때마다 백오프 지속 시간을 상수만큼 늘리는 linear_backoff.

• 반복할 때마다 백오프 지속 시간에 상수를 곱하는 exponential_backoff.

• exponential_backoff 를 사용하여 백오프 지속 시간을 늘리는 것과 반복할 때마다 백오프 지속 시간을 변경하지 않은 채로 그대로 두는 것 중에서 임의로 선택하는 mixed_backoff.

이러한 사전 정의된 생성기 함수는 다음 매개 변수를 사용하여 함수의 동작을 지정합니다.

• base: 초기 백오프 시간(초)입니다(기본값 = 1).

• factor: 백오프 시간을 늘리기 위한 계수입니다. 그 효과는 구현에 따라 다릅니다(기본값 = 2). linear_backup 은 값을 더하고 exponential_backup 은 값을 곱합니다.

• cap: 최대 백오프 시간(초)입니다(기본값 = 16).

• enable_jitter: 계산된 지속 시간에 대해 지터를 활성화할지 여부입니다(기본값 = True). 지수 백오프의 지터에 대한 자세한 내용은 AWS 지수 백오프 및 지터 문서를 참조하십시오.

예를 들어 다음과 같이 기본값 또는 사용자 지정 값으로 exponential_backoff 정책을 사용할 수 있습니다.

from snowflake.connector.backoff_policies import exponential_backoff

# correct, no required arguments
snowflake.connector.connect(
backoff_policy=exponential_backoff()
)

# correct, parameters are customizeable
snowflake.connector.connect(
backoff_policy=exponential_backoff(
    factor=5,
    base=10,
    cap=60,
    enable_jitter=False
  )
)

my_backoff_policy 생성기 함수를 정의하는 다음과 유사한 자체 백오프 정책 생성기 함수를 만들 수도 있습니다.

def my_backoff_policy() -> int:
  while True:
    # yield the desired backoff duration

그런 다음 아래와 같이 backoff_policy 연결 매개 변수를 생성기 함수의 이름으로 설정합니다.

snowflake.connector.connect(
  backoff_policy=constant_backoff
)

OCSP¶

드라이버가 연결되면 Snowflake는 Snowflake를 가장하는 호스트가 아니라 Snowflake에 연결되었음을 확인하는 인증서를 전송합니다. 드라이버는 해당 인증서를 OCSP(온라인 인증서 상태 프로토콜) 서버로 전송하여 인증서가 해지되지 않았는지 확인합니다.

드라이버가 인증서를 확인하기 위해 OCSP 서버에 연결할 수 없는 경우 드라이버는 《페일 오픈》 또는 《페일 클로즈》 메시지를 표시할 수 있습니다.

con = snowflake.connector.connect(
    account=<account_identifier>,
    user=<user>,
    ...,
    ocsp_fail_open=False,
    ...);