Merge pull request #3032 from emqx/r59-update-snowflake-connector

Meggielqk · web-flow · commit ea23cd66ac28 · 2025-06-27T13:10:29.000+08:00
update(snowflake): Add key-pair authn support for connector
diff --git a/en_US/data-integration/snowflake.md b/en_US/data-integration/snowflake.md
@@ -50,18 +50,71 @@ For more information, refer to the official [ODBC Driver](https://docs.snowflake
 
 #### Linux
 
-Run the following script to install the Snowflake ODBC driver and configure the `odbc.ini` file:
-
-```
-scripts/install-snowflake-driver.sh
-```
+EMQX provides an [installation script](https://github.com/emqx/emqx/blob/master/scripts/install-snowflake-driver.sh) designed specifically for the quick deployment of the Snowflake ODBC driver on Debian-based systems (such as Ubuntu), along with the required system configuration.
 
 ::: tip Note
 
 This script is for testing only, not a recommendation on how to set up the ODBC driver in production environments. You can refer to the official [installation instructions for Linux](https://docs.snowflake.com/en/developer-guide/odbc/odbc-linux).
 
 :::
 
+**Run the Installation Script**
+
+Copy the `scripts/install-snowflake-driver.sh` script to your local machine. Run `chmod a+x` to make the script executable, and run it with `sudo`:
+
+```bash
+chmod a+x scripts/install-snowflake-driver.sh
+sudo ./scripts/install-snowflake-driver.sh
+```
+
+The script automatically downloads the Snowflake ODBC `.deb` installation package (e.g., `snowflake-odbc-3.4.1.x86_64.deb`) to the current working directory. It then installs the driver and updates the following system configuration files:
+
+- `/etc/odbc.ini`: Adds the Snowflake data source configuration
+- `/etc/odbcinst.ini`: Registers the Snowflake driver path
+
+**Sample Configuration**
+
+Run the following command to view the configurations in the `/etc/odbc.ini` file:
+
+```
+emqx@emqx-0:~$ cat /etc/odbc.ini 
+
+[snowflake]
+Description=SnowflakeDB
+Driver=SnowflakeDSIIDriver
+Locale=en-US
+PORT=443
+SSL=on
+
+[ODBC Data Sources]
+snowflake = SnowflakeDSIIDriver
+```
+
+Run the following command to view the configurations in the  `/etc/odbcinst.ini` file:
+
+```
+emqx@emqx-0:~$ cat /etc/odbcinst.ini 
+
+[ODBC Driver 18 for SQL Server]
+Description=Microsoft ODBC Driver 18 for SQL Server
+Driver=/opt/microsoft/msodbcsql18/lib64/libmsodbcsql-18.5.so.1.1
+UsageCount=1
+
+[ODBC Driver 17 for SQL Server]
+Description=Microsoft ODBC Driver 17 for SQL Server
+Driver=/opt/microsoft/msodbcsql17/lib64/libmsodbcsql-17.10.so.6.1
+UsageCount=1
+
+[SnowflakeDSIIDriver]
+APILevel=1
+ConnectFunctions=YYY
+Description=Snowflake DSII
+Driver=/usr/lib/snowflake/odbc/lib/libSnowflake.so
+DriverODBCVer=03.52
+SQLLevel=1
+UsageCount=1
+```
+
 #### macOS
 
 To install and configure the Snowflake ODBC driver on macOS, follow these steps:
@@ -108,7 +161,7 @@ To install and configure the Snowflake ODBC driver on macOS, follow these steps:
 
 ### Create a User Account and Database
 
-Once the Snowflake ODBC driver is installed, you need to set up a user account, database, and related resources for data ingestion. The following credentials will be required later for configuring the connector and Sink in EMQX:
+Once the Snowflake ODBC driver is installed, you need to set up a user account, database, and related resources for data ingestion. The following credentials will be required later for configuring the Connector and Sink in EMQX:
 
 | Field                  | Value                                            |
 | ---------------------- | ------------------------------------------------ |
@@ -201,18 +254,46 @@ Once the ODBC driver is set up and the RSA key pair is generated, you can set up
 Before adding the Snowflake Sink, you need to create the corresponding connector in EMQX to establish the connection with Snowflake.
 
 1. Go to the Dashboard **Integration** -> **Connector** page.
+
 2. Click the **Create** button in the top right corner.
+
 3. Select **Snowflake** as the connector type and click next.
+
 4. Enter the connector name, a combination of upper and lowercase letters and numbers. Here, enter `my-snowflake`.
+
 5. Enter the connection information.
-   - **Account**: Enter your Snowflake Organization ID and Snowflake account name separated by a dash (`-`), which is part of the URL you use to access the Snowflake platform and can be found in your Snowflake console.
    - **Server Host**: The server host is the Snowflake endpoint URL, typically in the format `<Your Snowflake Organization ID>-<Your Snowflake Account Name>.snowflakecomputing.com`. You need to replace `<Your Snowflake Organization ID>-<Your Snowflake Account Name>` with the subdomain specific to your Snowflake instance.
+   
    - **Data Source Name(DSN)**: Enter `snowflake`, which corresponds to the DSN configured in the `.odbc.ini` file during ODBC driver setup.
+   
+   - **Account**: Enter your Snowflake Organization ID and Snowflake account name separated by a dash (`-`), which is part of the URL you use to access the Snowflake platform and can be found in your Snowflake console.
+   
    - **Username**: Enter `snowpipeuser`, as defined during the previous setup process.
-   - **Password**: Enter `Snowpipeuser99`, as defined during the previous setup process.
+   
+   - **Password**: The password for authenticating with Snowflake via ODBC using username/password authentication. This field is optional:
+   
+     - You may enter the password here, e.g., `Snowpipeuser99`, as defined during the previous setup process;
+     - Or configure it in `/etc/odbc.ini`;
+     - If using key-pair authentication instead, leave this field blank.
+   
+     ::: tip
+   
+     Use either Password or Private Key for authentication, not both. If neither is configured here, ensure the appropriate credentials are set in `/etc/odbc.ini`.
+   
+     :::
+   
+   - **Proxy**: Configuration settings for connecting to Snowflake through an HTTP proxy server. HTTPS proxies are **not** supported. By default, no proxy is used. To enable proxy support, select the `Enable Proxy` and provide the following:
+     - **Proxy Host**: The hostname or IP address of the proxy server.
+     - **Proxy Port**: The port number used by the proxy server.
+   - **Private Key Path**: The absolute file path to the private RSA key used for authenticating with Snowflake via ODBC. This path must be the same on all nodes of the cluster. The path must begin with `file://`, for example: `file:///etc/emqx/certs/snowflake_rsa_key.private.pem`.
+   - **Private Key Password**: The password used to decrypt the private RSA key file, if the key is encrypted. Leave this field blank if the key was generated without encryption (i.e., with the `-nocrypt` option in OpenSSL).
+   
 6. If you want to establish an encrypted connection, click the **Enable TLS** toggle switch. For more information about TLS connection, see [TLS for External Resource Access](../network/overview.md/#tls-for-external-resource-access).
-6. Advanced settings (optional): See [Advanced Settings](#advanced-settings).
-6. Before clicking **Create**, you can click **Test Connectivity** to test if the connector can connect to the Snowflake.
+
+7. Advanced settings (optional): See [Advanced Settings](#advanced-settings).
+
+8. Before clicking **Create**, you can click **Test Connectivity** to test if the connector can connect to the Snowflake.
+
 7. Click the **Create** button at the bottom to complete the connector creation.
 
 You have now completed the connector creation and can proceed to create a rule and Sink to specify how the data will be written into Snowflake.
diff --git a/zh_CN/data-integration/snowflake.md b/zh_CN/data-integration/snowflake.md
@@ -50,18 +50,71 @@ EMQX 利用规则引擎和 Sink 将设备事件和数据转发到 Snowflake。
 
 #### Linux
 
-运行以下脚本来安装 Snowflake ODBC 驱动程序并配置 `odbc.ini` 文件：
-
-```bash
-scripts/install-snowflake-driver.sh
-```
+EMQX 提供了一个[安装脚本](https://github.com/emqx/emqx/blob/master/scripts/install-snowflake-driver.sh)，仅适用用于在基于 Debian 的系统（如 Ubuntu）上快速部署 Snowflake ODBC 驱动，并配置所需的系统文件。
 
 ::: tip 注意
 
 该脚本仅用于测试环境，并非生产环境中 ODBC 驱动设置的推荐方式。请参考官方文档 [Installing for Linux](https://docs.snowflake.com/en/developer-guide/odbc/odbc-linux)。
 
 :::
 
+**执行安装脚本**
+
+将 `scripts/install-snowflake-driver.sh` 脚本复制到本地保存，同时添加执行权限并 sudo 执行脚本：
+
+```bash
+chmod a+x scripts/install-snowflake-driver.sh
+sudo ./scripts/install-snowflake-driver.sh
+```
+
+脚本将自动将 Snowflake ODBC 驱动 `.deb` 安装包 (如 `snowflake-odbc-3.4.1.x86_64.deb`) 下载到运行脚本的当前目录、完成驱动安装，并更新以下系统配置文件：
+
+- `/etc/odbc.ini`：添加 Snowflake 数据源配置
+- `/etc/odbcinst.ini`：注册 Snowflake 驱动路径
+
+**示例配置内容**
+
+运行以下命令查看 `/etc/odbc.ini` 文件配置：
+
+```
+emqx@emqx-0:~$ cat /etc/odbc.ini 
+
+[snowflake]
+Description=SnowflakeDB
+Driver=SnowflakeDSIIDriver
+Locale=en-US
+PORT=443
+SSL=on
+
+[ODBC Data Sources]
+snowflake = SnowflakeDSIIDriver
+```
+
+运行以下命令查看 `/etc/odbcinst.ini` 文件配置:
+
+```
+emqx@emqx-0:~$ cat /etc/odbcinst.ini 
+
+[ODBC Driver 18 for SQL Server]
+Description=Microsoft ODBC Driver 18 for SQL Server
+Driver=/opt/microsoft/msodbcsql18/lib64/libmsodbcsql-18.5.so.1.1
+UsageCount=1
+
+[ODBC Driver 17 for SQL Server]
+Description=Microsoft ODBC Driver 17 for SQL Server
+Driver=/opt/microsoft/msodbcsql17/lib64/libmsodbcsql-17.10.so.6.1
+UsageCount=1
+
+[SnowflakeDSIIDriver]
+APILevel=1
+ConnectFunctions=YYY
+Description=Snowflake DSII
+Driver=/usr/lib/snowflake/odbc/lib/libSnowflake.so
+DriverODBCVer=03.52
+SQLLevel=1
+UsageCount=1
+```
+
 #### macOS
 
 在 macOS 上安装并配置 Snowflake ODBC 驱动程序，请按照以下步骤操作：
@@ -200,19 +253,47 @@ openssl rsa -in snowflake_rsa_key.private.pem -pubout -out snowflake_rsa_key.pub
 
 在添加 Snowflake Sink 之前，您需要在 EMQX 中创建相应的连接器，以建立与 Snowflake 的连接。
 
-1. 进入 Dashboard **集成** -> **连接器** 页面。
+1. 进入 Dashboard **集成** -> **连接器**页面。
+
 2. 点击右上角的**创建**按钮。
+
 3. 选择 **Snowflake** 作为连接器类型，然后点击下一步。
+
 4. 输入连接器名称，由大小写字母和数字组成。这里输入 `my-snowflake`。
+
 5. 输入连接信息：
-   - **账户**：输入您的 Snowflake 组织 ID 和账户名，用连字符（`-`）分隔，可以在 Snowflake 控制台中找到该信息，通常也是您访问 Snowflake 平台的 URL 中的一部分。
    - **服务器地址**：服务器地址为 Snowflake 的端点 URL，通常格式为 `<你的 Snowflake 组织 ID>-<你的 Snowflake 账户名>.snowflakecomputing.com`。您需要用自己 Snowflake 实例的子域替换 `<你的 Snowflake 组织 ID>-<你的 Snowflake 账户名称>`。
+   
    - **数据源名称**：输入 `snowflake`，与您在 ODBC 驱动设置中配置的 `.odbc.ini` 文件中的 DSN 名称相对应。
+   
+   - **账户**：输入您的 Snowflake 组织 ID 和账户名，用连字符（`-`）分隔，可以在 Snowflake 控制台中找到该信息，通常也是您访问 Snowflake 平台的 URL 中的一部分。
+   
    - **用户名**：输入 `snowpipeuser`，这是之前设置过程中定义的用户名。
-   - **密码**：输入 `Snowpipeuser99`，这是之前设置过程中定义的密码。
+   
+   - **密码**：输入用于通过用户名和密码进行 ODBC 连接认证。此字段为可选项，用户可以选择：
+   
+     - 在此处填写密码，例如： `Snowpipeuser99`，这是之前设置过程中定义的密码。
+     - 或在系统的 `/etc/odbc.ini` 文件中配置；
+     - 如果使用密钥对认证，则无需提供密码。
+   
+     ::: tip
+   
+     使用密码或私钥进行身份验证，而不是两者兼用。如果此处未配置这两种方式，请确保在 `/etc/odbc.ini` 中设置了适当的凭证。
+   
+     :::
+   
+   - **代理**：用于通过 HTTP 代理服务器连接到 Snowflake 的配置。**不支持** HTTPS 代理。默认情况下不使用代理。若需启用代理支持，请选择`开启代理`并填写以下信息：
+     - **代理主机**：代理服务器的主机名或 IP 地址。
+     - **代理端口**：代理服务器使用的端口号。
+   - **私钥路径**： 用于通过 ODBC 认证连接 Snowflake 的 RSA 私钥的绝对文件路径。此路径必须在集群的所有节点上保持一致。路径必须以 `file://` 开头，例如：`file:///etc/emqx/certs/snowflake_rsa_key.private.pem`。
+   - **私钥密码**：用于解密 RSA 私钥文件的密码（如果该私钥已加密）。如果私钥是在未加密的情况下生成的（例如使用 OpenSSL 的 `-nocrypt` 选项），则此字段应留空。
+   
 6. 如果您想建立一个加密连接，单击**启用 TLS** 切换按钮。有关 TLS 连接的更多信息，请参见[启用 TLS 加密访问外部资源](../network/overview.md/#tls-for-external-resource-access)。
+
 7. 高级配置（可选），请参考[高级设置](#高级设置)。
+
 8. 在点击**创建**之前，可以点击 **测试连接** 来测试连接器是否能够连接到 Snowflake。
+
 9. 点击页面底部的**创建**按钮，完成连接器创建。
 
 现在，您已经成功创建了连接器，可以继续创建规则和 Sink，以指定如何将数据写入 Snowflake。
