Implantar e gerenciar DCM Projects

Este tópico descreve como criar e implantar DCM Projects para gerenciar ambientes Snowflake, incluindo contas.

Gerenciar um DCM project envolve as seguintes etapas:

  1. Prepare sua conta Snowflake para um DCM project.

  2. Defina a configuração e os objetos do projeto nos arquivos do projeto.

  3. Crie um objeto de DCM Projects.

  4. Planeje a versão preliminar das alterações propostas antes da implantação.

  5. Implante o projeto.

  6. Mantenha o projeto monitorando, atualizando e repetindo o processo conforme necessário.

Você pode implantar continuamente alterações incrementais em seu projeto, bem como alterações de infraestrutura de conta em grande escala.

A Snowflake recomenda que você implante continuamente alterações e adições incrementais ao seu projeto, em vez de passar de 0 a 100 alterações de infraestrutura de conta em grande escala em uma única implantação.

Preparar-se para um DCM project

Para começar a usar DCM Projects, sua conta Snowflake deve atender aos seguintes pré-requisitos:

  • Um banco de dados e um esquema onde você possa criar seu objeto DCM Projects

  • Uma função com privilégios para criar um objeto DCM Projects e acesso para executar consultas em um warehouse

  • Para o Snowflake CLI, uma função com privilégios para criar uma área de preparação temporária

Esta seção descreve as tarefas que você precisa concluir para se preparar para DCM Projects:

Nota

O repositório do DCM snowflake-labs é atualizado continuamente com recursos para ajudar você a começar.

  • Projetos de demonstração e início rápido: clone o repositório em um espaço de trabalho do Snowflake ou em uma pasta local para testar os comandos de DCM Projects e explorar os recursos de DCM Projects.

  • GitHub Actions reutilizável: ações compostas para analisar manifestos, testar conexões, planejar e implantar DCM Projects em pipelines CI/CD. Para obter mais informações, consulte Ações do GitHub.

  • Amostras de fluxos de trabalho: arquivos de fluxo de trabalho prontos para uso que compõem as ações reutilizáveis ​​em pipelines CI/CD completos.

Ferramentas de interface

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

Ferramenta de interface

Melhor para

Snowsight

Um espaço de trabalho no Snowsight é um IDE nativo da nuvem Snowflake em sua conta.

  • Crie ou carregue facilmente arquivos de definição DCM via UI.

  • Conecte-se a um repositório Git para baixar e enviar alterações.

  • Revise, edite e depure arquivos de definição.

  • Execute comandos DCM, PLAN e DEPLOY usando a UI do espaço de trabalho.

  • Navegue pelo catálogo do banco de dados para ver objetos DCM project e a configuração, objetos gerenciados e o histórico de implantação deles.

  • Selecione um perfil de destino para usar automaticamente o DCM project vinculado e a configuração de modelos.

IDE local com o Snowflake CLI

A interface mais conhecida e personalizada para engenheiros de software.

  • Crie e edite arquivos de definição localmente.

  • Conecte-se a um repositório Git para baixar e enviar alterações.

  • Comandos do Snowflake CLI concisos com contexto de diretório e sinalizadores opcionais.

  • Saída com formatação rica e opção para salvar como um arquivo .json.

  • Opção para aproveitar o Cortex Code CLI para desenvolvimento assistido ou de agente.

  • Consulte Snowflake CLI para DCM Projects para obter informações sobre como instalar e executar o Snowflake CLI em seu IDE local.

Cortex Code

Uma ferramenta de AI de agente para Snowflake. Consulte Cortex Code para DCM Projects para obter mais informações.

  • Criação de arquivos de definição local auxiliada por AI ou por agentes.

  • Validação e depuração de código auxiliado por AI ou por agente por meio da execução de análise estática e comandos DCM PLAN.

Comandos SQL

  • Execute comandos SQL a partir do Snowflake CLI REPL, espaços de trabalho, notebooks ou planilhas.

  • Personalize comandos com argumentos adicionais.

  • Os mesmos comandos funcionam em todas as interfaces SQL do Snowflake.s.

Cortex Code para DCM Projects

O Cortex Code é uma ferramenta de AI de agente para o Snowflake. Com a habilidade DCM ativada, o Cortex Code pode criar, migrar, depurar e implantar DCM Projects de forma autônoma. Ele também pode trabalhar com você passo a passo.

Nota

O Cortex Code com a habilidade DCM está disponível atualmente apenas por meio do Cortex Code CLI. Ele não está disponível no Snowsight Workspaces.

A habilidade DCM com o Cortex Code permite o seguinte:

  • Criar um novo DCM project do zero, incluindo o arquivo de manifesto, a estrutura de pastas e os arquivos de definição.

  • Criar e editar instruções DEFINE, modelos Jinja e macros.

  • Executar comandos PLAN, DEPLOY, REFRESH, TEST e PREVIEW.

  • Interpretar a saída do plano, diagnosticar falhas e sugerir correções.

  • Baixar e inspecionar artefatos de implantação.

  • Navegar e explicar um DCM project existente.

Para começar a usar a habilidade DCM com o Cortex Code, siga estas etapas:

  1. Instale o Cortex Code CLI conforme descrito em Instalando o Cortex Code.

  2. Inicie o Cortex Code no seu terminal.

  3. Use a referência de habilidade $dcm ou use o termo DCM em seu prompt de linguagem natural para interagir com seus DCM Projects de forma conversacional.

Por exemplo:

  • «Crie um novo projeto DCM para nosso pipeline de análise»

  • «Planeje meu projeto em relação à meta PROD»

  • «Por que meu último plano falhou?»

  • «Adicione uma nova definição de tabela dinâmica para gastos do cliente»

Snowflake CLI para DCM Projects

O Snowflake CLI é uma interface de linha de comando para o Snowflake. É uma ferramenta que você pode usar para interagir com sua conta Snowflake a partir do seu IDE local.

  1. Os projetos DCM exigem a versão 3.16 ou superior do Snowflake CLI. Instale ou atualize o Snowflake CLI conforme descrito em Instalação do Snowflake CLI.

  2. Configure sua conexão com sua conta Snowflake conforme descrito em Configurando o Snowflake CLI e conectando-se ao Snowflake. Confirme se você tem uma conexão funcionando:

    snow connection test

  3. Navegue até o diretório local do seu clone do repositório Git. Por exemplo:

    cd ./Quickstarts/DCM_Quickstart_1

  4. Consulte os comandos do Snowflake CLI DCM disponíveis:

    snow dcm --help

Integração com Git

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

  1. Crie um novo espaço de trabalho a partir de um repositório Git.

  2. Crie ou selecione uma ramificação Git para suas alterações planejadas.

    O Snowflake clona os arquivos dessa ramificação para o editor do seu espaço de trabalho.

  3. Navegue até a pasta onde você tem seus arquivos de definição de DCM project ou onde deseja criá-los.

Criar uma DCM project

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:

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

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'];

Controle de acesso e privilégios de função

Você pode definir o controle de acesso baseado em função (role-based access control, RBAC) do objeto de DCM project de nível de esquema para privilégios READ, MONITOR ou OWNERSHIP.

Esses privilégios são independentes do controle de acesso para arquivos de definição armazenados em um espaço de trabalho, uma área de preparação ou um repositório.

Privilégio

Descrição

Operações permitidas

READ

  • Mostra se o objeto de DCM project existe.

  • Lista os objetos e as concessões implantados pelo DCM project, que são visíveis para a função do usuário.

    Isso significa que você precisa de READ no DCM project e READ nos próprios objetos.

  • SHOW DCM PROJECTS LIKE “%project”

  • DESCRIBE DCM PROJECT <project>

  • SHOW ENTITIES IN DCM PROJECT <project>

MONITOR

  • Concede acesso ao histórico completo de implantação, incluindo todos os artefatos.

  • Concede à função a capacidade de analisar, depurar ou auditar implantações de produção sem a capacidade de implantar alterações diretamente.

  • Todos os privilégios READ

  • DESCRIBE DCM PROJECT <project> (com o caminho de origem e de implantação da implantação mais recente)

  • INFORMATION_SCHEMA.DCM_DEPLOYMENT_HISTORY (project_name => “db.schema.project”)

  • SHOW DEPLOYMENTS IN DCM PROJECT <project>

  • LIST todos os arquivos na implantação

  • GET qualquer acesso a arquivos dentro do DCM project

OWNERSHIP

  • A função utilizada para criar o objeto de DCM project é a proprietária desse projeto.

  • Concede à função a capacidade de implantar alterações.

  • Concede à função a capacidade de transferir a propriedade do projeto para outra função quando o projeto ainda não tiver sido implantado.

  • Todos os privilégios MONITOR

  • EXECUTE DCM PROJECT <project> PLAN

  • EXECUTE DCM PROJECT <project> DEPLOY

  • EXECUTE DCM PROJECT <project> PREVIEW

  • EXECUTE DCM PROJECT <project> REFRESH

  • EXECUTE DCM PROJECT <project> TEST

  • DROP DCM PROJECT <project>

  • ALTER DCM PROJECT <project>

  • GRANT READ em DCM PROJECT <project> TO ROLE <role2>

  • GRANT MONITOR em DCM PROJECT <project> TO ROLE <role2>

Nota

Assim como outros comandos do Snowflake, EXECUTE DCM PROJECT respeita quando privilégios de funções secundárias estão habilitados para o usuário que executa o comando. Execute USE SECONDARY ROLES NONE; para que você não esteja utilizando privilégios de outras funções além da função de proprietário do projeto. Isso garante que o comportamento de implantação seja consistente em diferentes ambientes quando executado por diferentes usuários de serviço com a mesma função principal.

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.

Nota

Se for um objeto migrado, recomendamos adicionar a instrução GRANT OWNERSHIP correspondente às definições do projeto também para garantir que o estado atual e as definições do DCM project estejam sincronizados.

Definir um DCM project

Um DCM project é baseado em um arquivo de manifesto e um ou mais arquivos de definição de objeto SQL. Esses arquivos normalmente são armazenados e gerenciados em um repositório Git ou em seu espaço de trabalho local.

  • O arquivo de manifesto

    • Especifica um ou mais ambientes de destino com identificadores de conta correspondentes, objetos de DCM project, funções de proprietário para esses objetos e configurações de modelo opcionais

    • Opcionalmente, especifica os padrões de modelo e uma ou mais configurações com valores para variáveis ​ de modelo.

  • Os arquivos de definição de objeto

    • Defina um grupo de objetos, concessões e expectativas do Snowflake que você deseja gerenciar juntos neste DCM project.

Consulte Criar uma pasta de DCM project para armazenar seus arquivos de definição para saber como configurar uma pasta de DCM project e os arquivos de definição e como usar modelos para definir seu DCM project.

Planejar um DCM project

Planejar um DCM project executa uma simulação para visualizar as alterações antes da implantação. O Snowflake compara seus arquivos de definição de projeto com objetos existentes e mostra quais objetos serão criados, alterados ou descartados. Nenhuma alteração é feita em sua conta.

Use o planejamento para revisar e validar as alterações antes de implantar um projeto DCM. Você pode especificar opções como uma configuração ou um caminho de saída para os resultados do plano.

O comando PLAN imita o comando DEPLOY o máximo possível, exceto que ele não executa nenhuma instrução DDL.

Importante

Sempre execute o comando PLAN em seus projetos antes da implantação para garantir que não haja erros de sintaxe, modelos, dependência de objetos, privilégios de acesso e assim por diante. Revise a saída do plano para depurar quaisquer erros, visualizar o Jinja renderizado com as variáveis ​ fornecidas e visualizar as alterações que serão feitas após a implantação.

O plano executa as seguintes etapas:

  1. Renderiza todos os modelos Jinja com o perfil de configuração selecionado ou os valores fornecidos em tempo de execução.

  2. Compara todas as definições com o estado atual das entidades definidas como parte da última implantação.

  3. Converte todas as instruções definidas em instruções CREATE, ALTER, DROP, GRANT e REVOKE.

  4. Classifica todas as instruções com base em suas interdependências.

  5. Compila todas as instruções.

Nota

Embora PLAN detecte quase todos os erros possíveis que podem ocorrer durante a implantação, ele não garante uma implantação bem-sucedida.

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.

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 é:

cd ./Quickstarts/DCM_Project_Quickstart_1/
snow dcm plan

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 é:

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

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

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

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.

Comandos do Snowflake CLI

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 é:

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

  • 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:

    cd ./Quickstarts/DCM_Project_Quickstart_1/

snow dcm plan

snow dcm plan --target PROD

    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:

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

  • 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. Você pode chamar a CLI diretamente ou usar o GitHub Actions reutilizável do repositório DCM snowflake-labs, que lidam com a configuração da CLI, autenticação e comandos do DCM internamente.

    Um exemplo usando a ação dcm-plan reutilizável:

    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 }}

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

    Caso você queira executar um PROCEDURE ou TASK 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 é:

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

Saída do plano

Para conferir o formato de saída de PLAN e DEPLOY, incluindo o esquema JSON e exemplos, consulte a seção da saída de PLAN e DEPLOY na referência do comando EXECUTE DCM PROJECT.

Implantar um DCM project

Quando você implanta um DCM project, as seguintes ações são realizadas:

  • Objetos que estão definidos, mas ainda não existem, são criados.

  • Objetos que já existem, mas diferem da definição atual, são alterados.

  • Objetos que já existem conforme definidos são ignorados.

  • Objetos que já existem, mas não estão mais definidos, são descartados.

O mesmo comportamento se aplica a concessões e expectativas de qualidade de dados anexadas definidas no projeto.

Importante

Para evitar qualquer perda de dados não intencional, sempre execute e revise a saída do seu PLAN antes de executar DEPLOY.

Cada DCM project pode ter apenas uma instância implantada por vez. Vários perfis de configuração não podem coexistir. Implantar a configuração B com o mesmo DCM project descartará quaisquer objetos de outras configurações anteriores que não estejam definidos na B.

Crie um DCM project para cada ambiente de destino. O DCM project para cada ambiente pode então apontar para os mesmos arquivos de definição, mas serem implantados independentemente com valores diferentes para cada variável, como suffix => 'DEV_JS', para que possam existir de maneira independente lado a lado na mesma conta Snowflake.

Será possível substituir valores para variáveis ​ selecionadas em tempo de execução se você quiser usar um perfil predefinido com uma pequena variação.

Por exemplo:

EXECUTE DCM PROJECT DCM_DEMO.PROJECTS.DCM_PROJECT_DEV
  DEPLOY
  USING CONFIGURATION DEV (suffix=>'DEV_USER', user=>'JANEDOE')
FROM
  'snow://workspace/USER$.PUBLIC.DEFAULT$/versions/live/DCM_Project_Quickstart_1';

snow dcm deploy DCM_PROJECT_DEV --configuration DEV --variable "suffix='DEV_USER'" --variable "user='JANEDOE'"

Cada tentativa de implantação (bem-sucedida, com falha ou cancelada) tem um número de implantação, por exemplo, DEPLOYMENT$1. Como opção, você pode especificar uma cadeia de caracteres exclusiva como um alias de implantação a fim de nomear implantações individuais para melhor observabilidade no histórico de implantações. Pense no alias de implantação como uma mensagem de commit para sua alteração de código.

Cada comando DEPLOY primeiro executa um PRE-PLAN interno como parte da implantação. Se o PRE-PLAN for bem-sucedido, o DEPLOY é executado imediatamente em seguida. Não há opção para interceptar ou revisar essa etapa do plano interno. O PRE-PLAN é executado para reduzir ainda mais o risco de falha durante a implantação. Se um DEPLOY falhar, você poderá ver na mensagem de erro se a falha ocorreu durante a etapa PRE-PLAN ou DEPLOY. A falha durante a etapa PRE-PLAN é semelhante a PLAN: nenhuma alteração DDL é executada.

Importante

A falha durante a etapa DEPLOY pode resultar na execução parcial das alterações definidas. Isso pode fazer com que alguns dos objetos gerenciados fiquem em um estado indefinido. Na maioria dos casos, corrigir a causa raiz e executar DEPLOY novamente restaura o estado de destino definido.

Não é possível personalizar o caminho de destino para o arquivo de saída DEPLOY. Os artefatos de implantação são sempre armazenados dentro do DCM project.

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';

Um exemplo de comando SQL para implantar um DCM project usando Jinja com perfis de configuração, mas substituindo wh_size e teams, é:

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';

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

Gerenciar um DCM project

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.

Nota

O resultado não corresponde necessariamente aos objetos da implantação mais recente. Objetos que foram descartados ou desvinculados manualmente do projeto não são listados no resultado.

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».

Importante

Descartar ou substituir um objeto de DCM project faz com que você perca todos os artefatos do histórico de implantação que o objeto contém.

DROP DCM PROJECT [IF EXISTS] <my_project>;

Automatizar uma implantação de DCM 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.

Ações do GitHub

O repositório DCM snowflake-labs fornece um conjunto do GitHub Actions composto reutilizável ​​que automatiza pipelines de DCM Projects. Cada ação trata de uma etapa do ciclo de vida, e você pode referenciá-las em seus próprios fluxos de trabalho para criar pipelines CI/CD de ponta a ponta. Apenas a sintaxe do fluxo de trabalho difere entre as plataformas; os mesmos conceitos de CI/CD se aplicam ao Azure DevOps, GitLab CI/CD, Bitbucket Pipelines e outros.

Nota

O GitHub Actions no repositório DCM snowflake-labs é fornecido “como está” para fins de avaliação. Ele não é oficialmente compatível com o Snowflake. Use por sua conta e risco.

As seguintes ações reutilizáveis ​​estão disponíveis:

Ação

Descrição

dcm-parse-manifest

Analisa o manifest.yml e gera nomes de destino como uma matriz JSON para estratégias de matriz.

dcm-connection-test

Testa a conectividade do Snowflake, valida se a função de conexão corresponde ao manifesto project_owner e verifica se o objeto de DCM project já existe.

dcm-plan

Executa snow dcm plan, resume o conjunto de alterações (contagens CREATE, ALTER e DROP por domínio de objeto) e carrega os artefatos do plano. Opcionalmente, publica o resumo do plano como um comentário na solicitação de pull associada.

dcm-deploy

Implanta o DCM project com detecção opcional de descarte de dados, atualização da tabela dinâmica, teste de expectativa e scripts SQL pós-implantação. Opcionalmente, publica um resumo de implantação na solicitação de pull.

Para usar uma ação em seu fluxo de trabalho, faça referência a ela com:

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

Para obter a documentação completa das entradas e saídas de cada ação, consulte as ações README.

Pré-requisitos

Antes de usar o GitHub Actions reutilizável, conclua as seguintes etapas de configuração:

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

  • Crie um ambiente GitHub para cada destino do manifesto (por exemplo, DCM_STAGE, DCM_PROD_US). O nome do ambiente deve corresponder ao nome do destino em seu manifest.yml.

  • Defina as variáveis ​​``SNOWFLAKE_USER`` e DCM_PROJECT_PATH no bloco env do fluxo de trabalho ou como variáveis ​​do repositório GitHub.

  • Conceda ao fluxo de trabalho as permissões necessárias:

    permissions:
  id-token: write       # Required for OIDC authentication
  contents: read
  pull-requests: write  # Required only when using comment-on-pr
Autenticação

Todas as ações autenticam usando o GitHub Action da Snowflake CLI. OIDC (OpenID Connect) é a abordagem recomendada porque usa os tokens de identidade integrados do GitHub, de modo que nenhuma senha ou chave privada precisa ser armazenada como segredo.

Para configurar a autenticação OIDC, crie um usuário de serviço do Snowflake com uma identidade de carga de trabalho que confie no provedor OIDC do GitHub:

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>'
  );

Substitua <owner>/<repo> pelo seu repositório GitHub e <env_name> pelo nome do ambiente GitHub (por exemplo, DCM_STAGE). Se você tiver vários ambientes, crie um usuário de serviço separado para cada um deles ou use a personalização de declaração de assunto. Em seguida, conceda ao usuário de serviço a função especificada como project_owner em seu manifesto.

Se não for possível usar OIDC, as ações também são compatíveis com autenticação por senha, PAT e par de chaves. Consulte a seção de autenticação de README das ações para obter instruções de configuração.

Fluxos de trabalho de amostra

O diretório GitHub_workflows no repositório DCM snowflake-labs contém arquivos de fluxo de trabalho prontos para uso que compõem as ações reutilizáveis ​​em pipelines CI/CD completos. Você pode copiá-los para o diretório .github/workflows/ do seu repositório e personalizá-los para o seu projeto. Para obter instruções completas de configuração, consulte o README dos fluxos de trabalho de amostra.

Todos os fluxos de trabalho de amostra leem a função account_identifier e project_owner do Snowflake diretamente dos destinos do manifesto, 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.

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

  • Configuração orientada por manifesto: cada fluxo de trabalho lê account_identifier, project_owner e project_name dos destinos do manifesto, mantendo a configuração do ambiente em um único local.

  • Proteção contra descarte de dados: o fluxo de trabalho de implantação detecta operações DROP destrutivas em objetos que contêm dados (bancos de dados, esquemas, tabelas e áreas de preparação) e bloqueia a implantação caso alguma seja encontrada.

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

  • Comentários da solicitação de pull: os resumos do planejamento e da implantação são publicados como comentários na solicitação de pull original.

Amostra de fluxo de trabalho: Testar conexões

Este fluxo de trabalho valida se o usuário do serviço GitHub Actions pode se conectar a todos os ambientes de destino definidos no manifesto. Use-o ao configurar um novo repositório, integrar uma nova conta ou depurar problemas de autenticação. O fluxo de trabalho executa as seguintes etapas:

  • Analisa todos os nomes de destino de manifest.yml dinamicamente.

  • Usa uma estratégia de matriz do GitHub Actions para testar cada destino em paralelo.

  • Para cada destino, verifica a conexão com o Snowflake, relata a conta, o usuário e a função conectados e verifica se a função conectada corresponde ao proprietário do DCM project.

  • Relata se o objeto de DCM project já existe e se o usuário do serviço tem privilégios de implantação.

Amostra de fluxo de trabalho: Testar PR para o principal

  • Arquivo de configuração do fluxo de trabalho: DCM_2_Test_PR_to_main.yml

  • Acionador: solicitação de pull aberta, sincronizada ou reaberta na ramificação main

Este fluxo de trabalho executa um PLAN no destino de produção como um teste de integração para cada solicitação de pull. Ele fornece aos revisores um resumo das alterações planejadas diretamente na solicitação de pull. O fluxo de trabalho executa as seguintes etapas:

  • Executa snow dcm plan no destino PROD.

  • Analisa plan_result.json para resumir as operações CREATE, ALTER e DROP agrupadas por domínio de objeto.

  • Carrega artefatos do plano para inspeção posterior.

  • Publica o resumo do plano como um comentário na solicitação de pull.

  • Falha na verificação se PLAN falha, bloqueando a mesclagem.

Amostra de fluxo de trabalho: Implantar em produção

  • Arquivo de configuração do fluxo de trabalho: DCM_3_Deploy_to_Prod.yml

  • Acionador: envie para a ramificação main (normalmente uma solicitação pull mesclada)

Este fluxo de trabalho planeja e implanta em um único destino de produção. Use-o quando você não precisar de um ambiente de preparação ou quando a preparação for feita separadamente. O fluxo de trabalho executa as seguintes etapas:

  1. Plano: executa snow dcm plan e resume o conjunto de alterações.

  2. Detecção de descarte de dados: bloqueia o pipeline se o plano contém operações DROP para bancos de dados, esquemas, tabelas ou áreas de preparação.

  3. Implantar: executa snow dcm deploy.

  4. Pós-scripts (opcional): executa scripts post-hook SQL com injeção de variáveis ​​Jinja.

  5. Atualizar tabelas dinâmicas (opcional): executa snow dcm refresh para aplicar qualquer nova lógica de transformação.

  6. Testar expectativas (opcional): executa snow dcm test para validar as expectativas de qualidade de dados.

Após a implantação, o fluxo de trabalho publica opcionalmente um resumo do status para a solicitação de pull original.

Amostra de fluxo de trabalho: Implantar na área de preparação e depois na produção

Esse fluxo de trabalho implanta um pipeline de promoção sequencial. As alterações são primeiro implantadas em preparação, validadas de ponta a ponta e somente então promovidas para produção. Se alguma etapa falhar, o pipeline será interrompido e a produção não será afetada.

A sequência de implantação para cada destino (STAGE, depois PROD) inclui:

  1. Plano: executa snow dcm plan e resume o conjunto de alterações.

  2. Detecção de descarte de dados: bloqueia o pipeline se o plano contém operações DROP para bancos de dados, esquemas, tabelas ou áreas de preparação.

  3. Implantar: executa snow dcm deploy.

  4. Pós-scripts (opcional): executa scripts post-hook SQL com injeção de variáveis ​​Jinja.

  5. Atualizar tabelas dinâmicas (opcional): executa snow dcm refresh para aplicar qualquer nova lógica de transformação.

  6. Testar expectativas (opcional): executa snow dcm test para validar as expectativas de qualidade de dados.

A implantação em produção começa somente após a aprovação de todas as etapas de preparação. Após a conclusão de todos os trabalhos, o fluxo de trabalho opcionalmente publica um resumo do status final na solicitação de pull original.

Perguntas frequentes (FAQ)

Como renomear um objeto existente?

  1. Execute um comando ALTER fora do projeto DCM.

  2. Altere a definição.

  3. Execute PLAN para verificar se a nova definição corresponde ao novo estado (sem alterações em PLAN).

  4. Execute DEPLOY para salvar o novo estado.

Como implantar objetos que ainda não são compatíveis com instruções DEFINE?

Você pode executar instruções CREATE IF NOT EXISTS ou CREATE OR REPLACE em um script SQL separado após executar a implantação ou o plano do seu projeto DCM.

Ambas as opções são compatíveis com o uso de modelos Jinja2 e a execução simulada (a execução simulada renderiza o modelo Jinja, mas não verifica a compilação bem-sucedida de SQL).

Por exemplo:

EXECUTE DCM PROJECT my_project
  PLAN ...
USING ...
FROM ...

EXECUTE IMMEDIATE
FROM
  'snow://workspace/USER$.PUBLIC.DEFAULT$/versions/head/DCM_Project_Quickstart_1/hooks/post_hook.sql'
  USING (db => 'DEV')
  dry_run = TRUE      -- shows the rendered Jinja but does not verify successful compilation
;