Konfigurations- und Verbindungsparameter für ODBC¶

Erforderliche Verbindungsparameter¶

<Name> (Datenquelle)

Gibt den Namen Ihres DSN an.

port (Port)

Gibt den Port an, an dem der Treiber die Snowflake-Kommunikation abhört.

Bemerkung

Sie müssen den Standardwert Port von 443 nicht ändern.

pwd (Kennwort)

Für die Verbindung zu Snowflake ist ein Kennwort erforderlich. Aus Sicherheits- und Authentifizierungsgründen rät Snowflake jedoch dringend davon ab, Kennwort-Anmeldeinformationen direkt innerhalb einer DSN-Definition zu speichern.

Normalerweise werden die Anmeldeinformationen von der Clientanwendung, die sich mit Snowflake zu verbinden versucht, programmgesteuert an den Treiber übergeben.

Bemerkung

Unter Windows zeigt der ODBC-Treiber ein Feld Password im Data Source Administration-Tool an, der Treiber speichert jedoch keine in das Feld eingegebenen Werte. Stattdessen verlangt der Treiber, dass zur Verbindungszeit Anmeldeinformationen bereitgestellt werden.

server (Server)

Gibt den Hostnamen für Ihr Konto im folgenden Format an:

account_identifier.snowflakecomputing.com

Um den zu verwendenden Kontobezeichner zu bestimmen, siehe Konfigurieren eines Clients, eines Treibers, einer Bibliothek oder einer Anwendung eines Drittanbieters für die Verbindung mit Snowflake.

uid (Benutzer)

Gibt den Anmeldenamen des Snowflake-Benutzers an, der authentifiziert werden soll.

Optionale Verbindungsparameter¶

BROWSER_RESPONSE_TIMEOUT

Gibt die Anzahl der Sekunden an, die in einem externen Browser auf eine Authentifizierungsantwort gewartet werden soll.

Der Standardwert ist 120.

CLIENT_OUT_OF_BAND_TELEMETRY_ENABLED=<Boolesch>

Gibt an, ob die Out-of-Band-Telemetrie aktiviert werden soll.

Standard ist true

CLIENT_SESSION_KEEP_ALIVE=<Boolesch>

Gibt an, ob die aktuelle Sitzung nach einer Zeit der Inaktivität aktiv bleiben soll oder ob der Benutzer gezwungen werden soll, sich erneut anzumelden. Wenn der Wert true ist, hält Snowflake die Sitzung auf unbestimmte Zeit aktiv, auch wenn es keine Aktivität des Benutzers gibt. Wenn der Wert false ist, muss sich der Benutzer nach vier Stunden Inaktivität erneut anmelden.

Der Standardwert ist false.

database (Datenbank)

Gibt die Standarddatenbank an, die für vom Treiber initiierte Sitzungen verwendet werden soll.

disableSamlUrlCheck

Gibt an, ob die Überprüfung für SAML URLs deaktiviert werden soll. Standardmäßig verifiziert der Treiber SAML URLs.

Der Standardwert ist false.

maxHttpRetries (Datenbank)

Gibt die maximale Anzahl der HTTP-Wiederholungsversuche bei Abfragen mit fehlgeschlagenen HTTP-Anforderungen an, bevor ein Fehler zurückgegeben wird. Durch die Einstellung maxHttpRetries=0 wird das Limit für die Wiederholungsversuche aufgehoben. Dabei besteht jedoch die Gefahr, dass der Treiber fehlgeschlagene HTTP-Anforderungen unendlich oft wiederholt.

Der Standardwert ist 7.

role (Rolle)

Gibt die Standardrolle an, die für vom Treiber initiierte Sitzungen verwendet werden soll. Die angegebene Rolle sollte eine Rolle sein, die dem angegebenen Benutzer für den Treiber zugeordnet wurde. Wenn die angegebene Rolle mit keiner der dem Benutzer zugeordneten Rollen übereinstimmt, haben vom Treiber initiierte Sitzungen zunächst keine Rolle. Eine Rolle kann jedoch immer innerhalb der Sitzung angegeben werden.

schema (Schema)

Gibt das Standardschema an, das für vom Treiber initiierte Sitzungen verwendet werden soll.

Der Standardwert ist public.

SecondaryRoles (Rolle)

Gibt die Sekundärrolle an, die für vom Treiber initiierte Sitzungen verwendet werden soll. Die Rollen müssen dem angegebenen Benutzer für den Treiber bereits zugewiesen sein. Sekundärrollen können auch innerhalb einer Benutzersitzung mit dem Befehl USE SECONDARY ROLES aktiviert werden.

Mögliche Werte sind:

• All: Alle dem Benutzer zugewiesenen Rollen.

• None: Keine Rollen erlaubt (deaktiviert die Sekundärrollen).

tracing (Ablaufverfolgung)

Der Detaillierungsgrad, der in den Ablaufverfolgungsdateien für Treiber protokolliert werden soll:

• 0 = Ablaufverfolgung deaktivieren

• 1 = Nur Ablaufverfolgung schwerwiegender Fehler

• 2 = Ablaufverfolgung von Fehlern

• 3 = Ablaufverfolgung von Warnungen

• 4 = Ablaufverfolgung von Informationen

• 5 = Debug-Ablaufverfolgung

• 6 = Detaillierte Ablaufverfolgung

warehouse (Warehouse)

Gibt das Standard-Warehouse an, das für vom Treiber initiierte Sitzungen verwendet werden soll.

Zusätzliche Verbindungsparameter¶

allowEmptyProxy

Gibt an, ob leere Werte für die Verbindungsparameter proxy und no_proxy zugelassen werden sollen, wie in den folgenden Abschnitten beschrieben:

• Verwenden von Verbindungsparametern

• Verwenden von Konfigurationsparametern

• Verwenden von Umgebungsvariablen

Das Einstellen der Werte hat die folgenden Auswirkungen:

• true: Der Treiber behandelt leere Proxy-Werte als gültige Proxy-Einstellungen und überschreibt alle vorhandenen Einstellungen oder Umgebungsvariablen.

• false: Der Treiber ignoriert leere Proxy-Werte und verwendet die angegebenen Konfigurationsparameter oder Umgebungsvariablen.

Der Standardwert ist true.

application

Snowflake partner use only: Gibt den Namen einer Partneranwendung an, die über ODBC verbunden werden soll.

Dieser Parameter kann auch durch Aufrufen der Funktion SQLSetConnectAttr() festgelegt werden. Weitere Informationen dazu finden Sie unter Snowflake-spezifisches Verhalten der SQLSetConnectAttr-Funktion.

authenticator

Gibt den Authentifikator an, der für die Überprüfung der Anmeldeinformationen des Benutzers verwendet werden soll:

• snowflake (Standard), um den internen Snowflake-Authentifikator zu verwenden.

• externalbrowser, um den für Ihr Konto definierten Webbrowser für die Authentifizierung mit Okta, AD FS oder einem anderen SAML 2.0-kompatiblen Identitätsanbieter (IdP) zu verwenden.

  Bemerkung

  Der Snowflake-ODBC-Treiber unterstützt keine externalbrowser-Authentifizierung mit Microsoft Excel unter MacOS.

• https://<Name_des_Okta-Kontos>.okta.com (d. h. der URL-Endpunkt für Okta) zum Authentifizieren über das systemeigene Okta (nur unterstützt, wenn Ihr IdP Okta ist).

• oauth zum Authentifizieren mit OAuth. Wenn OAuth als Authentifikator angegeben ist, müssen Sie auch den Parameter token festlegen, um das OAuth-Token anzugeben (siehe unten).

• username_password_mfa zum Authentifizieren mit MFA-Tokencaching. Weitere Informationen dazu finden Sie unter Verwenden der mehrstufigen Authentifizierung (unter diesem Thema).

Der Standardwert ist snowflake.

Unter Windows können Sie mit dem ODBC Data Source Administration-Tool verwenden, um diesen Parameter einzustellen.

Weitere Informationen zur Authentifizierung finden Sie unter Verwenden und Verwalten der Verbundauthentifizierung und Clients, Treiber und Konnektoren.

default_binary_size, . default_varchar_size

Gibt die Standardgröße in Byte an, die der Treiber beim Abrufen und Konvertieren von Werten aus BINARY- oder VARCHAR-Spalten mit unbestimmter Größe verwendet. Stellen Sie dies ein, wenn Sie Werte aus diesen Spaltentypen abrufen.

Standardmäßig verwendet der Treiber 8388608 (für BINARY-Spalten) und 16777216 (für VARCHAR-Spalten) als Standardgrößen, wenn er Speicher für das Abrufen des Wertes einer Spalte unbestimmter Größe zuweist.

Um den für diese Werte zugewiesenen Speicherplatz zu reduzieren, können Sie default_binary_size und default_varchar_size auf die maximale Größe der Werte in Spalten dieses Typs einstellen.

Bemerkung

Durch Einstellen dieser Werte werden nur das Feld SQL_DESC_LENGTH im Implementation Row Descriptor (IRD) und die entsprechenden Werte geändert, die von SQLDescribeCol/SQLColAttribute/SQLColAttributes zurückgegeben werden. Der Treiber gibt immer noch die gesamten Daten zurück, auch wenn die Länge der Daten die Einstellung überschreitet.

Andererseits könnte eine Anwendung einen Datenpuffer auf der Grundlage der in diesen Parametern angegebenen Länge zuweisen, wodurch die Daten abgeschnitten werden könnten, weil der Platz im Puffer nicht ausreicht. Snowflake empfiehlt, die Standardgröße größer als die maximale Größe der typischen Daten (z. B. 4.000 oder 8.000 Byte) einzustellen, um den Verbrauch an Arbeitsspeicher gegenüber den ursprünglichen Standardwerten 16.777.216/8.388.608 Byte erheblich zu verringern und so die Gefahr der Datenabschneidung zu minimieren.

Beachten Sie, dass Sie diese Einstellungen auch verwenden können, um den folgenden Fehler zu vermeiden, der bei Verwendung des Microsoft OLE DB-Anbieters (MSDASQL) mit einer Snowflake-Datenbank auftreten kann:

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

Copy

Sie können diese Parameter als Konfigurationsparameter der Verbindung angeben (z. B. in der simba.snowflake.ini auf macOS und Linux). Wenn dies als Verbindungsparameter und als Konfigurationsparameter eingestellt ist, hat der Verbindungsparameter im DSN (bzw. in der Verbindungszeichenfolge) Vorrang.

Diese Parameter wurden in Version 2.23.2 des ODBC-Treibers eingeführt.

get_size_threshold

Gibt die minimale Dateigröße in Megabyte (MB) an, um Dateien in kleinere Teile aufzuteilen, wenn sie mit dem Befehl GET heruntergeladen werden. Dateien, die kleiner als dieser Schwellenwert sind, werden nicht in mehreren Teilen heruntergeladen.

Der Standardwert ist 5 (MB).

Bemerkung

Die Einstellung dieses Wertes als Verbindungsparameter setzt den Wert des entsprechenden Konfigurationsparameters get_size_threshold außer Kraft.

login_timeout

Gibt an, wie lange beim Herstellen einer Verbindung zum Snowflake-Dienst auf eine Antwort gewartet werden soll, bevor ein Anmeldefehler zurückgegeben wird.

Standardwert ist 300 (Sekunden).

network_timeout

Gibt an, wie lange beim Interagieren mit dem Snowflake-Dienst auf eine Antwort gewartet werden soll, bevor ein Fehler zurückgegeben wird. Null (0) bedeutet, dass kein Netzwerk-Timeout eingestellt ist.

Standardwert ist 0 (Sekunden).

retryTimeout

Gibt an, wie lange (in Sekunden) gewartet werden soll, bevor bei HTTP-Wiederholungsversuchen von Abfragen mit fehlgeschlagenen HTTP-Anforderungen ein Fehler zurückgegeben wird. Null (0) bedeutet, dass kein Timeout für Wiederholungen eingestellt ist.

Standardwert ist 300 (Sekunden).

no_proxy

Gibt an, welche Hostnamen-Endungen den Proxyserver umgehen dürfen (z. B. bedeutet no_proxy=.amazonaws.com, dass der Amazon S3-Zugriff nicht über den Proxy erfolgen muss).

Dieser Parameter unterstützt keine Platzhalter. Jeder angegebene Wert sollte einer der folgenden Werte sein:

• Das Ende eines Hostnamens (oder eines vollständigen Hostnamens), zum Beispiel:

  • .amazonaws.com

  • meineOrganisation-meinKonto.snowflakecomputing.com

• Eine IP-Adresse, zum Beispiel:

  • 192.196.1.15

Wenn mehr als ein Wert angegeben wird, sollten die Werte durch Kommas getrennt werden. Beispiel:

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

Copy

Bemerkung

Dieser Parameter wird auf den Prozess angewendet. Wenn eine andere Verbindung den gleichen Prozess teilt, muss die Proxyeinstellung identisch sein, oder das Verhalten ist nicht vorhersehbar.

odbc_use_standard_timestamp_columnsize

Dieser boolesche Parameter wirkt sich auf die Spaltengröße (in Zeichen) aus, die für SQL_TYPE_TIMESTAMP zurückgegeben wird. Wenn dieser Parameter auf „true“ gesetzt ist, gibt der Treiber 29 gemäß dem ODBC-Standard zurück. Wenn dieser Parameter auf false gesetzt ist, gibt der Treiber 35 zurück, wodurch Platz für den Zeitzonenversatz bleibt (z. B. „-08:00“).

Dieser Wert kann nicht nur über die „odbc.ini“-Datei (Linux oder macOS) oder die Microsoft Windows-Registrierung festgelegt werden, sondern auch über die Verbindungszeichenfolge.

Der Standardwert ist false.

passcode

Gibt die Kennung an, die für die mehrstufige Authentifizierung verwendet werden soll.

Weitere Informationen zur mehrstufigen Authentifizierung finden Sie unter Mehrstufige Authentifizierung (MFA).

passcodeInPassword

Gibt an, ob die Kennung für die mehrstufige Authentifizierung an das Kennwort angehängt wird:

• on (oder true) gibt an, dass die Kennung angehängt wird.

• off (oder false) oder ein anderer Wert gibt an, dass die Kennung nicht angehängt wird.

Der Standardwert ist off.

proxy

Gibt die URL des Proxyservers im Format http://<Hostname>:<Port>/ oder <Hostname>:<Portnummer> an, sodass die gesamte ODBC-Kommunikation über den Proxyserver erfolgt.

Bemerkung

Dieser Parameter wird auf den Prozess angewendet. Wenn eine andere Verbindung den gleichen Prozess teilt, muss die Proxyeinstellung identisch sein, oder das Verhalten ist nicht vorhersehbar.

put_compresslv

Gibt die Komprimierungsrate an, die der ODBC-Treiber bei der Übertragung von Daten mit dem PUT-Befehl verwendet. Dieser Parameter überschreibt den standardmäßigen gzip-Komprimierungsgrad. Wenn Sie put_compresslv nicht angeben, verwendet der ODBC-Treiber den Standardkomprimierungsgrad.

Gültige Werte sind -1 bis 9. Der Standardwert ist -1 und gibt die Standardkomprimierungsrate Z_DEFAULT_COMPRESSION an.

Die Werte 0 bis 9 geben eine kundenspezifische Komprimierungsrate an. 0 veranlasst den ODBC-Treiber, eine niedrigere Komprimierungsrate zu verwenden, und 9 verwendet eine höhere Komprimierungsrate. Die Verwendung einer höheren Komprimierungsrate führt zu einer geringeren Geschwindigkeit beim Datentransfer.

Sie können diesen Parameter auch als Konfigurationsparameter (zum Beispiel in der simba.snowflake.ini unter macOS und Linux) angeben. Wenn dies als Verbindungsparameter und als Konfigurationsparameter eingestellt ist, hat der Verbindungsparameter im DSN (bzw. in der Verbindungszeichenfolge) Vorrang.

Dieser Parameter wurde in Version 2.23.3 des ODBC-Treibers eingeführt.

put_fastfail

Wenn Sie im PUT-Befehl Platzhalterzeichen verwenden, um mehrere Dateien auf einmal hochzuladen, und Sie möchten, dass der Treiber bei Auftreten eines Fehlers das Hochladen der Dateien abbricht, setzen Sie diesen Parameter auf true.

Der Standardwert ist false, d. h. wenn bei einer Datei ein Fehler auftritt, fährt der Treiber mit dem Hochladen der restlichen Dateien fort.

Dieser Parameter wurde in Version 2.22.3 des ODBC-Treibers eingeführt.

Ab Version 2.22.5 des ODBC-Treibers können Sie diesen Parameter auch als Konfigurationsparameter (zum Beispiel in der simba.snowflake.ini unter macOS und Linux) angeben. Wenn dies als Verbindungsparameter und als Konfigurationsparameter eingestellt ist, hat der Verbindungsparameter im DSN (bzw. in der Verbindungszeichenfolge) Vorrang.

put_maxretries

Gibt an, wie oft der Treiber die Ausführung des PUT-Befehls erneut versuchen soll, wenn der Befehl fehlschlägt.

Der Standardwert ist 5.

Der gültige Wertebereich für diesen Parameter ist 0 bis 100. Wenn Sie einen Wert außerhalb dieses Bereichs angeben, verwendet der Treiber den Standardwert 5.

Dieser Parameter wurde in Version 2.22.3 des ODBC-Treibers eingeführt.

Ab Version 2.22.5 des ODBC-Treibers können Sie diesen Parameter auch als Konfigurationsparameter (zum Beispiel in der simba.snowflake.ini unter macOS und Linux) angeben. Wenn dies als Verbindungsparameter und als Konfigurationsparameter eingestellt ist, hat der Verbindungsparameter im DSN (bzw. in der Verbindungszeichenfolge) Vorrang.

put_tempdir

Gibt das temporäre Verzeichnis an, das für PUT-Befehlsanforderungen verwendet werden soll. Der Treiber verwendet dieses temporäre Verzeichnis, um temporäre komprimierte Dateien zu erstellen, bevor diese Dateien zu Snowflake hochgeladen werden.

Wenn dieser Parameter nicht festgelegt ist, erstellt und verwendet der Treiber das temporäre Verzeichnis /tmp/snowflakeTmp_username, wobei username der Benutzername des aktuellen Benutzers im Betriebssystem ist.

Sie können diesen Parameter auch als Konfigurationsparameter (zum Beispiel in der simba.snowflake.ini unter macOS und Linux) angeben. Wenn dies als Verbindungsparameter und als Konfigurationsparameter eingestellt ist, hat der Verbindungsparameter im DSN (bzw. in der Verbindungszeichenfolge) Vorrang.

Dieser Parameter wurde in Version 2.23.1 des ODBC-Treibers eingeführt.

token=<Zeichenfolge>

Gibt das OAuth-Token an, das für die Authentifizierung verwendet werden soll, wobei <Zeichenfolge> das Token ist. Dieser Parameter ist nur erforderlich, wenn der Parameter authenticator=oauth eingestellt ist.

Der Standardwert ist „none“.

query_timeout

Gibt an, wie lange auf das Ende einer Abfrage gewartet werden soll, bevor ein Fehler gemeldet wird. Null (0) bedeutet, dass Sie auf unbestimmte Zeit warten müssen.

Standardwert ist 0 (Sekunden).

validateSessionParam

Gibt an, wie zu reagieren ist, wenn einer der folgenden Sitzungsverbindungsparameter ungültig ist:

enable_connection_diag

Gibt an, ob der Konnektor einen Diagnosebericht zur Konnektivität erstellt.

Der Standardwert ist false.

connection_diag_log_path

Gibt den absoluten Pfad an, unter dem der Konnektivitätsbericht gespeichert wird.

Nur gültig, wenn enable_connection_diag true ist.

Beispiel: connection_diag_log_path=C:\\reports

connection_diag_allowlist_path

Gibt den absoluten Pfad zu einer JSON-Datei an, die die Ausgabe von SYSTEM$ALLOWLIST() oder SYSTEM$ALLOWLIST_PRIVATELINK() enthält.

Nur gültig, wenn enable_connection_diag true ist.

Beispiel: connection_diag_log_path=C:\\allowlist.json

Verwenden von Verbindungsparametern¶

Um eine Verbindung über einen Proxyserver herzustellen, fügen Sie die folgenden Verbindungsparameter zum DSN hinzu:

• proxy

• no_proxy

Beispiel:

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

Copy

Die Parameterbeschreibungen finden Sie unter Verbindungsparameter.

Verwenden von Konfigurationsparametern¶

Um eine Verbindung über einen Proxyserver herzustellen, fügen Sie die folgenden Konfigurationsparameter hinzu:

• Proxy

• NoProxy

Siehe Konfigurationsparameter für Parameterbeschreibungen.

Verwenden von Umgebungsvariablen¶

Um eine Verbindung über einen Proxyserver herzustellen, konfigurieren Sie die folgenden Umgebungsvariablen:

• http_proxy

• https_proxy

• no_proxy

Beispiel:

• Linux oder macOS:

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

  Copy

  Wenn der Proxyserver einen Benutzernamen und ein Kennwort erfordert, geben Sie die Anmeldeinformationen an, z. B.:

  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

  Wenn der Proxyserver einen Benutzernamen und ein Kennwort erfordert, geben Sie die Anmeldeinformationen an, z. B.:

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

  Copy

Optional können Sie no_proxy so einstellen, dass der Proxy für bestimmte Kommunikation umgangen wird (z. B. no_proxy=.amazonaws.com zur Umgehung des Amazon S3-Zugriffs).

Protokollierungskonfigurationsdatei¶

Alternativ können Sie den Protokolliergrad und das Verzeichnis, in dem die Protokolldateien gespeichert werden sollen, auch einfach in der Konfigurationsdatei sf_client_config.json angeben.

Diese Konfigurationsdatei verwendet JSON, um die Protokollierungsparameter log_level und log_path wie folgt zu definieren:

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

Der Treiber sucht in der folgenden Reihenfolge nach dem Speicherort der Konfigurationsdatei:

• Parameter client_config_file, der den vollständigen Pfad zur Konfigurationsdatei enthält.

• Umgebungsvariable SF_CLIENT_CONFIG_FILE, die den vollständigen Pfad zur Konfigurationsdatei enthält.

• ODBC-Treiberinstallationsverzeichnis, wo die Datei den Namen sf_client_config.json tragen muss.

• Basisverzeichnis des Benutzers, in dem die Datei sf_client_config.json heißen muss.