Snowflake接続の管理¶
Snowflake CLI を使用する前に、 Snowflake CLI がどのように Snowflake に接続するかを指定する接続を定義する必要があります。 Snowflake CLI は、接続パラメーターが複数の場所で定義されている場合にどの値を使用するかを決定するために、次の優先順位階層を使用します。
コマンドラインパラメーター
SNOWFLAKE_CONNECTIONS_MYCONNECTION_PASSWORD
などの、特定のconfig.toml
パラメーターを上書きする環境変数手動または
snow connection add
コマンドを使用してconfig.toml
ファイルに定義された接続SNOWFLAKE_USER
などの汎用環境変数。
また、 --temporary-connection
オプションを使用することもできます。この場合、 config.toml
で定義する必要はありません。
注意
セキュリティ向上のため、Snowflakeでは SNOWFLAKE_CONNECTIONS_<NAME>_PASSWORD
または SNOWFLAKE_PASSWORD
環境変数の使用を強く推奨しています。
コネクションの定義¶
接続定義は、以下のように config.toml
ファイルの [connections] セクションに保存されます。
[connections.myconnection]
account = "myaccount"
user = "jondoe"
password = "password"
warehouse = "my-wh"
database = "my_db"
schema = "my_schema"
接続定義は、 Snowflake Connector for Python と同じ構成オプションをサポートしています。さらに、ファイルの一番上にある default_connection_name
変数でデフォルトの接続を指定することができます。接続定義の中に含めることはできません。例:
default_connection_name = "myconnection"
[connections.myconnection]
account = "myaccount"
...
注釈
MacOS およびLinuxシステムの場合、 Snowflake CLI は、 config.toml
ファイルの権限を、ファイル所有者のみが読み取りおよび書き込みできるように制限する必要があります。ファイルに必要なファイルアクセス権を設定するには、次のコマンドを実行します。
chown $USER config.toml
chmod 0600 config.toml
代替構成ファイル¶
注釈
Snowflake CLI の場合、Snowflake は構成定義に config.toml
ファイルを使用することを推奨します。ただし、必要に応じて connections.toml
ファイルを使用することもできます。
Snowflake CLI は、 connections.toml
構成ファイルもサポートしています。このファイルは、 config.toml
ファイルと同じディレクトリに配置し、接続のみを含める必要があります。 connections.toml
の構成には、 connections
のない別のセクション名が必要です。例えば、 [connections.myconnection]
は、単に [myconnection]
となります。
注釈
config.toml
と connections.toml
の両方の構成に接続が含まれている場合、 Snowflake CLI は connections.toml
の構成のみを使用します。
snow connection
コマンドを使用して、Snowflake への接続を管理または追加します。¶
snow connection
コマンドを使用すると、Snowflake 接続を作成、管理、テストできます。
接続を追加します。¶
注釈
Snowflake Open Catalog用の接続を追加する必要がある場合は、Open Catalogドキュメントの Open Catalog用のSnowflake CLI 接続を作成する を参照してください。SSO を使用するようにOpen Catalogを構成するといったタスクのために、この接続を追加する必要があるかもしれません。
新しい接続を作成し、 構成ファイル に追加するには、以下のようにします。
snow connection add
コマンドを実行します。snow connection add
プロンプトが表示されたら、必要な接続、アカウント、ユーザー名のパラメーターと、その他必要なオプションのパラメーターを入力します。
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
注釈
--private_key_file
オプションが存在しないファイルを参照している場合など、コマンドがエラーで終了すると、接続は config.toml
設定ファイルに保存されません。
デフォルトでは、 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 Supportは、接続性の問題を解決するために、この情報を要求することもあります。
診断コレクションは、以下の snow connection test
コマンドオプションを使用します。
--enable-diag
で診断レポートを生成します。--diag-log-path
で、生成されるレポートの絶対パスを指定します。--diag-allowlist-path
で、 SYSTEM$ALLOWLIST() または SYSTEM$ALLOWLIST_PRIVATELINK() SQL コマンドの出力を含む JSON ファイルの絶対パスを指定します。このオプションは、接続で定義されたユーザーがシステム許可リスト関数を実行する権限を持っていない場合、またはアカウント 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サポートにレポートを提出し、追加サポートを受けることもできます。
デフォルト接続の設定¶
default_connection_name
構成ファイルと SNOWFLAKE_DEFAULT_CONNECTION_NAME
変数が設定されている場合は、それを上書きして、デフォルトとして使用する構成 Snowflake CLI を指定するために、 snow connection set-default
コマンドを使用できます。
次の例では、デフォルトの接続を myconnection2
に設定しています。
snow connection set-default myconnection2
Default connection set to: myconnection2
注釈
connections.toml
と config.toml
の両方のファイルが存在する場合、 Snowflake CLI は connections.toml
で定義された接続のみを使用します。
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.
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
注意
セキュリティ向上のため、Snowflakeでは SNOWFLAKE_CONNECTIONS_<NAME>_PASSWORD
または SNOWFLAKE_PASSWORD
環境変数の使用を強く推奨しています。
SnowSQL からの接続をインポートします。¶
SnowSQL で定義された既存の接続がある場合、 Snowflake CLI config.toml
の構成ファイルにインポートすることができます。その際には snow helpers import-snowsql-connections
コマンドを使用します。
SnowSQL 接続をインポートするには、以下のような snow helpers import-snowsql-connections
コマンドを入力します。
snow helpers import-snowsql-connections
以下の例では、標準構成ファイルの場所から SnowSQL 接続をインポートしています:
snow helpers import-snowsql-connections
コマンドは SnowSQL 構成ファイルを処理する際、進行状況を表示し、 Snowflake CLI config.toml
ファイルに同名の接続が既に定義されている場合は確認を求めます:
SnowSQL config file [/etc/snowsql.cnf] does not exist. Skipping.
SnowSQL config file [/etc/snowflake/snowsql.cnf] does not exist. Skipping.
SnowSQL config file [/usr/local/etc/snowsql.cnf] does not exist. Skipping.
Trying to read connections from [/Users/<user>/.snowsql.cnf].
Reading SnowSQL's connection configuration [connections.connection1] from [/Users/<user>/.snowsql.cnf]
Trying to read connections from [/Users/<user>/.snowsql/config].
Reading SnowSQL's default connection configuration from [/Users/<user>/.snowsql/config]
Reading SnowSQL's connection configuration [connections.connection1] from [/Users/<user>/.snowsql/config]
Reading SnowSQL's connection configuration [connections.connection2] from [/Users/<user>/.snowsql/config]
Connection 'connection1' already exists in Snowflake CLI, do you want to use SnowSQL definition and override existing connection in Snowflake CLI? [y/N]: Y
Connection 'connection2' already exists in Snowflake CLI, do you want to use SnowSQL definition and override existing connection in Snowflake CLI? [y/N]: n
Connection 'default' already exists in Snowflake CLI, do you want to use SnowSQL definition and override existing connection in Snowflake CLI? [y/N]: n
Saving [connection1] connection in Snowflake CLI's config.
Connections successfully imported from SnowSQL to Snowflake CLI.
詳細については、 snow helpers import-snowsql-connections コマンドリファレンスをご参照ください。
仮接続の使用¶
--temporary-connection [-x]
オプションを使用して、コマンドラインから接続パラメーターを指定することもできます。 config.toml
からのすべての定義を無視し、代わりにコマンドラインオプションで指定された定義を使用します。このアプローチは、構成ファイルを使用しない CI/CD ユースケースに役立ちます。仮接続を使用する場合、 Snowflake CLI は config.toml
ファイルで定義された接続変数を無視しますが、 環境変数 のうち、セットしたものは使用します。
SNOWFLAKE_ACCOUNT
SNOWFLAKE_USER
SNOWFLAKE_PASSWORD
SNOWFLAKE_DATABASE
SNOWFLAKE_SCHEMA
SNOWFLAKE_ROLE
SNOWFLAKE_WAREHOUSE
SNOWFLAKE_AUTHENTICATOR
SNOWFLAKE_PRIVATE_KEY_FILE
SNOWFLAKE_PRIVATE_KEY_RAW
SNOWFLAKE_PRIVATE_KEY_PATH
SNOWFLAKE_SESSION_TOKEN
SNOWFLAKE_MASTER_TOKEN
SNOWFLAKE_TOKEN_FILE_PATH
次の例は、ユーザー名とパスワードを使用して仮接続を作成する方法を示しています。この例では、パスワードを SNOWFLAKE_PASSWORD
環境変数に保存したと仮定しています。
snow sql -q "select 42;" --temporary-connection \
--account myaccount \
--user jdoe
select 42;
+----+
| 42 |
|----|
| 42 |
+----+
注意
セキュリティ向上のため、Snowflakeでは SNOWFLAKE_CONNECTIONS_<NAME>_PASSWORD
または SNOWFLAKE_PASSWORD
環境変数の使用を強く推奨しています。
さらなるセキュリティのために、次のように、 プライベートキーファイル を使用し、プライベートキーファイルへのパスを SNOWFLAKE_PRIVATE_KEY_FILE
環境変数に格納することができます。
SNOWFLAKE_ACCOUNT = "account"
SNOWFLAKE_USER = "user"
SNOWFLAKE_PRIVATE_KEY_FILE = "/path/to/key.p8"
その後、次のようにオプションを指定せずに仮接続を作成することができます。
snow sql -q "select 42" --temporary-connection
select 42;
+----+
| 42 |
|----|
| 42 |
+----+
CI/CD パイプラインをキーペア認証で使用している場合、ローカルのプライベートキーファイル(SNOWFLAKE_PRIVATE_KEY_FILE
)にアクセスできないことがあります。このような場合は、次のように SNOWFLAKE_PRIVATE_KEY_RAW
環境変数にプライベートキーを格納します。
SNOWFLAKE_ACCOUNT = "account"
SNOWFLAKE_USER = "user"
SNOWFLAKE_PRIVATE_KEY_RAW = "-----BEGIN PRIVATE KEY-----..."
その後、次のようにオプションを指定せずに仮接続を作成することができます。
snow sql -q "select 42" --temporary-connection
select 42;
+----+
| 42 |
|----|
| 42 |
+----+
注釈
SNOWFLAKE_PRIVATE_KEY_RAW
環境変数を使用する場合は、 SNOWFLAKE_PRIVATE_KEY_FILE
も定義しないでください。
接続を認証するその他の方法¶
また、以下の方法を使用して、Snowflakeへの接続を認証することもできます。
認証にプライベートキーファイルを使用する¶
認証にプライベートキーファイルを使用するには、接続構成で 認証コード
パラメーターを 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
構成ファイルを使用する。
[connections.jwt] account = "my_account" user = "jdoe" authenticator = "SNOWFLAKE_JWT" private_key_file = "~/sf_private_key.p8"
キーペア認証の設定の詳細については、 キーペア認証とキーペアローテーション をご参照ください。
Snowflake CLI は、以下の順序で接続パラメーターからプライベートキーを探します。
private_key_file
が指定された場合、 Snowflake CLI は指定されたファイルパスからキーを読み込みます。private_key_path
が指定された場合、 Snowflake CLI は指定されたファイルパスからキーを読み込みます。private_key_file
またはprivate_key_path
が指定されていない場合、 Snowflake CLI はprivate_key_raw
パラメーターから直接キーを読み込みます。
注意
private_key_raw
パラメーターにプライベートキーを指定する場合、Snowflakeではセキュリティを向上させるために SNOWFLAKE_CONNECTIONS_<NAME>_PRIVATE_KEY_RAW
または SNOWFLAKE_PRIVATE_KEY_RAW
環境変数の使用を推奨しています。
注釈
プライベートキーがパスフレーズで保護されている場合は、そのパスフレーズを PRIVATE_KEY_PASSPHRASE
環境変数に設定します。
認証に OAuth を使用する¶
OAuth を使って接続するには、以下のどちらかを行います。
snow connection add
コマンドで、--token-file-path
オプションを図のように指定します。snow connection add --token-file-path "my-token.txt"
config.toml
ファイルで、authenticator = "oauth"
を設定し、図のように接続定義にtoken_file_path
パラメーターを追加します。[connections.oauth] account = "my_account" user = "jdoe" authenticator = "oauth" token_file_path = "my-token.txt"
OAuth 2.0クライアント認証情報フローを使用する¶
OAuth 2.0クライアント認証情報フローは、Python用Snowflake Connectorがバックエンドサービスに接続するような、マシン間(M2M)認証のためのセキュアな方法を提供します。OAuth 2.0認証コードフローとは異なり、このメソッドはユーザー固有のデータに依存しません。このフローとパラメーターの詳細については、Python用Snowflake Connectorドキュメントの OAuth 2.0 クライアント認証フローを有効にします。 を参照してください。
OAuth 2.0クライアント認証情報フローを使用するには、以下のような接続定義を 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 を使用するには、
Snowflakeで 多要素認証 を設定し、
authenticator
パラメーターをsnowflake
(デフォルト値)に設定します。プッシュの代わりに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 キャッシュを有効にします。
ご使用のアカウントに、
ALLOW_CLIENT_MFA_CACHING = true
を設定します。ファイル
config.toml
で、接続にauthenticator = "username_password_mfa"
を追加します。
詳細については、 MFA トークンキャッシングを使用して認証中のプロンプトの数を最小限に抑える --- オプション をご参照ください。
SSO (シングルサインオン)を使用する¶
シングルサインオン(SSO)を使用するようにSnowflakeを構成 している場合、認証に SSO を使用するようにクライアントアプリケーションを構成できます。詳細は Snowflakeに接続するクライアントアプリケーションでの SSO の使用 を参照し、Python用の手順を使って接続を構成してください。
外部ブラウザーの使用¶
ブラウザーを使用して、OktaやActive Directory Federation Servicesなどの SAML 2.0準拠のアイデンティティプロバイダー(IdP)で Snowflake CLI 接続を認証できます。
注釈
externalbrowser
認証方式は、ウェブブラウザーにアクセスできるターミナルウィンドウでのみサポートされます。たとえば、SSH (Secure Shell)セッションを介してアクセスされるリモートマシン上のターミナルウィンドウでは、ウェブブラウザーを開くために追加の設定が必要になる場合があります。
ウェブブラウザーにアクセスできない場合でも、 IdP がOktaの場合は、認証方式を https://<Oktaアカウント名>.okta.com
に設定することでネイティブOktaを使用できます。
外部ブラウザー認証を使用するには、以下のいずれかの方法を使用します。
snow connection add --authenticator
コマンドオプションを使用します。snow connection add --authenticator externalbrowser
config.toml
ファイルのauthenticator
をexternalbrowser
にセットします。[connections.externalbrowser] account = "my_account" user = "jdoe" authenticator = "externalbrowser"
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 の詳細については、 認証のためのプログラム アクセス トークンの使用 をご参照ください。