> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dados.rio/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Note>
  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.
</Note>

Recomendamos instalar a última versão do Python via [pyenv](https://github.com/pyenv/pyenv) no Linux/macOS ou diretamente do site oficial no Windows.

<Warning> O DBT requer Python 3.9 ou superior. </Warning>

### macOS / Linux (com pyenv)

```bash theme={null}
# 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/](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:

```bash theme={null}
python --version
pip --version
```

## 2. Instalar o Visual Studio Code

<Note>
  O [Visual Studio Code (VS Code)](https://code.visualstudio.com/) é um editor
  de código leve e poderoso, muito utilizado em projetos com Python, DBT e Git.
</Note>

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/](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

<Note>
  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.
</Note>

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)

```bash theme={null}
brew install git
```

### Linux (via apt)

```bash theme={null}
sudo apt update
sudo apt install git
```

### Windows

Baixe o instalador em: [https://git-scm.com/download/win](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:

```bash theme={null}
git --version
```

## 4. Criar e ativar um ambiente virtual Python

<Note>
  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.
</Note>

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

### Linux/macOS

Criar o ambiente:

```bash theme={null}
python -m venv dbt-env
```

Ativar o ambiente:

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

```bash theme={null}
source dbt-env/bin/activate
```

### Windows

Criar o ambiente:

```cmd theme={null}
python -m venv dbt-env
```

Ativar o ambiente:

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

```cmd theme={null}
dbt-env\Scripts\activate
```

Desativar o ambiente (qualquer sistema):

```bash theme={null}
deactivate
```

## 5. Instalação do DBT

<Note>
  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.
</Note>

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:

```bash theme={null}
python -m pip install dbt-core dbt-bigquery
```

Verifique a instalação:

```bash theme={null}
dbt --version
```

Saída esperada (exemplo):

```bash theme={null}
Core:
  - installed: 1.9.3
  - latest:    1.9.4

Plugins:
  - bigquery: 1.9.1
```

## 6. Configurando variáveis de ambiente e credenciais

<Note>
  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.
</Note>

### 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:

```bash theme={null}
# Linux/macOS
mkdir ~/credentials

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

<Warning>
  Nunca inclua a pasta credentials no controle de versão (Git).
</Warning>

### 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:

```yaml theme={null}
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
```

<Note>
  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
</Note>

### 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:

```bash theme={null}
export DBT_PROFILES_DIR=~/credentials
```

Depois execute:

```bash theme={null}
source ~/.bashrc  # ou ~/.zshrc, dependendo do seu shell
```

#### Windows

No Windows, configure a variável de ambiente:

```cmd theme={null}
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`

<Warning>
  Sempre que você for trabalhar com DBT, verifique se as variáveis de ambiente estão corretamente definidas, especialmente <code>DBT\_PROFILES\_DIR</code>.
</Warning>

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

1. Crie uma conta em [github.com](https://github.com/)
2. Configure o Git localmente:

```bash theme={null}
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.