ODBC 構成および接続パラメーター¶

必須の接続パラメーター¶

<名前> （データソース）

DSN の名前を指定します。

port （ポート）

ドライバーがSnowflake通信をリッスンするポートを指定します。

注釈

443 のデフォルトの Port 値を変更する必要はありません。

pwd （パスワード）

Snowflakeに接続するにはパスワードが必要です。ただし、セキュリティおよび認証上の理由により、 DSN 定義内にパスワード認証情報を直接保存することを強くお勧めします。

通常、認証情報は、Snowflakeへの接続を試行しているクライアントアプリケーションによってプログラムでドライバーに渡されます。

注釈

Windowsでは、 ODBC ドライバーは Data Source Administration ツールの Password フィールドを表示します。ただし、ドライバーはフィールドに入力された値を保存 しません 。代わりに、ドライバーは接続時にログイン認証情報を提供する必要があります。

server （サーバー）

アカウントの ホスト名 を次の形式で指定します。

account_identifier.snowflakecomputing.com

使用するアカウント識別子を決定するには、 Snowflakeに接続するためのクライアント、ドライバー、ライブラリ、またはサードパーティアプリケーションの構成 を参照してください。

uid （ユーザー）

認証するSnowflakeユーザーのログイン名を指定します。

オプションの接続パラメーター¶

BROWSER_RESPONSE_TIMEOUT

外部ブラウザーで認証応答を待つ秒数を指定します。

デフォルトは120です。

CLIENT_OUT_OF_BAND_TELEMETRY_ENABLED=<Boolean>

アウトオブバンドテレメトリを有効にするかどうかを指定します。

デフォルトは true です

CLIENT_SESSION_KEEP_ALIVE=<Boolean>

非アクティブな状態が一定時間続いた後、現在のセッションをアクティブのままにするか、ユーザーに再度ログインさせるかを指定します。値が true の場合、Snowflakeは、ユーザーからのアクティビティがない場合でも、セッションを無期限にアクティブに保ちます。値が false の場合、ユーザーは4時間の非アクティブ後に再度ログインする必要があります。

デフォルトは false です。

database （データベース）

ドライバーによって開始されたセッションに使用するデフォルトのデータベースを指定します。

disableSamlUrlCheck

SAML URLs の検証を無効にするかどうかを指定します。デフォルトでは、ドライバーは SAML URLs を検証します。

デフォルトは false です。

maxHttpRetries （データベース）

HTTP リクエストに失敗したクエリに対して、エラーを返すまでの HTTP の最大再試行回数を指定します。maxHttpRetries=0 に設定すると再試行制限が解除されますが、その場合は、失敗した HTTP 呼び出しをドライバーが無限に再試行する危険があります。

デフォルト値は7です。

role （ロール）

ドライバーによって開始されたセッションに使用する既定のロールを指定します。指定されたロールは、ドライバーの指定されたユーザーに割り当てられたロールでなければなりません。指定されたロールがユーザーに割り当てられたロールのいずれとも一致しない場合、ドライバーによって開始されたセッションには最初はロールがありません。ただし、ロールはセッション内からいつでも指定できます。

schema （スキーマ）

ドライバーによって開始されたセッションに使用するデフォルトのスキーマを指定します。

デフォルトは public です。

SecondaryRoles （ロール）

ドライバーによって開始されたセッションに使用するセカンダリロールを指定します。ロールは、ドライバーの指定されたユーザーにすでに付与されている必要があります。セカンダリロールは、 USE SECONDARY ROLES コマンドを使用して、ユーザーセッション内からアクティブ化することもできます。

可能な値は次のとおりです。

• すべて: ユーザーに付与されたすべてのロール。

• なし: ロールの許可なし（セカンダリロールを無効化）。

tracing （トレース）

ドライバートレースファイルに記録される詳細レベル：

• 0 = トレースの無効化

• 1 = 致命的なエラーのみトレース

• 2 = エラートレース

• 3 = 警告トレース

• 4 = 情報トレース

• 5 = デバッグトレース

• 6 =詳細トレース

warehouse （ウェアハウス）

ドライバーによって開始されたセッションに使用するデフォルトのウェアハウスを指定します。

Certificate revocation list (CRL) options¶

These options are available in driver versions 3.13.0 and later.

CRL_CHECK

Specifies whether to enable or disable CRL checking. When set to true, the driver checks the CRL to verify the server certificate has not been revoked. The connection fails if the server's certificate is revoked or another revocation check issue (such as downloading or parsing) occurs.

デフォルトは false です。

CRL_ADVISORY

Modifies the CRL connection checking to fail only when the certificate is revoked explicitly. When any other problem (such as parsing errors or download errors) is present, the connection is allowed.

デフォルトは false です。

CRL_ALLOW_NO_CRL

Specifies whether to allow connections when no CRL is found. When set to true, the driver allows connections when no CRL is found.

デフォルトは false です。

CRL_DISK_CACHING

Specifies whether to enable or disable disk caching of CRLs. When set to true, the driver caches CRLs on disk, which reduces the time spent re-downloading the certificate distribution lists.

The driver stores the cached CRLs in the following directories:

• MacOS: $HOME/Library/Caches/Snowflake/crls

• Linux: $HOME/.cache/snowflake/crls

• Windows: %LOCALAPPDATA%SnowflakeCachescrls

Default is true.

You can override the default disk cache location by setting the SF_CRL_RESPONSE_CACHE_DIR environment variable.

CRL_MEMORY_CACHING

Specifies whether to enable or disable memory caching of CRLs. When set to true, the driver caches CRLs in memory.

Default is true.

CRL_DOWNLOAD_TIMEOUT

Specifies the timeout, in seconds, for downloading CRLs. If the download does not complete within the specified time, the connection fails.

Default is 120 (seconds).

追加の接続パラメーター¶

allowEmptyProxy

以下のセクションで説明するように、 proxy と no_proxy 接続パラメーターに空の値を許可するかどうかを指定します。

• Using connection parameters

• Using configuration parameters

• Using environment variables

この値を設定すると、以下のような効果が得られます。

• true: ドライバーは空のプロキシ値を有効なプロキシ設定として扱い、既存の設定や環境変数を上書きします。

• false: ドライバーは空のプロキシ値を無視し、指定された構成パラメータまたは環境変数を使用します。

デフォルトは true です。

application

Snowflakeパートナーによる使用のみ ： ODBC を介して接続するパートナーアプリケーションの名前を指定します。

このパラメーターは、 SQLSetConnectAttr() 関数を呼び出すことでも設定できます。詳細については、 Snowflake固有のSQLSetConnectAttr 関数の動作 をご参照ください。

authenticator

ユーザーのログイン認証情報の確認に使用する認証方式を指定します。

• snowflake （デフォルト）は、内部Snowflake認証方式を使用します。

• externalbrowser から 自分のウェブブラウザーを使用 して、Okta、AD FS、またはアカウントのために定義されている他の SAML 2.0準拠の識別プロバイダー（IdP）を認証します。

  注釈

  Snowflake ODBC ドライバーは、Microsoft Excelと MacOS を使用した externalbrowser 認証をサポートしていません。

• https://<okta_account_name>.okta.com （つまり、ご使用のOktaの URL エンドポイント）から ネイティブOktaを介して認証 します（IdP がOktaの場合にのみサポート）。

• OAuthを使用して認証する oauth。OAuth が認証コードとして指定されている場合は、 OAuth トークンを指定するために token パラメーターも設定する必要があります（ 以下を参照）。

• username_password_mfa は MFA トークンキャッシングで認証します。詳細については、 多要素認証の使用 （このトピック内）をご参照ください。

• oauth_authorization_code Webブラウザーと選択したIDプロバイダー（IdP としてSnowflakeを含む）で、 OAuth 認証コードを使用して手動で認証します。詳細については、 OAuth 2.0 認証コードフローの使用 をご参照ください。

• oauth_client_credentials 選択したIDプロバイダーで OAuth クライアント認証を使用して自動的に認証します（Snowflakeは IdP として、クライアント認証フローをサポートしていません）。詳細については、 OAuth 2.0 クライアント認証フローの使用 をご参照ください。

• programmatic_access_token は、プログラムアクセストークン（PAT）で認証します。

• ワークロードIDフェデレーション（WIF） 認証コードで認証するための:codenowrap:workload_identity。

デフォルトは snowflake です。

Windowsでは、 ODBC データソース管理ツール を使用してこのパラメーターを設定できます。

認証の詳細については、 フェデレーション認証の管理/使用 および クライアント、ドライバー、およびコネクタ をご参照ください。

default_binary_size、 . default_varchar_size

サイズが不明な BINARY または VARCHAR 列から値を取得および変換するときに、ドライバーが使用するデフォルトサイズをバイト単位で指定します。これらの型の列から値を取得するときにこれを設定します。

デフォルトでは、ドライバーは、サイズが決定されていない列の値を取得するためにメモリを割り当てるときに、デフォルトのサイズとして 67108864 （BINARY 列の場合）および 134217728 （VARCHAR 列の場合）を使用します。

これらの値に割り当てられるメモリの量を減らすために、 default_binary_size と default_varchar_size をこれらの型の列にある値の最大サイズに設定できます。

注釈

これらの値を設定すると、実装行記述子（IRD）の SQL_DESC_LENGTH フィールドと、 SQLDescribeCol/SQLColAttribute/SQLColAttributes から返される対応する値のみが変更されます。長さが設定を超えても、ドライバーはデータ全体を返します。

一方、アプリケーションは、これらのパラメーターで指定された長さに基づいてデータバッファーを割り当てることができ、バッファー内のスペースが不足していると、データが切り捨てられる可能性があります。ベストプラクティスとして、Snowflakeは、メモリの使用量を大幅に削減し、データ切り捨ての可能性を最小化するため、元のデフォルト値の134217728/67108864バイトの代わりに、通常のデータの最大サイズ（例：4000または8000バイト）よりも大きめのデフォルトサイズに設定することをお勧めします。

これらの設定を使用して、SnowflakeデータベースでMicrosoft OLE DB プロバイダー（MSDASQL）を使用するときに発生する可能性がある、次のエラーを回避することもできます。

Requested conversion is not supported
Cannot get the current row value of column

Copy

これらのパラメーターは、接続 構成パラメーター として指定できます（たとえば、 macOS およびLinux の simba.snowflake.ini において）。これが接続パラメーター および 構成パラメーターの両方として設定されている場合は、 DSN （または接続文字列）の接続パラメーターが優先されます。

これらのパラメーターは、 ODBC ドライバーのバージョン2.23.2で導入されました。

get_size_threshold

GET コマンドでファイルをダウンロードするときに、ファイルを小さな部分に分割する最小ファイルサイズをメガバイト（MB）単位で指定します。このしきい値より小さいサイズのファイルは、マルチパートダウンロードを使用しません。

デフォルトは 5 （MB）です。

注釈

この値を接続パラメーターとして設定すると、対応する しきい値サイズ取得 構成パラメーターの値が上書きされます。

login_timeout

ログイン失敗エラーを返す前に、Snowflakeサービスに接続する際の応答を待機する時間を秒単位で指定します。

デフォルトは 300 （秒）です。

network_timeout

Snowflakeサービスと対話するときにエラーを返すまでの応答を待機する時間を秒単位で指定します。ゼロ（0）は、ネットワークタイムアウトが設定されていないことを示します。

デフォルトは 0 （秒）です。

retryTimeout

失敗した HTTP リクエストのあるクエリから HTTP の再試行エラーを返すまでの待機時間を秒単位で指定します。ゼロ（0）は、再試行タイムアウトが設定されていないことを示します。

デフォルトは 300 （秒）です。

no_proxy

プロキシサーバーのバイパスを許可するホスト名の末尾を指定します（例： no_proxy=.amazonaws.com は、Amazon S3アクセスがプロキシを通過する必要がないことを意味）。

このパラメーターはワイルドカードをサポートしていません。指定する各値は、次のいずれかである必要があります。

• ホスト名の末尾（または完全なホスト名）。例：

  • .amazonaws.com

  • myorganization-myaccount.snowflakecomputing.com

• IP アドレス。例：

  • 192.196.1.15

複数の値を指定する場合、値はコンマで区切る必要があります。次に例を示します。

no_proxy=localhost,.example.com,myorganization-myaccount.snowflakecomputing.com,192.168.1.15,192.168.1.16

Copy

注釈

このパラメーターはプロセスに適用されます。別の接続が同じプロセスを共有する場合、プロキシ設定は同一である必要があります。そうでない場合、動作は予測できません。

odbc_use_standard_timestamp_columnsize

このブール値パラメーターは、 SQL_TYPE_TIMESTAMPに対して返される列サイズ（文字数）に影響します。このパラメーターをtrueに設定すると、ドライバーは ODBC 標準に従って29を返します。このパラメーターを false に設定すると、ドライバーは35を返します。これにより、タイムゾーンオフセット用のスペースが許可されます（例: 「-08:00」）。

この値は、odbc.iniファイル（LinuxまたはmacOS）またはMicrosoft Windowsレジストリだけでなく、接続文字列経由でも設定できます。

デフォルトは false です。

passcode

多要素認証に使用するパスコードを指定します。

多要素認証の詳細については、 多要素認証（MFA） をご参照ください。

passcodeInPassword

多要素認証のパスコードをパスワードに追加するかどうかを指定します。

• on （または true）は、パスコードが追加されることを指定します。

• off （または false）またはその他の値は、パスコードが追加されないことを指定します。

デフォルト値は off です。

proxy

ODBC からのすべての通信がプロキシサーバーを使用するように、プロキシサーバー URL を http://<ホスト名>:<ポート>/ または <ホスト名>:<ポート番号> の形式で指定します。

注釈

このパラメーターはプロセスに適用されます。別の接続が同じプロセスを共有する場合、プロキシ設定は同一である必要があります。そうでない場合、動作は予測できません。

put_compresslv

ODBC ドライバーが PUT コマンドによりデータを転送するときに使用する圧縮率を指定します。このパラメーターは、デフォルトのgzip圧縮レベルを上書きします。put_compresslv を指定しない場合、 ODBC ドライバーはデフォルトの圧縮レベルを使用します。

有効な値は、 -1 から 9 です。デフォルト値は -1 で、デフォルトの Z_DEFAULT_COMPRESSION を指定します。

値 0 から 9 は、カスタム圧縮率を指定します。0 により、 ODBC ドライバーはより低い圧縮率を使用し、 9 はより高い圧縮率を使用します。より高い圧縮率を使用すると、データ転送速度が遅くなります。

このパラメーターは、 構成パラメーター として指定することもできます（例: macOS およびLinux の simba.snowflake.ini 内）。これが接続パラメーター および 構成パラメーターの両方として設定されている場合は、 DSN （または接続文字列）の接続パラメーターが優先されます。

このパラメーターは、 ODBC ドライバーのバージョン2.23.3で導入されました。

put_fastfail

PUT コマンドとワイルドカード文字を使用して一度に複数のファイルをアップロードし、エラーが発生したときにドライバーがファイルのアップロードを停止するようにする場合は、これを true に設定します。

デフォルト値は false です。これは、1つのファイルでエラーが発生した場合、ドライバーは残りのファイルのアップロードを続行することを意味します。

このパラメーターは、 ODBC ドライバーのバージョン2.22.3で導入されました。

ODBC ドライバーのバージョン2.22.5では、このパラメーターを 構成パラメーター として指定することもできます（たとえば、 macOS およびLinux の simba.snowflake.ini 内）。これが接続パラメーター および 構成パラメーターの両方として設定されている場合は、 DSN （または接続文字列）の接続パラメーターが優先されます。

put_maxretries

コマンドが失敗した場合に、ドライバーが PUT コマンドを再試行する回数を指定します。

デフォルト値は 5 です。

このパラメーターの有効な値の範囲は 0 から 100 です。この範囲外の値を指定すると、ドライバーはデフォルト値の 5 を使用します。

このパラメーターは、 ODBC ドライバーのバージョン2.22.3で導入されました。

ODBC ドライバーのバージョン2.22.5では、このパラメーターを 構成パラメーター として指定することもできます（たとえば、 macOS およびLinux の simba.snowflake.ini 内）。これが接続パラメーター および 構成パラメーターの両方として設定されている場合は、 DSN （または接続文字列）の接続パラメーターが優先されます。

put_tempdir

PUT コマンドリクエストに使用する一時ディレクトリを指定します。ドライバーは、この一時ディレクトリを使用して一時圧縮ファイルを作成してから、それらのファイルをSnowflakeにアップロードします。

このパラメーターが設定されていない場合、ドライバーは、一時ディレクトリ /tmp/snowflakeTmp_username を作成して使用します。ここで、 username は、オペレーティングシステムにおける現在のユーザーのユーザー名です。

このパラメーターは、 構成パラメーター として指定することもできます（例: macOS およびLinux の simba.snowflake.ini 内）。これが接続パラメーター および 構成パラメーターの両方として設定されている場合は、 DSN （または接続文字列）の接続パラメーターが優先されます。

このパラメーターは、 ODBC ドライバーのバージョン2.23.1で導入されました。

token=<文字列>

OAuth または PAT 認証のトークンを指定します。<string> がトークンです。このパラメーターは、 authenticator=oauth または authenticator=programmatic_access_token のパラメーターが設定されている場合にのみ必要です。

デフォルトはありません。

query_timeout

エラーを返す前に、クエリが完了するまで待機する時間を秒単位で指定します。ゼロ（0）は無期限に待機することを示します。

デフォルトは 0 （秒）です。

validateSessionParam

次の セッション接続パラメーター のいずれかが無効な場合の応答方法を指定します。

enable_connection_diag

コネクタが接続診断レポートを生成するかどうかを指定します。

デフォルトは false です。

connection_diag_log_path

接続レポートが保存される絶対パスを指定します。

enable_connection_diag が true の場合にのみ有効です。

例: connection_diag_log_path=C:\\reports

connection_diag_allowlist_path

SYSTEM$ALLOWLIST() または SYSTEM$ALLOWLIST_PRIVATELINK() の出力を含む JSON ファイルへの絶対パスを指定します。

enable_connection_diag が true の場合にのみ有効です。

例: connection_diag_log_path=C:\\allowlist.json

OAUTH_CLIENT_ID

IDプロバイダーがSnowflake統合用に提供する client id の値（Snowflakeセキュリティ統合メタデータ）。

デフォルト：LOCAL_APPLICATION。

OAUTH_CLIENT_SECRET

IDプロバイダーがSnowflake統合用に提供する client secret の値（Snowflakeセキュリティ統合メタデータ）。

デフォルト：LOCAL_APPLICATION。

OAUTH_AUTHORIZATION_URL

認証コードをドライバーに提供する ID プロバイダーエンドポイント。SnowflakeをIDプロバイダーとして使用する場合、この値は server または account パラメーターから取得されます。

OAUTH_TOKEN_REQUEST_URL

ドライバーにアクセストークンを供給する ID プロバイダーのエンドポイント。SnowflakeをIDプロバイダーとして使用する場合、この値は server または account パラメーターから取得されます。

OAUTH_SCOPE

ID プロバイダー承認リクエストで要求された範囲。デフォルトでは、ロールから派生します。複数のスコープが必要な場合、値はスペースで区切られた複数のスコープのリストでなければなりません。

OAUTH_REDIRECT_URI

認証コードリダイレクトに使用する URI （Snowflakeセキュリティ統合メタデータ）。デフォルト： http://127.0.0.1:{randomAvailablePort}。

:codenowrap：WORKLOAD_IDENTITY_PROVIDER

ワークロードIDプロバイダーのプラットフォーム。可能な値は次のとおりです。AWS、 AZURE、 GCP および:codenowrap:OIDC。

PRIV_KEY_BASE64

Base64でエンコードされたプライベートキー。

:codenowrap：PRIV_KEY_PWD

Base64でエンコードされたプライベートキーのパスワード。

接続パラメーターの使用¶

プロキシサーバー経由で接続するには、次の接続パラメーターを DSN に追加します。

• proxy

• no_proxy

例:

[connection]
Description = SnowflakeDB
Driver      = SnowflakeDSIIDriver
Locale      = en-US
server      = myorganization-myaccount.snowflakecomputing.com
proxy       = http://proxyserver.company:80
no_proxy    = .amazonaws.com

Copy

パラメーターの説明については、 接続パラメーター をご参照ください。

構成パラメーターの使用¶

プロキシサーバー経由で接続するには、次の構成パラメーターを追加します。

• Proxy

• NoProxy

パラメーターの説明については、 構成パラメーター をご参照ください。

環境変数の使用¶

プロキシサーバー経由で接続するには、次の環境変数を構成します。

• http_proxy

• https_proxy

• no_proxy

例:

• Linuxまたは macOS：

  export http_proxy=http://proxyserver.example.com:80
  export https_proxy=http://proxyserver.example.com:80
  

  Copy

  プロキシサーバーでユーザー名とパスワードが必要な場合は、認証情報を含めます。たとえば、

  export https_proxy=http://username:password@proxyserver.example.com:80
  

  Copy

• Windows：

  set http_proxy=http://proxyserver.example.com:80
  set https_proxy=http://proxyserver.example.com:80
  

  Copy

  プロキシサーバーでユーザー名とパスワードが必要な場合は、認証情報を含めます。たとえば、

  set https_proxy=http://username:password@proxyserver.example.com:80
  

  Copy

オプション: 特定の通信でプロキシをバイパスするには、 no_proxy をセットします（たとえば、Amazon S3 アクセスをバイパスするには、 no_proxy=.amazonaws.com を使用します）。

ログ構成ファイル¶

あるいは、 sf_client_config.json 構成ファイルでログレベルとログファイルを保存するディレクトリを簡単に指定することもできます。

この構成ファイルは、 JSON を使用して、 log_level と log_path のログパラメーターを以下のように定義します。

{
  "common": {
    "log_level": "DEBUG",
    "log_path": "/home/user/logs"
  }
}

ドライバーは、以下の順序で構成ファイルの場所を検索します。

• client_config_file には構成ファイルへの完全なパスが含まれます。

• SF_CLIENT_CONFIG_FILE 環境変数。構成ファイルへの完全なパスが含まれます。

• ODBC ドライバーのインストールディレクトリ。ファイル名は sf_client_config.json にする必要があります。

• ユーザーのホームディレクトリ。ファイル名は sf_client_config.json にする必要があります。