Instalação do DBT e dependências

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

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

Baixe o arquivo JSON da service account fornecida pelo time da Iplanrio
Mova o arquivo para a pasta credentials criada anteriormente
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:

Abra o menu Iniciar e busque por “Variáveis de ambiente”
Clique em “Editar variáveis de ambiente do sistema”
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)

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

git config --global user.name "Seu Nome"
git config --global user.email "seu@email.com"

🎉 Pronto!

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

Visão Geral

Guia de Desenvolvimento

Acesso aos Dados

✅ Pré-requisitos

1. Instalar o Python

macOS / Linux (com pyenv)

Windows

2. Instalar o Visual Studio Code

Instalação

Extensões recomendadas

3. Instalar o Git

macOS (via Homebrew)

Linux (via apt)

Windows

4. Criar e ativar um ambiente virtual Python

Linux/macOS

Windows

5. Instalação do DBT

6. Configurando variáveis de ambiente e credenciais

6.1 Solicitar Service Account

6.2 Criar pasta de credenciais

6.3 Adicionar arquivo da Service Account

6.4 Criar arquivo profiles.yml

6.5 Configurar variáveis de ambiente

Linux/macOS

Windows

7. Configurar o GitHub (opcional, mas recomendado)

🎉 Pronto!

​✅ Pré-requisitos

​1. Instalar o Python

​macOS / Linux (com pyenv)

​Windows

​2. Instalar o Visual Studio Code

​Instalação

​Extensões recomendadas

​3. Instalar o Git

​macOS (via Homebrew)

​Linux (via apt)

​Windows

​4. Criar e ativar um ambiente virtual Python

​Linux/macOS

​Windows

​5. Instalação do DBT

​6. Configurando variáveis de ambiente e credenciais

​6.1 Solicitar Service Account

​6.2 Criar pasta de credenciais

​6.3 Adicionar arquivo da Service Account

​6.4 Criar arquivo profiles.yml

​6.5 Configurar variáveis de ambiente

​Linux/macOS

​Windows

​7. Configurar o GitHub (opcional, mas recomendado)

​🎉 Pronto!

✅ Pré-requisitos

1. Instalar o Python

macOS / Linux (com pyenv)

Windows

2. Instalar o Visual Studio Code

Instalação

Extensões recomendadas

3. Instalar o Git

macOS (via Homebrew)

Linux (via apt)

Windows

4. Criar e ativar um ambiente virtual Python

Linux/macOS

Windows

5. Instalação do DBT

6. Configurando variáveis de ambiente e credenciais

6.1 Solicitar Service Account

6.2 Criar pasta de credenciais

6.3 Adicionar arquivo da Service Account

6.4 Criar arquivo profiles.yml

6.5 Configurar variáveis de ambiente

Linux/macOS

Windows

7. Configurar o GitHub (opcional, mas recomendado)

🎉 Pronto!