Boas práticas para programadores em Databricks

Esta página apresenta as melhores práticas para o seu ciclo de vida de engenharia de dados e desenvolvimento, incluindo controlo de versões, gestão de ambientes, ferramentas para programadores e implementações geridas.

Controlo de origem

Controlo de versões de todos os ficheiros

A automação declarativa baseia-se na ideia de que, se algo não estiver no controlo de versões, não existe. Por isso, a Databricks recomenda que controle a versão de quase todos os ficheiros, incluindo:

• Todos os cadernos e ficheiros fonte (.py, .sql)
• Agrupar ficheiros de configuração (databricks.yml e overrides YAML específicos do ambiente)

No entanto, não se comprometa:

• Constrói artefactos, como .jar ficheiros OU .whl . Em vez disso, carregue binários compilados para volumes do Unity Catalog durante o processo de CI. Consulte carregar JAR.
• Tokens ou credenciais. Use a gestão de segredos ao nível do espaço de trabalho, apoiada por um gestor de segredos na cloud (como AWS Secrets Manager ou Azure Key Vault) e sincronize os valores nos escopos secretos do Databricks. Consulte Gestão secreta.
• Exemplos de dados locais e ficheiros com PII. Use .gitignore para os excluir.

Repositório único

A Databricks recomenda que utilize um único repositório para todo o seu código (código-fonte e ficheiros de configuração), pois facilita a colaboração, o código e a partilha de boas práticas tanto para humanos como para IA. Se tiveres vários pacotes para ciclos de implementação separados, mantém-nos num único repositório.

A única exceção à recomendação do repositório único encontra-se em indústrias reguladas onde múltiplos repositórios são necessários para fins de confidencialidade.

Estratégia de ramificação baseada em troncos

Para minimizar conflitos de fusão e garantir que a branch principal está sempre em condições de implementação, utilize uma estratégia de ramificação baseada no ramo principal.

Um fluxo de trabalho simples seria:

1. Desenvolve localmente ou no espaço de trabalho e implementa num espaço de trabalho de desenvolvimento Databricks para testar alterações.
2. Crie uma ramificação de funcionalidades de curta duração para atualizações de controlo de versões e sincronize regularmente as alterações locais ou do seu espaço de trabalho.
3. Quando os testes terminarem, funde o ramo de funcionalidades no ramo principal.
4. O CI/CD implementa automaticamente o branch principal num ambiente de staging e ativa testes automatizados.
5. Quando os testes e verificações na fase de staging são concluídos com sucesso, o CI/CD implanta a branch principal num ambiente de produção.

Estes passos estão descritos no diagrama seguinte:

Configuração da área de trabalho

Ambientes de trabalho isolados

Isole os ambientes de trabalho para minimizar o impacto de uma implementação falhada. Por exemplo:

• Equipas pequenas (até 5 engenheiros de dados): Comecem com dois espaços de trabalho (desenvolvimento e produção) numa única conta cloud.
• Equipas em crescimento (5+ engenheiros de dados): Mudança para três áreas de trabalho (desenvolvimento, staging e produção). O ambiente de staging deve ser funcionalmente representativo da produção — com a mesma configuração de build, o mesmo esquema e as mesmas integrações críticas — ainda que esteja numa escala inferior.
• Indústrias reguladas (banca, saúde, defesa): Isolar fisicamente os espaços de trabalho e contas na cloud para evitar fugas de dados. Gerir o isolamento através dos limites do IAM e do Unity Catalog dentro de uma única conta é possível, mas proporciona uma postura de segurança menos robusta.

Para espaços de trabalho de produção, utilize computação serverless com políticas de rede sempre que possível. Caso contrário, configure as contas na cloud para usarem sub-redes privadas ou VNets com controlos rigorosos de saída e segurança de rede.

Para mais informações, consulte Políticas de rede baseadas em contexto.

Isolamento de armazenamento de dados

• Use uma única metastore do Unity Catalog e crie catálogos separados para desenvolvimento, staging (se aplicável) e produção, espelhando o layout do seu espaço de trabalho.
• Utilize esquemas pessoais para programadores individuais em catálogos de desenvolvimento e de pré-produção.
• Vincule o catálogo de produção no modo ISOLATED apenas ao espaço de trabalho de produção. Definir o modo de isolamento de um catálogo para ISOLATED garante que os dados de produção não estão acessíveis a partir de ambientes de desenvolvimento ou de teste, mesmo que uma identidade esteja mal configurada.
• Reserve metastores, contas ou regiões separadas apenas para organizações com requisitos regulatórios, de soberania de dados ou multi-regionais que o isolamento ao nível do catálogo não consiga satisfizer.

Trate metadados de tabelas e colunas como código

Trate os comentários de tabelas e colunas como parte do seu código. Guarde-as em .sql ficheiros juntamente com as definições dos Pacotes de Automação Declarativa e implemente-as através de um trabalho de metadados para que definições precisas e direcionadas para o negócio estejam sempre disponíveis. Escreva comentários que descrevam o que uma linha representa, as unidades e os valores válidos em linguagem simples, em vez de repetir o nome da coluna.

Configurar esquemas pessoais

Durante o desenvolvimento, configure bundles para usarem um esquema pessoal por utilizador, por exemplo dev_${user_name}. Isto impede que os programadores sobreescrevam as tabelas uns dos outros num espaço de trabalho partilhado.

Usar computação sem servidor

Use computação serverless para simplificar a gestão de clusters e otimizar custos. Consulte como se conectar à computação sem servidor.

Recomendações CI/CD

Pacotes de Automação Declarativa para CI/CD

Os Declarative Automation Bundles (anteriormente conhecidos como Databricks Asset Bundles) oferecem uma abordagem poderosa e unificada para gerir código, fluxos de trabalho e infraestrutura dentro do ecossistema Databricks e são recomendados para os seus pipelines CI/CD.

Para mais detalhes sobre o uso de bundles para fluxos de trabalho CI/CD, consulte fluxos de trabalho CI/CD em Databricks.

Para mais informações sobre Pacotes de Automação Declarativa, consulte O que são Pacotes de Automação Declarativa?.

Use o Terraform apenas para recursos externos

Use o Terraform para definir os seguintes recursos:

• Recursos ao nível da cloud e recursos externos
• Ações administrativas que utilizadores não privilegiados não devem realizar, como o provisionamento de espaços de trabalho ou a configuração de redes cloud

Use Pacotes de Automação Declarativa para todos os outros recursos do Databricks.

Gestão de pacotes

Criar pequenos pacotes

A Databricks recomenda o desenvolvimento de bundles pequenos e específicos em vez de um único bundle grande.

• Juntar tudo o que uma equipa possui num único pacote.
• Testar e implementar no mesmo pipeline CI/CD que partilha o mesmo ciclo de vida e a mesma cadência de lançamento.
• Cada bundle deve abranger todos os ambientes de um determinado projeto (dev, staging, produção) em vez de usar bundles separados por ambiente.

Criar pacotes separados para:

• Produtos ou domínios diferentes, por exemplo "Análise de faturação" e "Deteção de fraude"
• Diferentes limites de propriedade ou permissões
• Cargas de trabalho com ciclos de vida claramente diferentes
• Casos em que é necessária uma promoção ou reversão independente

Utilizar sync.paths para sincronizar pastas partilhadas

Ao gerir múltiplos bundles num único repositório, use sync.paths para sincronizar pastas partilhadas fora da raiz do bundle. Isto permite que diferentes projetos partilhem uma pasta comum de biblioteca, como ../common, mantendo identidades de implementação separadas.

Modelação de dependências inter-bundle em CI/CD

Quando o Bundle B depende de recursos publicados pelo Bundle A, represente essa dependência na camada de CI/CD ou de orquestração, em vez de agrupar os dois num único bundle.

• Torne o fluxo de trabalho de deploy-and-publish do Bundle A um pré-requisito explícito para o Bundle B. Configure o seu pipeline para que o Bundle B só comece depois de a implementação do Bundle A ser bem-sucedida e todas as verificações de validação necessárias passarem.
• Encaminha identificadores ou localizações de ativos publicados como entradas de pipeline, e falha rapidamente se faltarem ativos a montante. Isto garante que o Bundle B nunca seja implementado contra um estado parcialmente publicado.

Para mais informações sobre partilha de pacotes, consulte Partilha de pacotes e ficheiros de pacotes.

Modelos personalizados de pacotes

Use modelos personalizados de Declarative Automation Bundles como ponto de partida padrão para novos projetos, para que cada projeto herde os mesmos limites de proteção – permissões, etiquetagem, políticas de cluster, fiação CI/CD e bases de instância — sem que cada equipa tenha de resolver do zero.

Os templates devem codificar convenções partilhadas e duradouras, como governação, padrões de desempenho, layout do ambiente e limites de quotas. Evite lógica de negócio específica da aplicação, segredos ou configurações isoladas em templates.

Parametrize apenas entradas que se espera variem consoante a equipa, projeto ou ambiente:

• Nome do projeto ou da aplicação
• Definições do espaço de trabalho alvo
• Nomes de catálogos ou esquemas
• Identificadores principais de serviço
• Horários e definições de notificações

Manter as salvaguardas da plataforma e as predefinições partilhadas fixas no modelo, em vez de as parametrizar.

Para informações sobre modelos personalizados de bundles e como os criar, consulte modelos de projeto Declarative Automation Bundles.

Planeie reversões e correções urgentes

Mantém os pacotes suficientemente pequenos para poderes fazer um rollback direcionado num único bundle, em vez de coordenar um rollback entre várias cargas de trabalho não relacionadas.

Durante um incidente:

1. Reverter ou recuar o pacote afetado para a última versão estável conhecida.
2. Use um hotfix apenas para correções urgentes e de âmbito restrito que não podem esperar pelo fluxo normal de promoções.
3. Integre imediatamente qualquer hotfix novamente na rama principal após a validação, para que a linha principal continue a ser a única referência fidedigna.

Desenvolvimento geral

Usar princípios de serviço ou OIDC

Use os principais de serviço para toda a automação não relacionada com desenvolvimento, para desacoplar fluxos de trabalho automatizados das contas individuais de utilizador e garantir que os trabalhos continuam a correr quando os utilizadores internos saem. Consulte Entidades de serviço.

• Use princípios de serviço separados para implementação e tempo de execução. Um principal de serviço dedicado para implementações em bundles deve ter acesso mínimo aos dados. Cada tarefa de produção ou pipeline deve ter o seu próprio service principal utilizado na execução, com âmbito limitado apenas aos dados e recursos de que essa carga de trabalho necessita. Esta separação garante que as implementações em produção permanecem seguras quando se renovam ou restringem as permissões de acesso aos dados, e evita o acoplamento das alterações de infraestrutura ao acesso aos dados de produção.
• Setores regulados: Utilize a Workload Identity Federation (OIDC) para CI/CD. Isto elimina segredos duradouros no GitHub Actions ou no Azure DevOps. Consulte Habilitar federação de identidade de carga de trabalho em CI/CD.

Use as ferramentas de desenvolvimento do Databricks

Desenvolve na interface do workspace do Databricks usando pastas Git, ou num IDE local. Se usar Visual Studio Code ou um fork compatível, instale a extensão oficial Databricks para:

• Competências específicas dos agentes Databricks
• Catálogo Unity e acesso ao sistema de ficheiros
• Capacidades de desenvolvimento remoto para executar cargas de trabalho em recursos de computação do Databricks

Para mais informações, consulte a extensão Databricks para Visual Studio Code.

Minimizar lógica de negócio em cadernos

Não trate os cadernos como o principal recipiente da lógica de negócio. Usa-os apenas para exploração e visualização.

• Python: Coloque a lógica central em módulos importáveis .py em src/ ou src/py/, e chame essas funções a partir dos cadernos.
• SQL: Mantenha as consultas em ficheiros .sql em src/ ou src/sql/, e faça referência a esses ficheiros a partir de tarefas e pipelines, em vez de incorporar SQL diretamente em notebooks.

Use os cadernos apenas como camadas finas de orquestração e visualização que chamam o código subjacente. Esta abordagem facilita o teste e a reutilização.

Ao migrar um projeto com muitos cadernos, faça-o de forma incremental. Extrair um módulo reutilizável ou ficheiro SQL de cada vez e usar Declarative Automation Bundles para trazer os ativos migrados sob o mesmo fluxo de trabalho de implementação e testes que o resto do projeto.

Transmita o contexto dinamicamente

Evite variáveis estáticas para dependências de tarefas. Use referências de valores dinâmicos, como {{tasks.<task_key>.values.<value_key>}} para passar contexto de execução entre tarefas num trabalho de múltiplas etapas.

Testes e observabilidade

Implementar camadas de teste

Use três camadas de teste que correspondam à forma como os seus pacotes avançam para a produção:

1. Testes unitários: Mantém a lógica de negócio em módulos importáveis src/ e cobre-os com pytest ou um framework equivalente. Executa-os em cada pull request para que falhas bloqueem fusões.
2. Validação do pacote: Executar bundle validate localmente. Em CI, prefira bundle deploy a um espaço de trabalho de não produção para detetar problemas de YAML e de mapeamento de recursos antes das implementações em produção.
3. Testes de integração no staging: Após a implementação no staging, execute trabalhos de ponta a ponta com verificações de conclusão e asserções críticas de qualidade dos dados, como expectativas de contagem de linhas ou esquemas.

Considere "todos os testes passam com êxito na ramificação principal e no ambiente de staging" como o critério para promover artefactos para produção.

Para os Pipelines Declarativos Lakeflow Spark, utilize as funcionalidades de desenvolvimento e validação incorporadas em vez de execuções ad-hoc em notebooks. Testar a lógica do pipeline contra conjuntos de dados pequenos e representativos que incluem registos com erros, e usar o modo de desenvolvimento para validar alterações antes de atualizar as tabelas de produção.

Tratar o registo como parte da implementação

Para cargas de trabalho implementadas em Pacotes de Automação Declarativa, trate métricas e registos como parte do contrato de implementação, em vez de algo que cada projeto defina de forma independente.

• Emita registos estruturados de forma consistente entre tarefas, pipelines e tarefas. Inclua o nome do pacote, ambiente alvo, nome da carga de trabalho, identificador de execução e qualquer identificador de negócio necessário para rastrear falhas.
• Acompanhe um conjunto padrão de métricas operacionais para cada carga de trabalho de produção: estado de execução, duração, número de tentativas e indicadores de throughput ou novidade, quando relevantes.
• Codifique estas convenções em bibliotecas partilhadas, definições de cargas de trabalho reutilizáveis ou agrupe templates para que as equipas não tenham de recriar padrões de observabilidade para cada projeto.