Integração Git do Snowflake: um mergulho profundo

A integração Git do Snowflake permite conectar nativamente sua conta Snowflake a uma das plataformas Git suportadas (GitHub, GitLab etc.) e sincronizar o conteúdo de um repositório remoto com sua conta. Para essa sincronização, o Snowflake usa um tipo especial de stage chamado repository stage. Esse repository stage é sincronizado com o repositório Git remoto e se torna um repositório local com um clone completo do remoto, incluindo tudo o que você espera — branches, commits etc.

Com essa sincronização, você tem um clone completo do repositório disponível direto na sua conta Snowflake. Dá para usar os arquivos baixados nas suas aplicações Snowflake ou escrever UDFs/stored procedures cujo código do handler fica armazenado em um repositório Git remoto e sincronizado com o repository stage. Assim fica simples manter tudo sob controle de versão e atualizar o stage sempre que o repositório mudar.

Você também pode usar qualquer arquivo de qualquer branch ou commit diretamente no Snowflake.

Graças a essa integração, fica mais simples cuidar do ciclo de desenvolvimento do seu código quando você quer mantê-lo sob controle de versão. Vamos pegar como exemplo o código do handler de uma stored procedure. Antes dessa integração, você tinha que cuidar do controle de versão por conta própria e fora do Snowflake. Escrevia e testava o código do handler no VS Code. Quando terminava, precisava dar commit das alterações em um repositório remoto para manter o histórico. Ao mesmo tempo, também tinha que fazer o deploy do código no Snowflake e criar uma stored procedure usando aquele código como handler.

Isso significava fazer upload manual do código para um stage do Snowflake e então criar a stored procedure, ou usar o Snowflake CLI para cuidar tanto do upload quanto da criação da stored procedure. De qualquer jeito, era uma etapa a mais, sem ligação direta com o seu código versionado. Se precisasse alterar o código, era passar por todo o processo de novo — desenvolver, dar commit no repositório e atualizar o arquivo do handler no Snowflake.

Vamos ver como a integração nativa com o Git deixa esse processo muito mais ágil. Como dá para referenciar o código do handler direto no repository stage, sempre que você fizer commit das alterações e sincronizar o stage, o handler da stored procedure é atualizado automaticamente e segue versionado. Acabaram os processos isolados (controle de versão e atualizações da SP) — agora é um único fluxo enxuto.

A integração Git do Snowflake permite conectar repositórios das seguintes plataformas suportadas:

• GitHub
• GitLab
• BitBucket
• Azure DevOps
• AWS CodeCommit

Neste exemplo, vamos escrever um handler simples de stored procedure Hello World em Python, dar commit das alterações em um repositório remoto no GitHub e trazê-lo para o Snowflake por meio da integração Git. Depois, vamos alterar o código do handler e ver como é fácil atualizar o código no Snowflake graças à integração Git. Primeiro, dê uma olhada no diagrama abaixo, que ilustra o que vamos construir:

1. Primeiro, desenvolvemos o código do handler localmente no VS Code e damos commit em um repositório do GitHub.
2. Em seguida, criamos um repository stage no Snowflake apontando para o repositório remoto. Também precisamos criar um novo secret para guardar as credenciais da conta Git.
3. Com o repository stage pronto no Snowflake, sincronizamos com o repositório remoto para trazer o código para dentro do Snowflake.
4. Por fim, criamos uma stored procedure no Snowflake e importamos o código do handler a partir do nosso repository stage.

Vamos detalhar cada etapa.

1. Desenvolvimento do código do handler

Criei uma função simples de handler chamada hello_world e dei push para o meu repositório. Agora podemos seguir com a criação dos objetos necessários no Snowflake e ligar esse repositório remoto a um novo repository stage no Snowflake.

2. Criação do secret

Vamos começar pelo secret. Eu uso um personal access token para autenticação.

3. Criação da API Integration

Também precisamos de uma nova API integration para conectar o Snowflake ao GitHub. O parâmetro API_ALLOWED_PREFIXES aponta para a URL da minha conta no GitHub e, para autenticação, usamos o secret criado na etapa anterior.

4. Criação do repository stage

Por fim, podemos criar um repository stage Git e passar os valores criados antes. A origem é o repositório Git ao qual queremos nos conectar.

5. Sincronizar o repository stage com o remoto

O repository stage já está pronto; vamos sincronizá-lo com o repositório remoto.

6. Criação da stored procedure

E pronto! Agora temos uma integração funcionando entre o Snowflake e o repositório Git remoto. O handler da nossa stored procedure vem do repository stage, que está sincronizado com o repositório remoto. Vamos criar a stored procedure:

7. Sincronização com o repositório remoto

Como podemos executá-la?

Agora vamos alterar o código para ver como é fácil trazer atualizações para o Snowflake. De novo, faremos as mudanças localmente no VS Code e damos commit no repositório remoto. Vamos fazer uma alteração simples para deixar a mensagem em maiúsculas.

Depois que as alterações entrarem no repositório, precisamos atualizar (sincronizar) o repository stage no Snowflake.

1ALTER GIT REPOSITORY snowflake_git_demo FETCH;

Pronto, o código atualizado do handler já está disponível no Snowflake! É só isso — nada mais é preciso. Não é necessário recriar a procedure nem nada parecido. Basta executar a stored procedure para confirmar que o código foi atualizado:

8. Atualização automática a cada novo merge

Dá para automatizar isso. Imagine que você siga um fluxo padrão com Git, mantendo as alterações em feature branches separadas que precisam ser mescladas na branch principal. Podemos montar um workflow no GitHub Actions que executa o comando ALTER GIT REPOSITORY quando o PR é mesclado, fazendo com que o repository stage seja atualizado automaticamente toda vez que novo código entrar na branch principal!

Veja um exemplo simples. Você pode usar o SnowSQL ou o SnowCLI para executar a instrução SQL.

TORY command when the PR is merged, so the repository stage is automatically updated every time you push new code into your main branch!

Here is a simple example. You can use either SnowSQL or SnowCLI to run the SQL statement.

name: Deploying Stored procedure updates
env:
  SNOWSQL_ACCOUNT: ${{secrets.SF_ACCOUNT}}
  SNOWSQL_USER: ${{secrets.SF_USER}}
  SNOWSQL_PWD: ${{secrets.SF_PASSWORD}}
  SNOWSQL_DATABASE: ${{ secrets.SF_DATABASE }}
  SNOWSQL_SCHEMA: ${{ secrets.SF_SCHEMA }}
  SNOWSQL_ROLE: ${{ secrets.SF_ROLE }}
  SNOWSQL_WAREHOUSE: ${{ secrets.SF_WAREHOUSE }}

on:

Expandir código

E aqui está a saída da execução do workflow no GitHub Actions:

Agora que vimos como configurar a integração Git, há outros recursos que vale a pena explorar:

Gerenciando repositórios no Snowflake

Nosso exemplo mostrou só duas operações relacionadas a repositórios Git no Snowflake: a criação do repository stage e o comando ALTER para buscar atualizações remotas. Veja outros exemplos do que dá para fazer com seus repositórios:

Listar branches do repositório

Podemos listar todas as branches do repository stage, junto com o caminho e o hash do commit.

1SHOW GIT BRANCHES IN snowflake_git_demo;

Listar arquivos do repositório

Assim como em qualquer stage interno ou externo, também dá para listar os arquivos do repository stage com o comando LIST:

1LS @snowflake_git_demo

Repository stage

No repository stage, ainda dá para listar arquivos por nome de branch:

1LS @snowflake_git_demo/branches/main

Hash de commit específico

1LS @snowflake_git_demo/commits/<<add_my_commit_hash>>

Listar arquivos por nome de tag

1LS @snowflake_git_demo/tags/tag_name

Conferir as propriedades do repository stage

Como acontece com vários outros objetos do Snowflake, também existem os comandos SHOW e DESCRIBE para repository stages, que mostram metadados úteis: onde o repository stage está localizado (nome do database e do schema), qual é a origem do repositório remoto, qual API integration é usada para conectar Git e Snowflake e qual é o nome do secret que guarda as credenciais para a conexão com o repositório Git remoto.

Executando código de um repositório

Manter arquivos em um repositório é útil, mas e quanto a executar o código guardado neles? Já pensou nisso? O Snowflake tem o comando EXECUTE IMMEDIATE FROM, que permite rodar código SQL direto a partir de arquivos. Você pode armazenar a configuração da sua conta (criação de usuários, roles, warehouses) em arquivos SQL no repositório e, graças a esse comando, rodá-los diretamente do arquivo:

EXECUTE IMMEDIATE FROM @snowflake_git_demo/branches/main/sql/users.sql

Copiar código do repositório para uma worksheet

Você também pode copiar código de arquivos do repository stage para suas worksheets. Dá para copiar conteúdo de arquivos .sql ou .py. Depois, é só editar ou executar esse código em worksheets do Snowsight. Basta navegar até o arquivo desejado e selecionar a opção Copy into worksheet.

Se quiser salvar suas alterações de volta no repositório, é preciso fazer isso na sua cópia local, porque, hoje, os repositórios são somente leitura no Snowflake — com exceção dos Notebooks, que também conseguem gravar de volta. Ou seja, só dá para usar Notebooks para escrever de volta nos repositórios. Outras limitações do recurso no momento desta publicação:

• Suporte somente leitura — veja acima
• Apenas acesso à internet pública. Não dá para acessar repositórios atrás de uma rede privada.
• O repository stage não pode ser compartilhado via data sharing.
• Não é possível criar um repository stage dentro de um application package.
• Não é possível criar um repository stage dentro de um native app no lado do cliente.
• O acesso a arquivos no repository stage pode ser mais lento do que o acesso a arquivos em um stage interno do Snowflake. Não use para casos de ingestão de dados.
• Submódulos ainda não são suportados.

O exemplo ponta a ponta mostrou um dos casos de uso possíveis para a integração Git no Snowflake: manter o código de procedures/UDFs sob controle de versão em um repositório remoto. Mas esse não é o único.

A integração Git também é fundamental para gerenciar sua conta com práticas de DevOps. Você pode manter as definições dos seus objetos Snowflake (databases, warehouses, usuários, roles etc.) em um repositório remoto como arquivos SQL com definições CREATE ou ALTER e executá-los como parte dos seus pipelines de CI/CD. Graças aos repository stages, você tem uma cópia dessas definições direto no Snowflake e pode rodar o código por lá, sem precisar de nenhum runner externo para fazer o deploy desses objetos!

Outro caso de uso pode envolver seus apps native/Streamlit, em que o código fica integrado nativamente a repositórios remotos. Por último, mas não menos importante, se você usa o Snowflake para transformações de dados — DAGs com tasks ou dynamic tables —, dá para manter as definições do pipeline sob controle de versão e integrá-las facilmente aos repository stages e ao ambiente Snowflake.

Tomáš Sobotík·Senior Data Engineer & Snowflake SME na Norlys

Tomas é um Snowflake Data SuperHero de longa data e referência geral em Snowflake. Sua ampla experiência no mundo dos dados passa de uma década, na qual atuou como data engineer, arquiteto e admin Snowflake em diversos projetos, setores e tecnologias. Tomas é um membro ativo da comunidade, compartilhando seu conhecimento e inspirando outros profissionais. Também é instrutor da O'Reilly, conduzindo treinamentos ao vivo online.