从 SnowSQL 迁移到 Snowflake CLI¶

安装 Snowflake CLI 软件¶

与 SnowSQL 类似，Snowflake CLI 提供 :ref:` 二进制安装程序 <label-snowcli_install_package_managers>`。此外，它还允许您使用 Homebrew 和 pip 安装软件。

目前，Snowflake CLI 支持以下平台：

• macOS (arm)

  • 包安装程序

  • Homebrew

  • PyPi (pip)

• macOS (x86_64)：

  • 包安装程序

  • Homebrew

  • PyPi (pip)

• Linux（x86_64 和 aarch64）：

  • deb 包安装程序

  • rpm 包安装程序

  • PyPi (pip)

• Windows（64 位）：

  • 安装程序

  • PyPi (pip)

目前，Snowflake CLI 不支持以下平台：

• Linux bash 安装程序

有关安装 Snowflake CLI 的更多信息，请参阅 安装 Snowflake CLI。

迁移您的 SnowSQL 连接和设置¶

Snowflake CLI 提供了 snow helpers 命令组，以简化从 SnowSQL 到 Snowflake CLI 的过渡过程。使用这些命令可以轻松导入现有连接和环境变量：

• snow helpers import-snowsql-connections 命令通过交互式菜单让您选择要导入的 SnowSQL 连接。有关更多信息，请参阅 从 SnowSQL 导入连接。

• snow helpers check-snowsql-env-vars 命令可帮助您诊断 SnowSQL 环境中设置了哪些环境变量，并显示其相应的 Snowflake CLI 等效变量。有关更多信息，请参阅 在 SQL 中使用变量。

如果您使用 SnowSQL 来执行内联 SQL 语句或执行文件，但不想编辑所有脚本，可以考虑创建一个别名，将 snowsql 映射到 snowsql 命令。例如，在类似 Unix 的系统上，使用以下命令：

alias snowsql='snow sql'

使用此别名，您可以将现有脚本与 Snowflake CLI 结合使用。

请注意，如果您是更高级的 SnowSQL 用户，偶尔可能会遇到不兼容消息，这些消息通常与用于配置 SnowSQL 的选项有关。由于 Snowflake CLI 未使用所有 SnowSQL 配置选项，因此您可能需要复制脚本并移除这些不兼容的选项。

回滚到 SnowSQL¶

Snowflake CLI 使用自己的配置文件，因此您可以继续使用 SnowSQL。您可以同时安装 SnowSQL 和 Snowflake CLI，并独立运行它们。如果您如上所述设置了别名，则必须移除该别名，才能将 snowsql 命令用于 SnowSQL。

配置文件中的差异¶

• SnowSQL

  SnowSQL 由其 配置文件 配置，该文件是 TOML 格式的文件，包含连接配置、工具的各种设置以及可在 SQL 查询中使用的变量。可以将配置拆分为多个位置，这使您可以定义系统范围的默认值并针对不同的用户替换这些默认值。您还可以通过指定 --config 命令行选项来从自定义位置指定配置。有关更多信息，请参阅 连接参数参考。

• Snowflake CLI

  Snowflake CLI 还有自己的 TOML 配置文件，用于指定该工具的连接配置和设置。它不允许您定义稍后在 SQL 查询中使用的变量。Snowflake CLI 中的变量是在项目级别的 项目定义文件 中定义的。Snowflake CLI 仅使用一个默认情况下位于用户主目录中的配置文件。您还可以通过指定 --config 命令行选项来从自定义位置指定配置。有关更多信息，请参阅 snow 命令参考。

查找 Snowflake CLI 默认配置文件¶

默认 Snowflake CLI 配置的位置取决于您的系统，并由 .toml 配置文件的位置 中指定的顺序确定。

• 要查找 Snowflake CLI 安装的 default_config_file_path 参数值，请运行 snow --info 命令，如下所示：

  snow --info
  

  Copy

  [
    ...
  
    {
        "key": "default_config_file_path",
        "value": "/<user_home>/.snowflake/config.toml"
    },
  
    ...
  ]
  

从 SnowSQL 导入连接¶

您可以使用 snow helpers import-snowsql-connections 命令导入所有 SnowSQL 连接。有关更多信息，请参阅 从 SnowSQL 导入连接 和 snow helpers import-snowsql-connections 命令参考。

手动迁移默认连接配置¶

如果您选择不使用 snow helpers import-snowsql-connections 命令导入连接，则可以手动迁移默认连接。

指定默认连接的区别包括以下几点：

• SnowSQL

  默认连接在 SnowSQL 配置文件 中配置，连接设置直接在 [连接] 部分定义。

• Snowflake CLI

  默认连接在 Snowflake CLI 配置文件 中配置为命名配置，名称为 default_connection_name，在配置顶层设置（请参阅 设置默认连接）。您可以使用 snow connection set-default 命令更改默认连接。

默认情况下，SnowSQL 和 Snowflake CLI 都使用默认连接配置连接到 Snowflake。如果您在 SnowSQL 中进行了配置，则应将此配置迁移到 Snowflake CLI 配置文件中，如下所示：

1. 打开 SnowSQL 配置文件并在 [connections] 部分找到默认连接参数。向 Snowflake CLI 添加连接时，需要连接参数的值。

2. 要将连接添加到 Snowflake CLI，请使用以下方法之一：

   • 手动编辑 Snowflake CLI 配置文件，如下所示：

     1. 打开 Snowflake CLI 配置文件。

     2. 添加 [connections.your_connection_name] 部分，然后从 SnowSQL 配置文件中复制/粘贴默认配置详细信息。

     3. 更改以下参数的名称，如下所示：

        • accountname 更改为 account

        • username 更改为 user

        • dbname 更改为 database

        • schemaname 更改为 schema

        • warehousename 更改为 warehouse

        • rolename 更改为 role

     4. 在配置文件的顶层添加或设置 default_connection_name = "your_connection_name" 设置（请参阅 设置默认连接）。

   • 使用 snow connection add 和 snow connection set-default 命令。有关更多信息，请参阅 使用 snow connection 命令管理连接或将其添加到 Snowflake。

手动迁移您的命名连接配置¶

如果您不使用 snow helpers import-snowsql-connections 命令来导入您的连接，可以手动迁移它们。

指定命名连接的区别包括以下几点：

• SnowSQL

  命名连接是在 SnowSQL 配置文件 中配置的。每个命名连接都有自己的 [connections.your_connection_name] 部分。

• Snowflake CLI

  Snowflake CLI 使用几乎相同的格式来 配置命名连接。您可以从 SnowSQL 配置中复制它们，并按照默认连接中指定的方式重命名参数。

默认情况下，SnowSQL 和 Snowflake CLI 都允许您使用命名连接来连接到 Snowflake。如果您想继续在 SnowSQL 中使用这些命名连接，则应将它们迁移到 Snowflake CLI 配置文件：

1. 打开 SnowSQL 配置文件并找到 [connections.your_connection_name] 部分。向 Snowflake CLI 添加 连接 时，需要连接参数的值。

2. 要将连接添加到 Snowflake CLI，请使用以下方法之一：

   • 手动编辑 Snowflake CLI 配置文件，如下所示：

     1. 打开 Snowflake CLI 配置文件。

     2. 添加 [connections.your_connection_name] 部分，然后从 SnowSQL 配置文件中复制/粘贴默认配置详细信息。

     3. 更改以下参数的名称，如下所示：

        • accountname 更改为 account

        • username 更改为 user

        • dbname 更改为 database

        • schemaname 更改为 schema

        • warehousename 更改为 warehouse

        • rolename 更改为 role

   • 使用 snow connection add 命令。有关更多信息，请参阅 使用 snow connection 命令管理连接或将其添加到 Snowflake。

配置日志¶

要手动配置 Snowflake CLI 的日志记录，请参阅 配置日志记录 文档。

迁移您的变量¶

Snowflake CLI 不支持在其配置文件中指定变量。它使用更注重项目的方法，将变量与特定项目相关联。Snowflake CLI 允许您在:file:snowflake.yml 项目定义文件 中定义变量。然后，您可以按 关于项目定义文件 中所述，在 SQL 查询中使用这些变量。

• 要为项目定义变量，请在项目的 snowflake.yml 文件中添加 env 部分，并在查询中加入要使用的任何变量。

以下示例定义了两个变量：database 和 role：

definition_version: 2
env:
  database: "dev"
  role: "eng_rl"

手动迁移您的环境变量¶

In SnowSQL, you can use environment variables (like $SNOWSQL_ACCOUNT and $SNOWSQL_DATABASE) instead of specifying command-line parameters when starting a connection. This approach provides another way to specify default connection configurations. Snowflake CLI offers the same functionality but uses different names for these parameters and allows you to override many more configuration parameters via environment variables. If you're using environment variables to connect to Snowflake, for more information, see connecting to Snowflake with environment variables. Also, see information about possibilities for configuring environment variables in the Snowflake CLI documentation.

使用默认连接¶

• 要使用配置文件中定义的默认配置进行连接，请执行以下操作：

  • SnowSQL

    snowsql -q "select 1"
    

    Copy

  • Snowflake CLI

    snow sql -q "select 1"
    

    Copy

使用带有命令行选项的连接¶

• 要使用配置文件中定义的默认配置进行连接，并使用命令行选项替换参数，请执行以下操作：

  • SnowSQL

    snowsql --username myname -q "select 1"
    

    Copy

  • Snowflake CLI

    snow sql --username myname -q "select 1"
    

    Copy

    有关可用的命令行选项的列表，请参阅 snow sql。请注意，某些选项的名称与 SnowSQL 中的名称不同。

使用命名配置¶

• 要使用配置文件中定义的命名配置进行连接，请执行以下操作：

  • SnowSQL

    snowsql -c dev -q "select 1"
    

    Copy

  • Snowflake CLI

    snow sql -c dev -q "select 1"
    

    Copy

仅使用命令行选项¶

• 要仅使用命令行选项而不是使用已配置的连接进行连接，请执行以下操作：

  • SnowSQL

    snowsql \
      --accountname myaccount \
      --username myuser \
      --authenticator SNOWFLAKE_JWT \
      --private-key-path "path_to_my_key" \
      -q "select 1"
    

    Copy

  • Snowflake CLI

    snow sql \
      --temporary-connection \
      --accountname myaccount \
      --username myuser \
      --authenticator SNOWFLAKE_JWT \
      --private-key-path "path_to_my_key" \
      -q "select 1"
    

    Copy

    请注意，Snowflake CLI 要求将 --temporary-connection 选项用于此方法。

使用环境变量¶

• 要使用默认连接进行连接，请将某些参数作为环境变量传递：

  • SnowSQL

    export SNOWSQL_USER=myuser
    snowsql -q "select 1"
    

    Copy

  • Snowflake CLI

    export SNOWFLAKE_USER=myuser
    snow sql -q "select 1"
    

    Copy

    请注意，环境变量的名称可能有所不同。有关更多信息，请参阅 为 Snowflake 凭据使用环境变量。

结合使用连接、环境变量和命令行选项¶

• 要使用包含命名连接、环境变量和命令行选项的混合方法进行连接，请执行以下操作：

  • SnowSQL

    export SNOWSQL_USER=myuser
    snowsql -c dev --accountname myaccount -q "select 1"
    

    Copy

  • Snowflake CLI

    export SNOWFLAKE_USER=myuser
    snow sql -c dev --accountname myaccount -q "select 1"
    

    Copy

    您可以将此方法与默认连接和命名连接一起使用。

通过各种输入执行 SQL 查询¶

Snowflake CLI 允许您使用与 SnowSQL 所处理的输入类似的输入来执行 SQL 查询。以下示例使用各种输入执行 SQL 查询。

• 使用命令行参数执行查询：

  • SnowSQL

    snowsql -q "select 1"
    

    Copy

  • Snowflake CLI

    snow sql -q "select 1"
    

    Copy

• 通过文件执行查询：

  • SnowSQL

    snowsql -f test.sql
    

    Copy

  • Snowflake CLI

    snow sql -f test.sql
    

    Copy

• 通过标准输入执行查询：

  • SnowSQL

    cat test.sql | snowsql
    

    Copy

  • Snowflake CLI

    cat test.sql | snow sql --stdin
    

    Copy

将查询结果保存到 JSON 文件中¶

Snowflake CLI 目前不支持部分 SnowSQL 输出格式选项。Snowflake CLI 确实允许您将查询结果另存为格式化表或 JSON。尽管 CSV 和其他格式尚不可用，但您可以使用外部工具（例如 jq (https://jqlang.org/)），从 JSON 的其他格式转换数据。

• SnowSQL

  snowsql \
    -f test.sql \
    -o "output_format=json" \
    -o "output_file=result.json"
  

  Copy

• Snowflake CLI

  snow sql -f test.sql --format json > result.json
  

  Copy

使用变量执行查询¶

SnowSQL 和 Snowflake CLI 都允许您在查询中使用变量。SnowSQL 允许您使用命令行选项中的变量、其配置文件中的变量，以及使用一些:ref:内置变量 <label-snowsql_variables>。尽管 Snowflake CLI 不支持在其配置文件中使用变量或使用内置变量，但它确实支持使用命令行选项指定参数以及在项目定义文件中指定变量。有关迁移 SnowSQL 配置文件变量的信息，请参阅 迁移您的变量。

从 SnowSQL 的配置迁移变量后，您可以使用命令行选项和项目定义中的变量运行 Snowflake CLI 查询。

使用变量时，请注意 SnowSQL 和 Snowflake CLI 之间的以下重要区别：

• 它们使用不同的语法进行变量替换。SnowSQL 使用 &variable 或 &{variable} 语法，而 Snowflake CLI 使用 <% variable %>。目前支持 SnowSQL 中的语法，但该语法已弃用。

• Snowflake CLI 自动启用变量替换，因此您无需像使用 SnowSQL 一样明确启用它。

• Snowflake CLI 项目定义文件中的变量名称必须以 ctx.env 为前缀，如下所示：

以下示例显示了使用变量执行 SQL 查询时的区别：

• 使用命令行选项中的变量执行查询，其中 x 是变量名称：

  • SnowSQL

    snowsql \
      -o variable_substitution=true \
      -q "select &x" \
      -D x=1
    

    Copy

  • Snowflake CLI

    snow sql \
      -q "select <% x %>" \
      -D x=1
    

    Copy

  • |sf-cli|（使用已弃用的语法来实现快速迁移）

    snow sql \
      -q "select &x" \
      -D x=1
    

    Copy

• 对比使用 SnowSQL 配置中的变量与使用 Snowflake CLI 项目定义文件中的变量执行查询：

  • SnowSQL

    # save variables to config
    echo "[variables]
    xyz=Hello World" > custom_config
    
    
    # execute query
    snowsql \
      --config custom_config \
      -o variable_substitution=true \
      -q "select '&{xyz}'"
    

    Copy

  • Snowflake CLI

    # save variables to project definition
    echo "definition_version: 2
    env:
      xyz: Hello World" > snowflake.yml
    
    # execute query
    snow sql -q "select '<% ctx.env.xyz %>'"
    

    Copy

  • |sf-cli|（使用已弃用的语法来实现快速迁移）

    # save variables to project definition
    echo "definition_version: 2
    env:
      xyz: Hello World" > snowflake.yml
    
    
    # execute query
    snow sql -q "select '&{ctx.env.xyz}'"
    

    Copy