部署和管理 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 语法。您可以直接调用 CLI，或使用 snowflake-labs DCM 存储库中“可重复使用的 :ref:` GitHub Actions <label-dcm_github_actions>`”，这些操作会在内部处理 CLI 设置、身份验证和 DCM 命令。

  使用可重复使用的 dcm-plan 操作示例：

  CopyExpand

  steps:
    - uses: actions/checkout@v4
    - uses: Snowflake-Labs/snowflake-dcm-projects/actions/dcm-plan@v1
      with:
        target: PROD
        project-path: Quickstarts/DCM_Project_Quickstart_1/
        snowflake-user: ${{ env.SNOWFLAKE_USER }}
  

  Show lessSee more

  Scroll to top

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

  如果您想在 Snowflake 中运行执行 DCM 命令的 PROCEDURE 或 TASK，此 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

计划输出¶

对于 PLAN 和 DEPLOY 输出格式，包括 JSON 架构和示例，请参阅 EXECUTE DCM PROJECT 命令参考的 PLAN 和 DEPLOY 输出 部分。

运行 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 \
--target DCM_DEV \
--variable "wh_size='MEDIUM'" --variable "teams = ['TEAM_A', 'TEAM_B']" \
--alias 'testing 2 teams'

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

显示由 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 Actions¶

snowflake-labs DCM 存储库 (https://github.com/Snowflake-Labs/snowflake-dcm-projects) 提供了一组可重复使用的复合 GitHub Actions，用于自动执行 DCM Projects 管道。每个操作负责生命周期的一个步骤，您可以从自己的工作流程中引用它们，构建端到端的 CI/CD 管道。仅不同平台的工作流程语法有所区别；同样的 CI/CD 概念适用于 Azure DevOps、GitLab CI/CD、Bitbucket Pipelines 等。

以下是可用的可重复使用的操作：

要在工作流程中使用某个操作，请通过以下方式引用该操作：

- uses: Snowflake-Labs/snowflake-dcm-projects/actions/<action-name>@v1

有关各操作输入和输出的完整文档，请参阅 操作 README (https://github.com/Snowflake-Labs/snowflake-dcm-projects/blob/main/actions/README.md)。

CREATE USER SVC_GITHUB_ACTIONS
  TYPE = SERVICE
  DEFAULT_ROLE = 'PUBLIC'
  COMMENT = 'GitHub Actions service user for CI/CD via OIDC'
  WORKLOAD_IDENTITY = (
    TYPE = OIDC
    ISSUER = 'https://token.actions.githubusercontent.com'
    SUBJECT = 'repo:<owner>/<repo>:environment:<env_name>'
  );