Pipeline dbt + Databricks – Guia Geral

Repositório de treinamento dabdbt, utilizado pela equipe de dados da Rescue Point para demonstrar um fluxo completo de dbt empacotado via Databricks Asset Bundles e publicado em static websites na Azure. Este README cobre visão geral, automação e operação dos ambientes. A documentação específica do projeto dbt está em dabdbt/README.md.

---

Visão geral

• Fontes: Azure SQL (sqlolistdev) exposto no Unity Catalog via catálogo federado sqlpoclf.
• Camadas (catálogos rescue_<target>):
  • Bronze (.b): seed ibge_municipios com referência IBGE.
  • Silver (.s): customers_s, orders_s, order_items_s, order_payments_s com enriquecimento e tags UC.
  • Gold (.g): visões analíticas *_g para clientes, fulfillment, vendas, pagamentos, heatmap e cesta de produtos.
• Publicação: artefatos dbt docs e portal.html publicados no static website do storage ($web). URLs atuais: https://docsdev.rescuepoint.com.br/ (dev) e domínio de produção em preparação.
• Orquestração: job dabdbt_job com tasks dbt_seed → dbt_silver → dbt_gold → dbt_docs. A publicação no storage é feita por GitHub Actions (veja abaixo).

Estrutura resumida do repositório:

.
├── README.md                  # Este guia geral
├── requirements.txt           # Dependências para setup local
├── portal.html                # Portal estático publicado no storage
└── dabdbt/                    # Projeto dbt + bundle
    ├── README.md              # Documentação detalhada do projeto dbt
    ├── databricks.yml         # Targets, variáveis e metadados do bundle
    ├── dbt_project.yml        # Configuração dbt (camadas, flags, persist_docs)
    ├── dbt_profiles/          # Perfis dev/prd (catálogos, http_path, tokens)
    ├── resources/             # Job + specs de cluster/warehouse
    ├── src/                   # Modelos, seeds, macros e docs
    └── notebooks/             # Notebook de publicação (ainda disponível para referência)

---

Automação (GitHub Actions)

A pipeline foi segmentada por branch:

Workflow	Branch	Ambientes e segredos	Ações principais
.github/workflows/deploy-dev.yml	dev	Environment dev com AZURE_CREDENTIALS, AZURE_SUBSCRIPTION_ID, DATABRICKS_* e variáveis (AZURE_STORAGE_ACCOUNT, etc.)	Deploy do bundle em dev, execução do job dabdbt_job e correção do header MIME do blob dabdbt/index.html no storage sarescuedev via az storage blob update --auth-mode login
.github/workflows/deploy-prd.yml	main	Environment prd com AZURE_CREDENTIALS_PRD, AZURE_SUBSCRIPTION_ID, DATABRICKS_* (para o workspace prd) e variáveis iguais às de dev, porém apontando para sarescueprd	Deploy do bundle em prd, execução do job com warehouse de produção e atualização do blob no static website

Service principals

• dev: ghactions-dabdbt (já configurado). Secrets reunidos em AZURE_CREDENTIALS.
• prd: ghactions-dabdbt-prd (criado via CLI). Secret AZURE_CREDENTIALS_PRD armazena o JSON com clientId, clientSecret, subscriptionId (eef39a8e-5a31-408a-87e8-a8b61faae822) e tenantId.

Para cadastrar/atualizar: gh secret set AZURE_CREDENTIALS[_PRD] --env <dev|prd> --repo AnselmoBorges/pocdabdbt --body '<json>'.

Ajustes recentes

• az storage blob update agora usa --auth-mode login e az account set para evitar busca de account key.
• Deploy de produção usa o warehouse 7a2b912f6c29d8a8 via variável sql_warehouse_id; dev permanece com f38fa7279458bb21.
• Bundle de produção grava em /Workspace/Shared/srv_eng_prd/.bundle/${bundle.name}/${bundle.target}, eliminando erros de ACL e alinhando com o usuário responsável (srv_eng_prd).

---

Operação por ambiente

Desenvolvimento (dev)

• Workspace: https://adb-1293581597272291.11.azuredatabricks.net.
• Catálogo default nos perfis: rescue_dev.
• Warehouse: f38fa7279458bb21 (serverless).
• Storage: sarescuedev, container $web.
• Execução local: databricks bundle deploy --target dev --profile dev seguido de databricks bundle run dabdbt_job --target dev --profile dev.

Produção (prd)

• Workspace: https://adb-2533506717590470.10.azuredatabricks.net.
• Catálogo: rescue_prd (configurável via DBT_PROD_CATALOG).
• Warehouse: 7a2b912f6c29d8a8 (variável sql_warehouse_id).
• Root path: /Workspace/Shared/srv_eng_prd/.bundle/dabdbt/prd (variável prod_root_path).
• Storage: sarescueprd, container $web (segredo AZURE_CREDENTIALS_PRD com role Storage Blob Data Contributor).
• Após merge em main, acione manualmente Deploy dabdbt (prd) via Actions → Run workflow se precisar evitar deploy automático.

Parâmetros importantes

• databricks.yml controla targets, root path, variáveis (source_olist_env, sql_warehouse_id).
• dbt_project.yml habilita populate_by_name (substitui allow_population_by_field_name) e use_materialization_v2.
• dbt_profiles/profiles.yml contém overrides de http_path, catalog, schema, host, token por ambiente.

---

Setup local rápido

python -m venv ~/.venvs/dabdbt
source ~/.venvs/dabdbt/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt

curl -fsSL https://raw.githubusercontent.com/databricks/setup-cli/main/install.sh | bash

export DBT_PROFILES_DIR="$(pwd)/dabdbt/dbt_profiles"
export DBT_HOST="https://adb-1293581597272291.11.azuredatabricks.net"
export DBT_ACCESS_TOKEN="dapi<token_dev>"
export DBT_DEV_HTTP_PATH="/sql/1.0/warehouses/f38fa7279458bb21"

cd dabdbt
dbt deps
dbt seed --select ibge_municipios --target dev
dbt run  --select tag:silver --target dev
dbt run  --select tag:gold   --target dev
dbt docs generate --target dev

Publicação manual (hotfix)

az storage blob upload \
  --account-name sarescuedev \
  --container-name '$web' \
  --name portal.html \
  --file portal.html \
  --overwrite


  --account-name sarescuedev \
  --container-name '$web' \
  --name dabdbt/index.html \
  --content-type 'text/html; charset=utf-8' \
  --content-disposition inline \
  --auth-mode login

---

Troubleshooting

Sintoma	Causa provável	Como corrigir
SQL warehouse ... does not exist no deploy	Variável sql_warehouse_id não configurada para o target	Ajuste databricks.yml ou DBT_*_HTTP_PATH conforme ambiente
Deploy falha com ACLs for directory are disabled	Root path fora de /Workspace/Users/... em workspace sem ACL	Use /Workspace/Shared/... (como configurado) ou habilite ACLs
HTML baixa em vez de abrir	contentType incorreto no blob	Reexecute workflow ou az storage blob update --content-type 'text/html; charset=utf-8'
Pipeline dev/prod não autentica no Azure	Secret AZURE_CREDENTIALS[_PRD] ausente ou inválido	Recrie com JSON do service principal e confira permissões Storage Blob Data Contributor
dbt acusa flag deprectada allow_population_by_field_name	Flag removida no dbt 1.8+	Já mitigado com populate_by_name: true (não remover)

---

Próximos passos sugeridos

• Adicionar dbt test e testes personalizados para validar os modelos gold.
• Versionar e publicar dashboards conectados às tabelas rescue_<target>.g.
• Expandir monitoramento das Actions com notificações (Slack/email) em falhas.
• Avaliar uso de Unity Catalog grants via bundle (grants.yml) para automatizar permissões após o deploy.

Para detalhes das transformações e componentes dbt, consulte dabdbt/README.md e a documentação gerada em src/docs.```*** End Patch

1. O portal exibido em https://docsdev.rescuepoint.com.br/ está em portal.html na raiz do repositório.