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

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

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

DSN の名前を指定します。

port （ポート）

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

注釈

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

pwd （パスワード）

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

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

注釈

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

server （サーバー）

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

account_identifier.snowflakecomputing.com

アカウント識別子については、 アカウント識別子 をご参照ください。

uid （ユーザー）

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

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

BROWSER_RESPONSE_TIMEOUT

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

デフォルトは120です。

CLIENT_OUT_OF_BAND_TELEMETRY_ENABLED=<ブール値>

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

デフォルトは true です

CLIENT_SESSION_KEEP_ALIVE=<ブール値>

非アクティブな状態が一定時間続いた後、現在のセッションをアクティブのままにするか、ユーザーに再度ログインさせるかを指定します。値が 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 （ウェアハウス）

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

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

allowEmptyProxy

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

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

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

• 環境変数の使用

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

• 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のアカウント名>.okta.com （つまり、ご使用のOktaのURLエンドポイント）から ネイティブOktaを介して認証 します（IdPがOktaの場合にのみサポート）。

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

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

デフォルトは snowflake です。

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

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

default_binary_size、 . default_varchar_size

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

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

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

注釈

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

一方、アプリケーションは、これらのパラメーターで指定された長さに基づいてデータバッファーを割り当てることができ、バッファー内のスペースが不足していると、データが切り捨てられる可能性があります。ベストプラクティスとして、Snowflakeは、メモリの使用量を大幅に削減し、データ切り捨ての可能性を最小化するため、元のデフォルト値の16777216/8388608バイトの代わりに、通常のデータの最大サイズ（例: 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,.my_company.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で導入されました。

query_timeout

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

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

token=<文字列>

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

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

validateSessionParam

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

• database
• schema
• warehouse

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

• false （デフォルト）: 正常に接続しますが、 database および schema のパラメーター値を空の文字列に設定し、 warehouse パラメーターをデフォルト値に設定します。ウェアハウスの詳細については、 セッションでのウェアハウスの使用 をご参照ください。

• true: 接続を拒否し、エラーをスローします。

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

プロキシサーバー経由で接続するには、次の接続パラメーターを 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.company.com:80
  export https_proxy=http://proxyserver.company.com:80
  

  Copy

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

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

  Copy

• Windows：

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

  Copy

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

  set https_proxy=http://username:password@proxyserver.company.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 にする必要があります。