Instalação do DBT e dependências

Guia passo a passo para configurar o ambiente com DBT, Python e GitHub.

Este guia explica como instalar o DBT (Data Build Tool), além de configurar o ambiente com Python e GitHub.

✅ Pré-requisitos

• Acesso ao terminal (Linux, macOS ou Windows)
• Permissões de administrador

---

1. Instalar o Python

O Python é uma linguagem de programação muito utilizada em projetos de ciência de dados, automação e engenharia de dados. O DBT (Data Build Tool) é distribuído como um pacote Python, ou seja, usamos o Python como base para instalar, configurar e executar o DBT no nosso ambiente.

Recomendamos instalar a última versão do Python via pyenv no Linux/macOS ou diretamente do site oficial no Windows.

O DBT requer Python 3.9 ou superior.

macOS / Linux (com pyenv)

# Instalar pyenv (requer curl e git)
curl https://pyenv.run | bash

# Adicionar ao shell (bash/zsh)
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init --path)"' >> ~/.bashrc
source ~/.bashrc

# Instalar e usar uma versão do Python
pyenv install 3.12
pyenv global 3.12

Windows

Baixe o instalador oficial em: https://www.python.org/downloads/windows/

Durante a instalação:

• Marque a opção “Add python.exe to PATH”
• Clique em Customize installation e ative a opção “Install pip”
• Finalize a instalação e reinicie o terminal

Verifique:

python --version
pip --version

2. Instalar o Visual Studio Code

O Visual Studio Code (VS Code) é um editor de código leve e poderoso, muito utilizado em projetos com Python, DBT e Git.

Embora não seja obrigatório, recomendamos o uso do VS Code porque ele facilita:

• A navegação e edição dos arquivos .sql e .yml usados no DBT
• O controle de versão com Git através de uma interface gráfica simples
• A visualização de erros, highlights de sintaxe e integração com o terminal

Instalação

Baixe e instale o VS Code no site oficial:
👉 https://code.visualstudio.com/

Extensões recomendadas

Após instalar o VS Code, você pode adicionar algumas extensões úteis:

• Python (Microsoft) — para suporte ao ambiente virtual e sintaxe Python
• SQL (ou SQLTools) — para melhor experiência com arquivos .sql
• DBT Power User — extensão dedicada ao desenvolvimento com DBT

Essas ferramentas deixarão seu ambiente de trabalho mais produtivo e organizado.

3. Instalar o Git

O Git é um sistema de controle de versão distribuído. Ele é essencial para trabalharmos de forma colaborativa, mantendo o histórico de alterações e facilitando o versionamento dos nossos arquivos.

No nosso projeto, usaremos o Git para subir os modelos construídos com o DBT para o nosso repositório principal, que centraliza todos os modelos do nosso datalake. Isso garante rastreabilidade, colaboração e integração com os pipelines de dados.

macOS (via Homebrew)

brew install git

Linux (via apt)

sudo apt update
sudo apt install git

Windows

Baixe o instalador em: https://git-scm.com/download/win

Durante a instalação:

• Mantenha as opções padrão
• Marque o Visual Studio Code como editor padrão
• Ao final, reinicie o terminal

Verifique:

git --version

4. Criar e ativar um ambiente virtual Python

Ambientes virtuais Python são usados para isolar as dependências de um projeto. Isso significa que os pacotes que instalamos para o DBT não vão interferir em outros projetos nem conflitar com pacotes instalados globalmente no seu sistema.

Vamos criar um ambiente virtual chamado dbt-env, que usaremos exclusivamente para este projeto.

Linux/macOS

Criar o ambiente:

python -m venv dbt-env

Ativar o ambiente:

Sempre que você for trabalhar com DBT, lembre-se de ativar o ambiente virtual com o comando abaixo.

source dbt-env/bin/activate

Windows

Criar o ambiente:

python -m venv dbt-env

Ativar o ambiente:

Sempre que você for trabalhar com DBT, lembre-se de ativar o ambiente virtual com o comando abaixo.

dbt-env\Scripts\activate

Desativar o ambiente (qualquer sistema):

deactivate

5. Instalação do DBT

O DBT (Data Build Tool) é uma ferramenta que permite transformar dados dentro do seu data warehouse usando apenas SQL e alguns comandos em linha de comando.

Para funcionar com diferentes tecnologias de Data Warehouse (como BigQuery, Snowflake, Postgres, Redshift, etc), o DBT utiliza adaptadores. Adaptadores são pacotes que permitem que o DBT se conecte e interaja com cada tipo específico de banco de dados.

No nosso caso, usaremos apenas o BigQuery, pois é onde nosso data lake está hospedado.

Vamos instalar então o DBT com o adaptador do BigQuery:

python -m pip install dbt-core dbt-bigquery

Verifique a instalação:

dbt --version

Saída esperada (exemplo):

Core:
  - installed: 1.9.3
  - latest:    1.9.4

Plugins:
  - bigquery: 1.9.1

6. Configurando variáveis de ambiente e credenciais

Para conectar o DBT ao BigQuery, precisamos configurar credenciais de autenticação através de uma service account. Além disso, algumas variáveis de ambiente podem ser configuradas para personalizar o comportamento do DBT.

6.1 Solicitar Service Account

Antes de prosseguir, você precisa solicitar uma service account para o time responsável da Iplanrio. Esta service account deve ter as permissões necessárias para:

• Ler dados das tabelas do BigQuery
• Criar e modificar tabelas no projeto do BigQuery
• Executar jobs de processamento

6.2 Criar pasta de credenciais

Crie uma pasta chamada credentials fora do seu projeto para armazenar as credenciais de forma segura:

# Linux/macOS
mkdir ~/credentials

# Windows
mkdir C:\Users\%USERNAME%\credentials

Nunca inclua a pasta credentials no controle de versão (Git).

6.3 Adicionar arquivo da Service Account

1. Baixe o arquivo JSON da service account fornecida pelo time da Iplanrio
2. Mova o arquivo para a pasta credentials criada anteriormente
3. Renomeie o arquivo para algo descritivo, por exemplo: iplanrio-dbt-service-account.json

6.4 Criar arquivo profiles.yml

Crie um arquivo chamado profiles.yml na pasta credentials com a seguinte estrutura:

iplan:
  target: dev
  outputs:
    dev:
      type: bigquery
      method: service-account
      project: rj-iplanrio-dev
      schema: dbt_models
      location: US
      keyfile: /caminho/completo/para/credentials/iplanrio-dbt-service-account.json
      threads: 8
    
    prod:
      type: bigquery
      method: service-account
      project: rj-iplanrio
      schema: dbt_models
      location: US
      keyfile: /caminho/completo/para/credentials/iplanrio-dbt-service-account.json
      threads: 8

Substitua os valores pelos dados reais do seu projeto:

• rj-iplanrio-dev e rj-iplanrio: IDs dos projetos no Google Cloud
• dbt_models: schema padrão para os modelos do DBT
• keyfile: caminho completo para o arquivo JSON da service account

6.5 Configurar variáveis de ambiente

Configure a variável DBT_PROFILES_DIR para apontar para a pasta onde está o profiles.yml:

Linux/macOS

Adicione ao final do arquivo ~/.bashrc, ~/.zshrc ou outro arquivo de configuração do seu shell:

export DBT_PROFILES_DIR=~/credentials

Depois execute:

source ~/.bashrc  # ou ~/.zshrc, dependendo do seu shell

Windows

No Windows, configure a variável de ambiente:

setx DBT_PROFILES_DIR C:\Users\%USERNAME%\credentials

Ou através da interface gráfica:

1. Abra o menu Iniciar e busque por “Variáveis de ambiente”
2. Clique em “Editar variáveis de ambiente do sistema”
3. Na seção “Variáveis de usuário”, clique em “Novo” e adicione:
   • Nome da variável: DBT_PROFILES_DIR
   • Valor da variável: C:\Users\%USERNAME%\credentials

Sempre que você for trabalhar com DBT, verifique se as variáveis de ambiente estão corretamente definidas, especialmente DBT_PROFILES_DIR.

7. Configurar o GitHub (opcional, mas recomendado)

1. Crie uma conta em github.com
2. Configure o Git localmente:

git config --global user.name "Seu Nome"
git config --global user.email "[e-mail]"

---

🎉 Pronto!

Agora seu ambiente está preparado para iniciar projetos com o DBT.