部署和管理 DCM Projects¶

界面工具¶

您可以为 DCM Projects 使用以下界面选项。

Git 集成¶

连接到存储 DCM project 定义文件的 Git 存储库。

所需的角色和权限¶

创建 DCM project 对象的用户角色必须具有以下角色和权限：

• CREATE DCM PROJECT ON SCHEMA 权限：

  CopyExpand

  GRANT CREATE DCM PROJECT ON SCHEMA <schema_name> TO ROLE <role_name>;
  

  Show lessSee more

  Scroll to top

创建 DCM project¶

使用以下选项之一创建 DCM project 对象。

CREATE [OR REPLACE] DCM PROJECT [IF NOT EXISTS] <my_project>
[COMMENT = 'my comment'];

snow dcm create <my_project> --if-not-exists

snow dcm create <my_project> --if-not-exists

snow dcm create # uses the name specified in the default target from the manifest

snow dcm create --target # uses the named target from the manifest

DCM 所有权 - 受管理对象¶

默认情况下，部署 DCM project 的角色具有所有已部署对象的 OWNERSHIP 权限。

项目定义可以包括对其他角色的 GRANT OWNERSHIP 语句。Snowflake 建议 DCM project 所有者角色仅将 DCM 管理对象的所有权授予它也拥有的另一个较低级别的角色。然后，项目可以继续管理此对象，因为项目所有者角色会“继承”新对象所有者角色的权限。

如果 DCM project 所有者角色将 DCM 管理对象的所有权授予给另一个自身不拥有的角色，则项目将无法再管理此已部署的对象，因为项目所有者角色不再拥有该对象的所有权。后续部署将失败。需要从项目中移除对象定义，或者需要将所有权重新授予项目所有者角色。

如果要将现有对象迁移到由 DCM project 管理，拥有 DCM project 对象的角色还必须拥有由 DCM project 管理的对象的所有权权限（直接所有权或通过其他角色继承的所有权）。

运行 PLAN 命令¶

PLAN 命令会将以下信息作为输入：

• 清单文件的路径

  CLI 从清单中读取目标（default_target 或 --target 标志）。对于 SQL 命令，必须提供清单文件的路径和项目名称。

• Jinja 变量的定义值（可选）。

• 目标的 templating_config 会自动选择配置文件。对于 SQL 命令，使用 USING CONFIGURATION 子句来指定配置文件。

• 要覆盖的配置文件的一个或多个值（可选）。

以下示例展示了如何运行 PLAN 命令。

Snowflake CLISnowsightSQL

在本地 IDE 终端运行 snow dcm plan 命令或作为 Git 工作流程的一部分运行。

使用 CLI 命令来计划本地目录中的项目 DCM 的示例：

CopyExpand

cd ./Quickstarts/DCM_Project_Quickstart_1/
snow dcm plan

Show lessSee more

Scroll to top

使用 CLI 命令计划来自 Snowflake 暂存区或 Git 存储库克隆的项目 DCM 的示例是：

CopyExpand

snow dcm plan --target PROD_US --save-output

Show lessSee more

Scroll to top

使用 CLI 命令计划具有可选实参的项目 DCM 的示例是：

CopyExpand

snow dcm plan
--variable "wh_size='MEDIUM'" --variable "teams = ['TEAM_A', 'TEAM_B']"
--save-output

Show lessSee more

Scroll to top

变量需要放在双引号内，字符串值需要加上单引号。值列表需要方括号。

定义文件路径¶

您可以使用以下选项来引用清单和定义文件的位置。

• 从工作区路径

  Snowsight 用户界面会自动列出所有当前工作区中的 DCM project 定义。您可以选择其中一个路径，工作区将使用它来运行 DCM 命令。

  如果您想在工作区中手动运行 SQL 命令，您还可以在任何工作区中引用相同的路径。

  提示： 工作区中每个文件后面的三点菜单可让您将该文件的完整路径复制到您的 SQL 代码。

  使用 SQL 命令，通过工作区路径计划 DCM 项目的示例是：

  CopyExpand

  EXECUTE DCM PROJECT DCM_PROJECT_DEV
    PLAN
    USING CONFIGURATION DEV
  FROM
    'snow://workspace/USER$.PUBLIC.DEFAULT$/versions/live/Quickstarts/DCM_Project_Quickstart_1'
  

  Show lessSee more

  Scroll to top

• 从磁盘上的本地 Git 存储库克隆

  在本地 IDE 中运行 CLI 命令之前，请选择包含 manifest.yml 文件的目录或者，您可以指定其他本地目录，其中包含要使用的清单和定义。

  CLI 命令从本地 Git 存储库的当前目录计划 DCM project 的示例：

  CopyExpand

  cd ./Quickstarts/DCM_Project_Quickstart_1/
  
  snow dcm plan
  
  snow dcm plan --target PROD
  

  Show lessSee more

  Scroll to top

  CLI 命令从本地 Git 存储库克隆中的不同目录计划 DCM project 的示例：

  CopyExpand

  snow dcm plan DCM_PROJECT_DEV --configuration DEV --from ./Quickstarts/DCM_Project_Quickstart_2/
  

  Show lessSee more

  Scroll to top

• 来自工作流程中的远程存储库

  可以在 DCM 命令在 CI/CD 工作流程中执行时使用相同的 CLI 语法。

  CI/CD 工作流程从本地 Git 存储库克隆计划 DCM project 的示例：

  CopyExpand

  steps:
    - name: Clone Repo
      uses: actions/checkout@v4
    - name: Setup SnowCLI
      uses: snowflakedb/snowflake-cli-action@v2.0
    - name: Run PLAN
      run: |
        cd ./Quickstarts/DCM_Project_Quickstart_1/
        snow dcm plan --target PROD --save-output
  

  Show lessSee more

  Scroll to top

• 来自 Snowflake 中的暂存区或 Git 存储库克隆

  如果您想在 Snowflake 中运行执行 DCM 命令的过程或任务，此 SQL 命令可以引用账户内 Snowflake 暂存区或 Git 存储库克隆的绝对路径。

  对于 Git 存储库克隆，请考虑首先运行 ALTER GIT REPOSITORY FETCH 以获得最新版本。

  '@...' 路径只能在执行 DCM SQL 命令时使用。

  SQL 命令从 Snowflake 中暂存区或 Git 存储库克隆计划 DCM 项目的示例是：

  CopyExpand

  EXECUTE DCM PROJECT DCM_PROJECT_DEV
    PLAN
    USING CONFIGURATION DEV
  FROM
    '@DCM_DEMO.DEPLOY.DCM_DEMO/branches/main/Quickstarts/DCM_Project_Quickstart_1/'
  

  Show lessSee more

  Scroll to top

计划输出¶

标准计划输出包含以下有关计划执行的 JSON 格式信息：

version: 2
metadata:
  timestamp: <timestamp>
  query_id: <query_id>
  project_name: <project_name>
  user: <user>
  role_name: <role_name>
  command: <command>
  changes:
    - kind: <kind>
        "attribute_name": <attribute_name>,
        "value": <value>
        "changes": [
          {
            "kind": <kind>,
            "attribute_name": <attribute_name>,
            "value": <value>
          }
        ]
      }
    ]
  }
}

计划输出的示例：

{
  "version": 2,
  "metadata": {
    "timestamp": <timestamp>,
    "query_id": <query_id>,
    "project_name": <project_name>,
    "user": <user>,
    "role_name": <role_name>,
    "command": <command>
  },
  "changeset": [
    {
      "type": "CREATE",
      "object_id": {
        "domain": "TABLE",
        "name": "CUSTOMER_SUMMARY",
        "fqn": "MY_DB.ANALYTICS.CUSTOMER_SUMMARY",
        "database": "MY_DB",
        "schema": "ANALYTICS"
      },
      "changes": [
        {
          "kind": "set",
          "attribute_name": "warehouse_size",
          "value": "XSMALL"
        },
        {
          "kind": "set",
          "attribute_name": "query",
          "value": "SELECT customer_id, SUM(amount) AS total FROM orders GROUP BY customer_id"
        }
      ]
    },
    {
      "type": "ALTER",
      "object_id": {
        "domain": "DYNAMIC_TABLE",
        "name": "ORDER_DETAILS",
        "fqn": "MY_DB.ANALYTICS.ORDER_DETAILS",
        "database": "MY_DB",
        "schema": "ANALYTICS"
      },
      "changes": [
        {
          "kind": "changed",
          "attribute_name": "warehouse_size",
          "value": "SMALL",
          "prev_value": "XSMALL"
        },
        {
          "kind": "collection",
          "collection_name": "columns",
          "id_label": "name",
          "changes": [
            {
              "kind": "added",
              "item_id": "DISCOUNT_AMOUNT",
              "changes": [
                {
                  "kind": "set",
                  "attribute_name": "data_type",
                  "value": "NUMBER(10,2)"
                }
              ]
            },
            {
              "kind": "modified",
              "item_id": "ORDER_STATUS",
              "changes": [
                {
                  "kind": "changed",
                  "attribute_name": "data_type",
                  "value": "VARCHAR(50)",
                  "prev_value": "VARCHAR(20)"
                }
              ]
            },
            {
              "kind": "removed",
              "item_id": "LEGACY_FLAG"
            }
          ]
        }
      ]
    },
    {
      "type": "DROP",
      "object_id": {
        "domain": "VIEW",
        "name": "OLD_REPORT_VIEW",
        "fqn": "MY_DB.ANALYTICS.OLD_REPORT_VIEW",
        "database": "MY_DB",
        "schema": "ANALYTICS"
      },
      "changes": []
    }
  ]
}

运行 DEPLOY 命令¶

要执行 DEPLOY 命令，请提供以下输入：

• 清单文件的路径。

• 如果在清单中定义了配置文件，则必须命名配置文件。

• （可选）配置文件的值将替换默认值。

• （可选）部署 别名。

以下示例展示了如何运行 DEPLOY 命令。

EXECUTE DCM PROJECT DCM_DEMO.PROJECTS.DCM_PROJECT_DEV
  DEPLOY
FROM
  'snow://workspace/USER$.PUBLIC.DEFAULT$/versions/live/Quickstarts/DCM_Project_Quickstart_1';

EXECUTE DCM PROJECT DCM_DEMO.PROJECTS.DCM_PROJECT_DEV
  DEPLOY AS "testing 2 teams"
  USING CONFIGURATION DEV (wh_size => 'MEDIUM', teams => ['TEAM_A', 'TEAM_B'])
FROM
  'snow://workspace/USER$.PUBLIC.DEFAULT$/versions/live/Quickstarts/DCM_Project_Quickstart_1';

cd ./Quickstarts/DCM_Project_Quickstart_1/
snow dcm deploy DCM_DEMO.PROJECTS.DCM_PROJECT_DEV

snow dcm deploy --target PROD_US

snow dcm deploy DCM_DEMO.PROJECTS.DCM_PROJECT_DEV \
--configuration DEV \
--variable "wh_size='MEDIUM'" --variable "teams = ['TEAM_A', 'TEAM_B']" \
--alias 'testing 2 teams'

请参阅 计划输出，了解标准计划输出结构。

显示由 DCM project 管理的所有对象¶

SHOW ENTITIES IN DCM PROJECT 命令允许您查看当前由特定 DCM project 管理的所有 Snowflake 对象的列表。它提供所有对象的完全限定名称列表。要查看结果，您需要 DCM project 上 READ 的权限以及查看托管对象本身的权限。

您可以使用 LIKE，按名称搜索或使用流运算符进一步处理或筛选结果集。

同样，您可以使用随此项目定义和部署的 SHOW GRANTS 和 SHOW FUTURE GRANTS。

查看当前由 DCM project 管理的所有对象的示例：

SHOW ENTITIES LIKE '%DASHBOARD%' IN DCM PROJECT DCM_DEMO.PROJECTS.DCM_PROJECT_DEV;

SHOW ENTITIES IN DCM PROJECT DCM_DEMO.PROJECTS.DCM_PROJECT_DEV
  ->> SELECT * FROM $1 WHERE "object_type" = 'DYNAMIC_TABLE';

SHOW [FUTURE] GRANTS IN DCM PROJECT DCM_DEMO.PROJECTS.DCM_PROJECT_DEV;

从 DCM project 中分离对象¶

使用带有 UNSET DCM PROJECT 子句的 ALTER <object> 命令可以分离已部署且现在由 DCM project 管理的对象。该命令会移除对象和 DCM project 之间的关联，但不会删除对象。当您想开始通过不同的 DCM project 管理对象时，可以使用此命令。

在再次部署之前，确保从 项目定义文件 中移除相应的 DEFINE 语句。否则，该对象将被重新集成到 DCM project 中。

将对象与 DCM project 分离的命令 SQL 示例：

ALTER TABLE MY_DB.MY_SCH.MY_TABLE
  UNSET DCM PROJECT;

您不能将已部署的授权或期望与 DCM 项目分离。

删除 DCM project¶

当 DCM project 对象被删除后，所有托管实体、授权和期望仍保持为“非托管”状态。

DROP DCM PROJECT [IF EXISTS] <my_project>;

snow dcm drop my_project

CI/CD 最佳实践¶

在使用 CI/CD 管道自动部署时，请遵循以下实践：

• 以非生产环境为目标的 DCM project 应由与其生产环境对应的角色拥有，以避免意外部署到生产环境。

• 以生产环境为目标的 DCM project 应由生产部署的专用角色拥有，该角色具有专门定制的访问权限，这些权限足以部署项目中的所有对象。

  • 避免为 DCM project 所有权使用一般管理员角色。仅将此类角色授予服务用户，而不是单个开发者。

  • 仅将专用生产部署角色授予服务用户，而不是单个开发者。

  • 将所有权限制为生产部署角色，以确保关键基础设施或数据产品的不可变性。

    如果专用生产部署角色将生产对象的所有权授予其他角色，则被授予这些角色的用户仍然可以修改或删除生产对象。

GitHub 操作示例¶

本节提供描述 DCM Projects 中典型 CI/CD 模式的示例 GitHub 操作工作流程。同样的概念也适用于其他基于 Git 的平台，例如 Azure DevOps、GitLab CI/CD 或 Bitbucket Pipelines。不同的只有工作流程语法。

每个示例都提供了构建块，您可以根据管道设置、环境拓扑和组织要求对这些构建块进行自定义和组合。

示例工作流程演示了以下模式，适用于任何 DCM CI/CD 设置：

• 清单驱动的配置 每个工作流程会读取来自清单目标的 account_identifier、project_owner 和 project_name。这样可以将环境配置保留在一个位置，并避免在不同 GitHub 密钥处进行重复配置。

• 数据删除保护 部署工作流程会解析对数据承载对象（如数据库、架构、表和暂存区）的破坏性 DROP 操作的 plan_result.json，如果发现任何操作，则会阻止部署。

• 顺序暂存区生产升级 只有在暂存部署成功、动态表刷新且数据质量测试通过后，生产部署才会开始。

• 结构化计划输出解析 工作流程使用 jq 从 plan_result.json 中提取操作计数和对象域，从而轻松构建自定义摘要和检查。

• AI 支持的摘要 snow cortex complete 生成 post-hook 脚本结果的自然语言摘要和动态表刷新输出，供 GitHub 行为作业摘要使用。

在运行这些示例工作流程之前，请满足以下先决条件：

• 存储 Git 存储库中的 DCM project 文件。

• 授予用户创建和运行 GitHub 操作的权限。

• 配置Snowflake 服务用户凭据的 GitHub 密钥（SNOWFLAKE_USER、SNOWFLAKE_PASSWORD 或个人访问令牌）。

• 配置 DCM project 文件夹路径 (DCM_PROJECT_PATH) 的 GitHub 变量。

• 配置每个清单目标的 GitHub 环境（例如，DCM_STAGE、DCM_PROD_US）。

用于在 GitHub 操作中设置 Snowflake 连接，请参阅博客文章的前半部分，GitHub 操作 CI/CD 实用指南 (link removed)。

请参阅 snowflake-labs DCM 存储库 (https://github.com/Snowflake-Labs/snowflake_dcm_projects/GitHub_workflows)，了解一组涵盖了整个 DCM Projects 中 CI/CD 生命周期的 GitHub 操作工作流程。

所有示例工作流程都会使用 yq 从清单目标中直接读取 Snowflake account_identifier 和 project_owner 角色，以便特定于环境的配置存在于版本控制的 manifest.yml 而不是重复的 GitHub 密钥中。只有服务用户凭据会存储为密钥。