Implantar e gerenciar DCM Projects¶

Ferramentas de interface¶

Você tem as seguintes opções de interface disponíveis para DCM Projects.

Integração com Git¶

Conecte-se ao repositório Git em que seus arquivos de definição de DCM project estão armazenados.

Funções e privilégios necessários¶

A função do usuário que cria um objeto de DCM project deve ter as seguintes funções e privilégios:

• O privilégio CREATE DCM PROJECT ON SCHEMA:

  CopyExpand

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

  Show lessSee more

  Scroll to top

Criar uma DCM project¶

Crie um objeto de DCM project usando uma das seguintes opções.

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

Propriedade de objetos gerenciados por DCM¶

A função que implanta um DCM project, por padrão, tem o privilégio OWNERSHIP de todos os objetos implantados.

As definições de projeto podem incluir instruções GRANT OWNERSHIP para outras funções. A Snowflake recomenda que a função de proprietário de DCM project conceda a propriedade de objetos gerenciados por DCM apenas para outra função de nível inferior que ela também tenha. Assim, o projeto pode continuar gerenciando esse objeto, pois a função de proprietário do projeto «herda» os privilégios da nova função proprietária do objeto.

Se a função de proprietário do DCM project conceder a propriedade de objetos gerenciados por DCM para outra função que ela não tenha, o projeto não poderá mais gerenciar esse objeto implantado, pois a função de proprietário do projeto não terá mais a propriedade dele. As implantações subsequentes falharão. A definição do objeto precisa ser removida do projeto ou a propriedade precisa ser concedida de volta à função de proprietário do projeto.

Se você deseja migrar objetos existentes para serem gerenciados por um DCM project, a função que tem o objeto de DCM project também precisa ter privilégios de propriedade (diretos ou herdados por meio de outras funções) no objeto a ser gerenciado pelo DCM project.

Execução do comando PLAN¶

O comando PLAN recebe as seguintes informações como entrada:

• O caminho para o arquivo de manifesto

  O CLI lê o destino do manifesto (sinalizador default_target ou --target). Para comandos SQL, o caminho para o arquivo de manifesto e o nome do projeto devem ser fornecidos.

• Valores definidos para variáveis ​​Jinja (opcional).

• O templating_config do destino seleciona automaticamente o perfil de configuração. Para comandos SQL, use a cláusula USING CONFIGURATION para especificar o perfil.

• Um ou mais valores do perfil de configuração a serem substituídos (opcional).

A seguir, veja exemplos de como executar o comando PLAN.

Snowflake CLISnowsightSQL

Execute o comando snow dcm plan em seu terminal IDE local ou como parte de um fluxo de trabalho Git.

Um exemplo de comando CLI para planejar um projeto DCM a partir de um diretório local é:

CopyExpand

cd ./Quickstarts/DCM_Project_Quickstart_1/
snow dcm plan

Show lessSee more

Scroll to top

Um exemplo de comando CLI para planejar um projeto DCM a partir de uma área de preparação do Snowflake ou clone de repositório Git é:

CopyExpand

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

Show lessSee more

Scroll to top

Um exemplo de comando CLI para planejar um projeto DCM com argumentos opcionais é:

CopyExpand

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

Show lessSee more

Scroll to top

As variáveis ​​devem estar entre aspas duplas, com aspas simples adicionais para valores de cadeia de caracteres. As listas de valores devem ficar entre colchetes.

Caminho do arquivo de definição¶

Você tem as seguintes opções para referenciar a localização dos arquivos de manifesto e definição.

• A partir de um caminho do Workspace

  A interface do usuário do Snowsight lista automaticamente todas as definições de DCM project dentro do espaço de trabalho atual. Você pode selecionar um desses caminhos, e os espaços de trabalho o usarão para executar comandos DCM.

  Se você quiser executar comandos SQL manualmente em espaços de trabalho, também poderá referenciar o mesmo caminho em qualquer um dos seus espaços de trabalho.

  Dica: o menu de três pontos atrás de cada arquivo em seu espaço de trabalho permite copiar o caminho completo para esse arquivo em seu código SQL.

  Um exemplo de um comando SQL para planejar um projeto DCM a partir de um caminho de espaço de trabalho é:

  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

• A partir de um clone de repositório Git local em seu disco

  Selecione o diretório que contém seu arquivo manifest.yml antes de executar o comando CLI em seu IDE local. Como alternativa, você pode especificar um diretório local diferente que contenha o manifesto e as definições que deseja usar.

  Exemplo de um comando CLI para planejar um DCM project a partir do diretório atual de um repositório Git local:

  CopyExpand

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

  Show lessSee more

  Scroll to top

  Exemplo de um comando CLI para planejar um DCM project a partir de um diretório diferente em um clone de repositório Git local:

  CopyExpand

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

  Show lessSee more

  Scroll to top

• A partir de seu repositório remoto em um fluxo de trabalho

  A mesma sintaxe CLI pode ser utilizada quando os comandos DCM são executados em um fluxo de trabalho CI/CD.

  Um exemplo de um fluxo de trabalho CI/CD para planejar um DCM project a partir de um clone de repositório Git local:

  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

• A partir de um clone de repositório Git ou área de preparação no Snowflake

  Caso você queira executar um procedimento ou uma tarefa dentro do Snowflake que execute comandos DCM, este comando SQL pode referenciar um caminho absoluto para uma área de preparação do Snowflake ou um clone de repositório Git dentro da conta.

  Para clones de repositórios Git, considere executar primeiro ALTER GIT REPOSITORY FETCH para obter a versão mais recente.

  Só é possível utilizar os caminhos '@...' ​​ao executar comandos DCM SQL.

  Um exemplo de um comando SQL para planejar um projeto DCM a partir de uma área de preparação ou clone de repositório Git no Snowflake é:

  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

Saída do plano¶

A saída padrão do plano contém as seguintes informações sobre a execução do plano no formato 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>
          }
        ]
      }
    ]
  }
}

Exemplo de saída de um plano:

{
  "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": []
    }
  ]
}

Execução do comando DEPLOY¶

Para executar o comando DEPLOY, forneça as seguintes entradas:

• O caminho para o arquivo de manifesto.

• Será preciso nomear um perfil de configuração se perfis de configuração estiverem definidos no manifesto.

• Como opção, valores para o perfil de configuração que substituem os valores padrão.

• Como opção, um alias de implantação.

A seguir, veja exemplos de como executar o comando 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'

Consulte Saída do plano para obter a estrutura de saída padrão do plano.

Mostrar todos os objetos gerenciados por um DCM project¶

O comando SHOW ENTITIES IN DCM PROJECT permite que você veja uma lista de todos os objetos Snowflake que estão sendo gerenciados por um DCM project específico. Ele fornece uma lista de nomes totalmente qualificados para todos os objetos. Para ver os resultados, você precisa do privilégio READ no DCM project e dos privilégios para ver o próprio objeto gerenciado.

Você pode usar LIKE para pesquisar por nome ou utilizar um operador de fluxo para processar ou filtrar ainda mais o conjunto de resultados.

Da mesma forma, você pode usar SHOW GRANTS e SHOW FUTURE GRANTS que estão definidos e implantados com esse projeto.

Exemplos para ver todos os objetos que estão sendo gerenciados por um 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;

Desvincular objetos de um DCM project¶

Usando o comando ALTER <objeto> com a cláusula UNSET DCM PROJECT, você pode desvincular um objeto que foi implantado e agora é gerenciado por um DCM project. O comando remove a associação entre o objeto e o DCM project sem descartar o objeto. É possível usar esse comando quando você quer começar a gerenciar um objeto por um DCM project diferente.

Remova a instrução DEFINE correspondente dos arquivos de definição do seu projeto antes de implantá-lo novamente. Caso contrário, o objeto será reintegrado ao DCM project.

Um exemplo de comando SQL para desvincular um objeto de um DCM project:

ALTER TABLE MY_DB.MY_SCH.MY_TABLE
  UNSET DCM PROJECT;

Você não pode desvincular concessões ou execuções implantadas de um projeto DCM.

Descartar um DCM project¶

Quando um objeto DCM project é descartado, todas as entidades, concessões e expectativas gerenciadas permanecem como «não gerenciadas».

DROP DCM PROJECT [IF EXISTS] <my_project>;

snow dcm drop my_project

Práticas recomendadas para CI/CD¶

Siga estas práticas ao automatizar implantações com pipelines de CI/CD:

• Um DCM project destinado a um ambiente de não produção deve pertencer a uma função diferente da sua contraparte de produção para evitar implantações acidentais em produção.

• Um DCM project destinado a um ambiente de produção deve pertencer a uma função dedicada para implantações de produção com privilégios de acesso especificamente adaptados, suficientes apenas para implantar todos os objetos no projeto.

  • Evite usar funções de administrador geral para a propriedade de DCM project. Conceda essas funções apenas a usuários de serviço, não a desenvolvedores individuais.

  • Conceda a função dedicada de implantação de produção apenas a usuários de serviço, não a desenvolvedores individuais.

  • Restrinja a propriedade à função de implantação de produção para garantir a imutabilidade de infraestrutura crítica ou produtos de dados.

    Se a função dedicada de implantação de produção conceder a propriedade de objetos de produção a outras funções, os usuários que receberem essas funções ainda poderão modificar ou descartar os objetos de produção.

Exemplos do GitHub Actions¶

Esta seção fornece amostras de fluxos de trabalho do GitHub Actions que ilustram padrões típicos de CI/CD para DCM Projects. Os mesmos conceitos se aplicam a outras plataformas baseadas em Git, como Azure DevOps, GitLab CI/CD ou Bitbucket Pipelines; apenas a sintaxe do fluxo de trabalho difere.

Cada amostra fornece componentes básicos que você pode personalizar e combinar com base na configuração do seu pipeline, na topologia do ambiente e nos requisitos organizacionais.

As amostras de fluxos de trabalho demonstram os seguintes padrões aplicáveis ​​a qualquer configuração de DCM CI/CD:

• Configuração orientada por manifesto Cada fluxo de trabalho lê account_identifier, project_owner e project_name dos destinos do manifesto. Isso mantém a configuração do ambiente em um só lugar e evita duplicá-la em vários segredos do GitHub.

• Proteção contra descarte de dados O fluxo de trabalho de implantação analisa plan_result.json em busca de operações DROP destrutivas em objetos que contêm dados, como bancos de dados, esquemas, tabelas e áreas de preparação, e bloqueia a implantação se alguma for encontrada.

• Promoção sequencial da área de preparação para a produção A implantação em produção começará somente após a implantação da área de preparação ser concluída com sucesso, as tabelas dinâmicas serem atualizadas e os testes de qualidade de dados serem aprovados.

• Análise estruturada da saída do plano Os fluxos de trabalho usam jq para extrair contagens de operações e domínios de objetos de plan_result.json, facilitando a criação de resumos e verificações personalizados.

• Resumos com tecnologia de AI snow cortex complete gera resumos em linguagem natural dos resultados do script post-hook e da saída de atualização de tabelas dinâmicas para o resumo do trabalho do GitHub Actions.

Antes de executar essas amostras de fluxos de trabalho, conclua os seguintes pré-requisitos:

• Armazene os arquivos de DCM project em um repositório Git.

• Conceda privilégios a um usuário para criar e executar ações do GitHub.

• Configure segredos do GitHub para as credenciais do usuário do serviço Snowflake (SNOWFLAKE_USER, SNOWFLAKE_PASSWORD ou um token de acesso pessoal).

• Configure variáveis do ​​GitHub para o caminho da pasta do DCM project (DCM_PROJECT_PATH).

• Configure ambientes do GitHub para cada destino do manifesto (por exemplo, DCM_STAGE, DCM_PROD_US).

Para configurar uma conexão do Snowflake no GitHub Actions, consulte a primeira metade da postagem do blog Um guia prático para CI/CD com o GitHub Actions.

Consulte o repositório snowflake-labs DCM para obter um conjunto de fluxos de trabalho do GitHub Actions que abrangem todo o ciclo de vida de CI/CD de DCM Projects.

Todas as amostras de fluxos de trabalho leem a função account_identifier e project_owner do Snowflake diretamente dos destinos do manifesto usando yq, de modo que a configuração específica do ambiente reside no manifest.yml com controle de versão, em vez de em segredos do GitHub duplicados. Somente as credenciais do usuário do serviço são armazenadas como segredos.