Verwalten von Snowflake-Verbindungen¶

Alternative Konfigurationsdatei¶

Snowflake CLI unterstützt auch die Konfigurationsdatei connections.toml. Die Datei sollte sich im gleichen Verzeichnis wie die Datei config.toml befinden und nur Verbindungen enthalten. Konfigurationen in connections.toml erfordern einen anderen Abschnittsnamen ohne connections. Ein Beispiel wäre [connections.myconnection] nur [myconnection].

Hinzufügen einer Verbindung¶

Gehen Sie wie folgt vor, um eine neue Verbindung zu erstellen und sie der Konfigurationsdatei hinzuzufügen:

1. Führen Sie den Befehl snow connection add aus:

   snow connection add
   

   Copy

2. Wenn Sie dazu aufgefordert werden, geben Sie die erforderlichen Parameter für die Verbindung, das Konto und den Benutzernamen sowie alle anderen gewünschten optionalen Parameter ein.

   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
   

Sie können auch Werte für bestimmte Parameter in der Befehlszeile eingeben, wie hier gezeigt:

snow --config-file config.toml connection add -n myconnection2 --account myaccount2 --user jdoe2

Standardmäßig fordert der Befehl snow connection add zur Angabe von optionalen Parametern auf, wenn diese nicht in der Befehlszeile angegeben wurden. Wenn Sie Verbindungen hinzufügen möchten, ohne einen optionalen Parameter wie account anzugeben und die interaktiven Eingabeaufforderungen überspringen möchten, können Sie die Option --no-interactive verwenden, wie gezeigt:

snow connection add -n myconnection2 --user jdoe2 --no-interactive

Nachdem Sie eine Verbindung hinzugefügt haben, können Sie die Verbindung testen, um sicherzustellen, dass sie korrekt funktioniert.

Listen Sie definierte Verbindungen auf¶

Um die verfügbaren Verbindungen aufzulisten, geben Sie den Befehl snow connection list ein, wie gezeigt:

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      |
+-------------------------------------------------------------------------------------------------+

Testen und diagnostizieren Sie eine Verbindung¶

Um zu testen, ob sich eine Verbindung erfolgreich mit Snowflake verbinden kann, geben Sie den Befehl snow connection test ein, ähnlich dem Folgenden:

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                        |
+--------------------------------------------------+

Wenn Sie Probleme mit der Konnektivität haben, können Sie direkt unter Snowflake CLI eine Diagnose durchführen. Der Snowflake-Support kann diese Informationen auch anfragen, um Ihnen bei Problemen mit der Konnektivität zu helfen.

Die Diagnosesammlung verwendet die folgenden snow connection test-Befehlsoptionen:

• --enable-diag, um einen Diagnosebericht zu erstellen.

• --diag-log-path, um den absoluten Pfad für den generierten Bericht anzugeben.

• --diag-allowlist-path, um den absoluten Pfad zu einer JSON-Datei anzugeben, welche die Ausgabe der Befehle SYSTEM$ALLOWLIST() oder SYSTEM$ALLOWLIST_PRIVATELINK() SQL enthält. Diese Option ist nur erforderlich, wenn der in der Verbindung definierte Benutzer keine Berechtigung hat, die Funktionen der Systemzulassungsliste auszuführen, oder wenn die Verbindung zur Konto-URL fehlschlägt.

Das folgende Beispiel erzeugt einen Diagnosebericht für die Verbindung myconnection2 und speichert ihn in der Datei ~/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 |
+----------------------------------------------------------------------------+

Sie können den Bericht auf eventuelle Probleme mit der Konnektivität überprüfen und diese mit Ihrem Netzwerk-Team besprechen. Sie können den Bericht auch dem Snowflake-Support zur Verfügung stellen, um zusätzliche Unterstützung zu erhalten.

Legen Sie die Standardverbindung fest¶

Mit dem Befehl snow connection set-default können Sie angeben, welche Konfiguration Snowflake CLI als Standard verwendet werden soll. Damit überschreiben Sie die Konfigurationsdatei default_connection_name und die Variablen SNOWFLAKE_DEFAULT_CONNECTION_NAME, sofern diese festgelegt sind.

Das folgende Beispiel setzt die Standardverbindung auf myconnection2:

snow connection set-default myconnection2

Default connection set to: myconnection2

Umgebungsvariablen für Snowflake-Anmeldeinformationen verwenden¶

Sie können die Anmeldeinformationen für Snowflake in Variablen der Systemumgebung statt in Dateien der Konfiguration angeben. Sie können die folgenden generischen Umgebungsvariablen nur zur Angabe von Parametern für die Verbindung verwenden:

• 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

Übergeben Sie Verbindungsparameter an den Befehl snow¶

Sie können Verbindungsparameter direkt in jedem snow-Befehl übergeben, der eine Verbindung erfordert. Um eine vollständige Liste der Parameter für die Verbindungskonfiguration zu erhalten, führen Sie den Befehl snow sql --help aus, wie gezeigt. Beachten Sie, dass in der Ausgabe nur der Abschnitt mit den Optionen für die Konfiguration der Verbindung angezeigt wird.

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.
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Verwenden Sie eine Datei mit einem privaten Schlüssel zur Authentifizierung¶

Um eine private Schlüsseldatei für die Authentifizierung zu verwenden, müssen Sie in der Verbindungskonfiguration den Parameter authenticator auf SNOWFLAKE_JWT setzen und den Pfad zur Datei mit Ihrem privaten Schlüssel angeben, ähnlich wie im Folgenden beschrieben:

• Geben Sie die --private_key-file-Option im Befehl snow connection add an, wie gezeigt:

  snow connection add \
     --connection-name jwt \
     --authenticator SNOWFLAKE_JWT \
     --private-key-file ~/.ssh/sf_private_key.p8
  

  Copy

• Verwenden Sie die Konfigurationsdatei:

  [connections.jwt]
  account = "my_account"
  user = "jdoe"
  authenticator = "SNOWFLAKE_JWT"
  private_key_file = "~/sf_private_key.p8"
  

  Copy

Weitere Informationen zum Konfigurieren der Schlüsselpaar-Authentifizierung finden Sie unter Schlüsselpaar-Authentifizierung und Schlüsselpaar-Rotation.

Snowflake CLI sucht in den Verbindungsparametern in der folgenden Reihenfolge nach dem privaten Schlüssel:

1. Wenn private_key_file angegeben ist, liest Snowflake CLI den Schlüssel aus dem angegebenen Dateipfad.

2. Wenn private_key_path angegeben ist, liest Snowflake CLI den Schlüssel aus dem angegebenen Dateipfad.

3. Wenn private_key_file oder private_key_path nicht angegeben sind, liest Snowflake CLI den Schlüssel direkt aus dem Parameter private_key_raw.

Verwenden Sie die OAuth-Authentifizierung¶

Um die Verbindung über OAuth zu nutzen, können Sie einen der folgenden Schritte ausführen:

• Geben Sie die --token-file-path-Option im Befehl snow connection add an, wie gezeigt:

  snow connection add --token-file-path "my-token.txt"
  

  Copy

• Stellen Sie für die Datei config.toml authenticator = "oauth" ein und fügen den token_file_path-Parameter zur Definition der Verbindung hinzu, wie gezeigt:

  [connections.oauth]
  account = "my_account"
  user = "jdoe"
  authenticator = "oauth"
  token_file_path = "my-token.txt"
  

  Copy

Verwenden Sie den OAuth 2.0-Autorisierungscodeablauf¶

Der OAuth 2.0-Autorisierungscodeablauf ist eine sichere Methode für eine Client-Anwendung, um im Namen eines Benutzers ein Zugriffstoken von einem Autorisierungsserver zu erhalten, ohne die Anmeldeinformationen des Benutzers preiszugeben. Weitere Informationen zu diesem Ablauf und seinen Parametern finden Sie unter Aktivieren des OAuth 2.0-Autorisierungscodeablaufs in der Dokumentation zum Snowflake Connector für Python.

Um den OAuth 2.0-Autorisierungscodeablauf zu verwenden, fügen Sie eine Verbindungsdefinition zu Ihrer config.toml-Datei hinzu, die der folgenden ähnelt:

[connections.oauth]
authenticator = "OAUTH_AUTHORIZATION_CODE"
user = "user"
account = "account"
oauth_client_id = "client_id"
oauth_client_secret = "client_secret"
oauth_redirect_uri = "http://localhost:8001/snowflake/oauth-redirect"
oauth_scope = "session:role:PUBLIC"

Verwenden Sie den OAuth 2.0-Client-Anmeldeinformationsablauf¶

Der OAuth 2.0-Client-Anmeldeinformationsablauf bietet einen sicheren Weg für die Machine-to-Machine (M2M)-Authentifizierung, wie z. B. den Snowflake Connector für Python, der sich mit einem Backend-Service verbindet. Im Gegensatz zum OAuth 2.0-Autorisierungscodeablauf ist diese Methode nicht auf benutzerspezifische Daten angewiesen. Weitere Informationen zu diesem Ablauf und seinen Parametern finden Sie unter Aktivieren des OAuth 2.0-Client-Anmeldeinformationsablaufs in der Dokumentation zum Snowflake Connector für Python.

Um den OAuth 2.0-Client-Anmeldeinformationsablauf zu verwenden, fügen Sie eine Verbindungsdefinition zu Ihrer config.toml-Datei hinzu, die der folgenden ähnelt:

[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"

Verwenden Sie eine mehrstufige Authentifizierung (MFA)¶

So verwenden Sie MFA:

1. Richten Sie mehrstufige Authentifizierung in Snowflake ein, und setzen Sie den Parameter authenticator auf snowflake (dies ist ein Standardwert).

2. Wenn Sie anstelle des Push-Mechanismus eine von Duo generierte Kennung verwenden möchten, verwenden Sie entweder die Option --mfa-passcode <passcode> oder setzen Sie passcode_in_password = true in der Datei config.toml und fügen Sie die Kennung in Ihr Kennwort ein, wie in Verwenden von MFA mit Python beschrieben.

   Bemerkung

   Wenn Sie die Kennung im Kennwort zur Authentifizierung verwenden möchten, können Sie nach der Ausführung des ersten Befehls snow die Kennung nicht mehr angeben, solange das Token gültig ist. Sie müssen Folgendes tun:

   • Entfernen Sie die Kennung aus dem Kennwort.

   • Entfernen oder kommentieren Sie passcode_in_password = true in der Datei config.toml.

Verwenden Sie MFA-Caching¶

MFA-Caching ist ein Sicherheits-Feature, das die Häufigkeit von Aufforderungen zur mehrstufigen Authentifizierung (MFA) bei Anmeldungen reduziert. Häufige MFA-Aufforderungen können den Arbeitsablauf stören und die Produktivität verringern. MFA-Caching löst dieses Problem, indem es die MFA-Sitzungsinformationen für einen bestimmten Zeitraum sicher speichert. Mithilfe von MFA-Caching können Sie sich authentifizieren, ohne wiederholt MFA-Codes eingeben zu müssen, solange sie innerhalb des Zeitrahmens der zwischengespeicherten Sitzung liegen.

So aktivieren Sie MFA-Caching:

1. Stellen Sie für Ihr Konto ALLOW_CLIENT_MFA_CACHING = true ein.

2. Fügen Sie in Ihrer config.toml-Datei authenticator = "username_password_mfa" zu Ihrer Verbindung hinzu.

Weitere Informationen dazu finden Sie unter Verwenden von MFA-Tokencaching zur Minimierung der Anzahl von Eingabeaufforderungen bei der Authentifizierung – Optional.

Verwenden Sie SSO (Single Sign-On)¶

Wenn Sie Snowflake für die Verwendung von Single Sign-On (SSO) konfiguriert haben, können Sie Ihre Clientanwendung so konfigurieren, dass SSO für die Authentifizierung verwendet wird. Einzelheiten finden Sie unter Verwenden von SSO bei Clientanwendungen, die sich mit Snowflake verbinden. Konfigurieren Sie Ihre Verbindung anhand der Anweisungen für Python.

Verwenden Sie einen externen Browser¶

Sie können Ihren Browser verwenden, um Ihre Snowflake CLI-Verbindung mit jedem SAML 2.0-konformen Anbieter (IdP) zu authentifizieren, wie z. B. Okta oder Active Directory Federation Services.

Um die externe Browser-Authentifizierung zu verwenden, verwenden Sie eine der folgenden Methoden:

• Verwenden Sie die Befehlsoption snow connection add --authenticator:

  snow connection add --authenticator externalbrowser
  

  Copy

• Setzen Sie authenticator auf externalbrowser in Ihrer config.toml-Datei:

  [connections.externalbrowser]
  account = "my_account"
  user = "jdoe"
  authenticator = "externalbrowser"
  

  Copy

Verwenden Sie PAT (Programmatic Access Token)¶

Programmatic Access Token (PAT) ist eine Snowflake-spezifische Authentifizierungsmethode. Das Feature muss vor der Verwendung für das Konto aktiviert werden (weitere Informationen finden Sie unter Voraussetzungen). Die Authentifizierung mit PAT erfordert keine menschliche Interaktion.

Um PAT für die Verbindung zu verwenden, setzen Sie authenticator auf PROGRAMMATIC_ACCESS_TOKEN und token_file_path auf die Datei mit dem Token, wie gezeigt:

[connections.externalbrowser]
account = "my_account"
user = "jdoe"
authenticator = "PROGRAMMATIC_ACCESS_TOKEN"
token_file_path = "path-to-pat-token"

Weitere Informationen zu PATs finden Sie unter Verwenden von programmatische Zugriffstoken für die Authentifizierung.