Projeto Prático de Engenharia de Dados com Python, SQL e GitHub

 

Introdução:

      Este projeto apresenta uma aplicação prática de Engenharia de Dados em um cenário empresarial realista, utilizando Python, SQL, Git e GitHub, com base na arquitetura conceitual Medallion (Bronze, Silver e Gold), amplamente adotada em pipelines modernos de dados. O contexto do projeto está inserido no domínio de geoprocessamento, GIS e sensoriamento remoto, áreas que lidam com grandes volumes de dados espaciais, metadados técnicos e necessidade de rastreabilidade, qualidade e governança da informação. Para isso, são utilizados dados realistas em formato CSV, representando produtos e serviços geoespaciais comuns em empresas de tecnologia, engenharia e análise territorial.

A solução contempla todo o ciclo de um pipeline de dados:

• Ingestão de dados brutos (Bronze)

• Tratamento, padronização e validação (Silver)

• Modelagem analítica e consolidação para consumo (Gold)

   Todo o desenvolvimento é realizado em um ambiente virtual Python isolado, seguindo boas práticas de versionamento de dependências e organização de projeto. O repositório local é versionado com Git e publicado remotamente no GitHub via HTTPS, utilizando a GitHub CLI, simulando um fluxo profissional adotado em equipes corporativas.

     Este projeto tem como objetivo demonstrar, de forma clara e estruturada, competências essenciais para atuação em Engenharia de Dados, como:

• Organização de código e dados

• Uso de SQL para modelagem e validação

• Aplicação da arquitetura Medallion

• Controle de versão e colaboração com Git/GitHub

• Boas práticas de ambientes virtuais e reprodutibilidade

   O conteúdo apresentado faz parte de um portfólio técnico, voltado à demonstração prática de habilidades aplicáveis ao mercado de dados. Toda a documentação técnica sobre o projeto está no link:

https://github.com/userdanixdev/project_eng_data

Início do Projeto: Estruturação do Ambiente e Versionamento

   O ponto de partida deste projeto consiste na criação de um diretório local versionado, que posteriormente é publicado em um repositório remoto no GitHub, utilizando conexão HTTPS. Esse fluxo simula um cenário profissional, no qual o controle de versão e a rastreabilidade das alterações são fundamentais para a manutenção e evolução de soluções de dados.

      Em seguida, é criado um ambiente virtual Python dentro do diretório do projeto, respeitando boas práticas de isolamento e organização. O uso de ambientes virtuais garante que:

• A linguagem Python seja apontada exclusivamente para o ambiente do projeto

• As dependências e versões de bibliotecas fiquem isoladas

• O sistema operacional e outros projetos não sejam impactados por conflitos de versão

     Enquanto o ambiente virtual estiver ativo, todas as instalações de pacotes e execuções de código ocorrem dentro desse contexto isolado. Isso evita inconsistências comuns em ambientes globais, onde bibliotecas instaladas para um projeto podem interferir no funcionamento de outros.

      É importante destacar que não é considerado boa prática trabalhar em diferentes projetos com o mesmo ambiente virtual ativo. Caso o desenvolvedor acesse outro diretório e instale dependências acreditando estar em um novo projeto, essas bibliotecas serão adicionadas ao ambiente errado, resultando em projetos “quebrados”, erros de execução e dificuldade de rastreamento da causa do problema. Com o ambiente virtual desativado, o sistema passa a utilizar a instalação padrão da linguagem Python, e o gerenciador de pacotes instala dependências de forma global. Esse comportamento pode comprometer outros projetos e torna inviável o trabalho com múltiplos contextos, versões de bibliotecas ou linguagens diferentes.

    Portanto, a adoção disciplinada de ambientes virtuais isolados, aliada a um controle de versão bem estruturado, estabelece uma base sólida para o desenvolvimento do pipeline de dados que será construído ao longo do projeto.

Quando desativar o ambiente virtual?

    O ambiente virtual deve ser tratado como um recurso temporário e contextual, ativado apenas enquanto o projeto correspondente estiver em uso. Manter esse controle é essencial para evitar conflitos de dependências e comportamentos inesperados no ambiente de desenvolvimento.

O ambiente virtual deve ser desativado nas seguintes situações:

• Ao finalizar ou pausar o desenvolvimento de um projeto:
  Evita que comandos futuros sejam executados em um contexto incorreto.

• Ao alternar entre projetos diferentes:
  Cada projeto deve possuir seu próprio ambiente virtual, com dependências e versões específicas.

• Para executar scripts ou ferramentas de uso global:
  Garante que o sistema utilize a instalação padrão da linguagem.

• Para evitar a instalação de bibliotecas no ambiente errado:
  Um erro comum é instalar dependências acreditando estar em outro projeto, o que pode “quebrar” ambos.

    Como boa prática, o ambiente virtual deve ser criado e ativado sempre dentro da pasta do projeto. Além disso:

• Não reutilize o mesmo ambiente virtual em projetos diferentes

• Utilize nomes distintos e identificáveis para cada ambiente virtual

• Sempre verifique no terminal qual ambiente virtual está ativo antes de executar comandos

    Utilizar o ambiente virtual de outro projeto é uma armadilha comum no desenvolvimento com Python. Esse tipo de erro costuma gerar problemas difíceis de diagnosticar posteriormente, como falhas de importação, conflitos de versão e comportamento inconsistente do código. O uso disciplinado de ambientes virtuais contribui diretamente para reprodutibilidade, estabilidade e organização, pilares fundamentais em projetos profissionais de Engenharia de Dados.

Atenção aos Ambientes Virtuais (venv)

    O uso incorreto de ambientes virtuais é uma das principais fontes de erros silenciosos, conflitos de dependências e problemas difíceis de diagnosticar em projetos profissionais de dados e software. Abaixo estão exemplos reais e comuns que justificam a adoção rigorosa de boas práticas.

Problema nº 1 — Dependências “fantasmas”

    Um projeto funciona apenas na sua máquina. Por exemplo: Um Projeto A possui a biblioteca X. E um Projeto B não possui essa biblioteca. Por comodidade, o desenvolvedor utiliza o ambiente virtual do Projeto A no Projeto B. Inicialmente, tudo funciona. O problema surge quando outra pessoa clona o Projeto B (ou quando o projeto é executado em um servidor): a biblioteca X nunca foi instalada oficialmente no Projeto B, causando erro imediato. Esse problema costuma aparecer após pull requests, deploys ou troca de máquina.

Problema nº 2 — Conflito de versões

    O Projeto A utiliza o módulo X na versão 1.0. O Projeto B utiliza o mesmo módulo X, porém na versão 2.0. Ao reutilizar o mesmo ambiente virtual um projeto sobrescreve o outro, as funcionalidades quebram e erros estranhos surgem. O resultado são horas de debug até identificar que o problema não está no código, mas no ambiente.

Problema nº 3 — pip install quebra outro projeto

Você está trabalhando no Projeto B, mas com o ambiente virtual do Projeto A ativado.

Ao executar:

pip install alguma-biblioteca

    As dependências do Projeto A são alteradas sem que você perceba. O Projeto A pode parar de funcionar de forma inesperada, e o erro só será percebido muito tempo depois.

Problema nº 4 — requirements.txt mentiroso

    Ao compartilhar o mesmo ambiente virtual entre projetos as dependências se misturam, o arquivo requirements.txt perde a confiabilidade, as bibliotecas desnecessárias aparecem e outras essenciais podem faltar. Isso quebra completamente a reprodutibilidade, a replicação e o profissionalismo do projeto.

Problema nº 5 — Debug impossível em equipe

   Em ambientes colaborativos acontecem: “Na minha máquina funciona”,“Na sua máquina quebra”,“No servidor funciona diferente”. Esses cenários são típicos de ambientes mal isolados e são extremamente prejudiciais para empresas, pois podem afetar produção, pipelines e serviços críticos.

 Regra de Ouro:

Ambiente virtual não é reutilizável.
Ele nasce e morre com o projeto.

Boas Práticas Recomendadas:

• Criar um ambiente virtual por projeto

• Criar o ambiente dentro da pasta do projeto

• Utilizar nomes padrão como:

  • .venv

  • venv/

• Nunca versionar o ambiente virtual no Git

• Versionar sempre o arquivo:

  • requirements.txt

Por que NÃO versionar o ambiente virtual?

Ambientes virtuais são dependentes do sistema operacional. Contêm caminhos absolutos, Binários específicos, Arquitetura da máquina e funcionam apenas corretamente na máquina onde foram criados. Além disso podem conter centenas ou milhares de arquivos, tornam o repositório gigante e lento, geram conflitos de merge impossíveis de resolver, mascaram dependências não declaradas e quebram a reprodução do projeto em outras máquinas.

Por isso, muitas empresas bloqueiam pull requests que versionam ambientes virtuais. Versione o requirements.txt, não o ambiente virtual.

Gerenciamento de Dependências, Versionamento e Preparação do Projeto

    Após a ativação do ambiente virtual, o próximo passo é a instalação das dependências que serão utilizadas no projeto. Não há necessidade de instalar todas as bibliotecas logo no início: caso uma nova dependência seja lembrada durante o desenvolvimento, ela pode ser instalada normalmente ao longo do trabalho. É importante observar que, ao utilizar distribuidores de pacotes ou ambientes mais completos, o ambiente virtual pode conter diversos pacotes auxiliares, que não são necessariamente usados diretamente no código. Por esse motivo, neste projeto, recomenda-se não criar o arquivo requirements.txt no início.

    A abordagem adotada consiste em desenvolver o código normalmente, importar apenas os módulos realmente necessários e gerar o requirements.txt posteriormente, com base no código-fonte. Para isso, pode-se utilizar ferramentas como pipreqs, que geram o arquivo de dependências somente com os pacotes efetivamente importados no projeto, garantindo maior precisão e reprodutibilidade.

Atenção ao renomear o projeto

    Mesmo no início do desenvolvimento, é necessário cuidado ao renomear a pasta do projeto. Embora possa parecer que “nada foi criado ainda”, o ambiente virtual já é um processo ativo dentro da pasta, contendo caminhos absolutos do sistema operacional, links internos e referências ao nome antigo da pasta. Desativar o ambiente virtual não é o mesmo que destruí-lo. Portanto, ao renomear um projeto, é obrigatório destruir o ambiente virtual existente, sair da pasta do projeto, renomear o diretório e criar um novo ambiente virtual com o nome correto.

Exemplo de fluxo correto:

cd ..
mv project_01 projeto_01

Essa prática evita erros futuros difíceis de diagnosticar, especialmente relacionados a paths quebrados e comportamentos inesperados do Python.

Organização do repositório

Para manter o projeto limpo e profissional as pastas que não precisam ser versionadas devem ser adicionadas ao .gitignore e os ambientes virtuais nunca devem ser versionados. Muitas IDEs modernas automatizam a exclusão dessas pastas, reforçando boas práticas

Preparação do versionamento com Git

Antes de iniciar o desenvolvimento direto no código:

• Acesse a pasta do projeto pelo Git Bash

• Inicialize e versiona o projeto com Git

• Por boa prática, a partir da branch principal, crie uma branch de desenvolvimento:

git checkout -b develop ou main

Essa separação reflete um fluxo profissional, comum em equipes e ambientes corporativos.

Conexão com o GitHub via HTTPS e GitHub CLI

Neste projeto, a conexão com o repositório remoto é feita via HTTPS, utilizando o GitHub CLI (GH).

Para criar o repositório remoto via HTTPS utilizando CLI utilize o comando:

gh repo create project_eng_data --source=. --public -- push

O que é o GitHub CLI?

O GitHub CLI é uma ferramenta oficial que permite interagir com o GitHub diretamente pelo terminal:

https://cli.github.com/

       Ao autenticar com o GitHub CLI, o desenvolvedor conecta o terminal à sua conta GitHub, cria uma autenticação segura via token e passa a gerenciar repositórios sem depender do navegador. Com isso, o GitHub CLI permite criar repositórios, realizar push e pull e gerenciar issues e pull requests, trabalhando de forma integrada com Git. Esse passo é fundamental para simular um ambiente profissional real, onde o terminal é parte central do fluxo de trabalho.

   Com o repositório devidamente versionado, conectado ao GitHub via HTTPS, organizado em branches e com ambiente virtual corretamente configurado O próximo passo é abrir o projeto corretamente na IDE (normalmente o VS Code) e iniciar o desenvolvimento do pipeline de dados, agora focando diretamente no código e na lógica do projeto.

Cuidados a serem feitos: O gitignore e README.md deverão ser configurados.

Cenário Empresarial  - GeoInsight Analytics

Visão Geral da Empresa:

    A GeoInsight Analytics é uma empresa  de tecnologia especializada em soluções de inteligência geoespacial, atuando nos setores de planejamento urbano, meio ambiente, infraestrutura, gestão de riscos e apoio à tomada de decisão baseada em dados espaciais. A empresa fornece produtos e serviços de geoprocessamento para órgãos públicos, empresas de engenharia, construtoras, utilities e consultorias ambientais. Seu portfólio inclui mapas temáticos, imagens orbitais, modelos digitais de elevação e análises ambientais avançadas.

Contexto do Problema de Dados

    A GeoInsight Analytics recebe dados geoespaciais de múltiplos fornecedores, públicos e privados, em diferentes formatos, sistemas de coordenadas, resoluções espaciais e modelos de precificação. Esses dados chegam de forma despadronizada, geralmente em arquivos CSV, acompanhados dos respectivos arquivos geográficos (Shapefile, GeoTIFF, GeoPackage). Com o crescimento da empresa, surgiram desafios como:

• Falta de padronização dos metadados

• Dificuldade de rastrear origem, custo e cobertura dos produtos

• Inconsistências entre formatos, sistemas de coordenadas e escalas

• Baixa confiabilidade para análises estratégicas e relatórios gerenciais

Para resolver esse problema, a empresa decidiu implementar um pipeline de dados estruturado, baseado na arquitetura Medallion, utilizando Python, SQL e um Data Lake.

O Dataset de Produtos Geoespaciais

O arquivo CSV apresentado representa o catálogo interno de produtos e serviços geoespaciais da empresa, contendo metadados técnicos e comerciais de cada item.

Cada linha do dataset descreve um produto, incluindo:

• Tipo de dado: Raster ou Vetorial

• Resolução espacial: em metros ou escala cartográfica

• Sistema de coordenadas: padrões GIS (WGS84, SIRGAS 2000, UTM)

• Formato: Shapefile, GeoTIFF, GeoPackage

• Área de cobertura: extensão espacial do produto

• Preço: diferenciando dados públicos (0.00) de dados comerciais

Esse conjunto de dados permite que a empresa compreenda valor, qualidade, aplicabilidade e origem de cada produto geoespacial.

Pipeline de Dados - Arquitetura Medallion

Camada Bronze - Dados Brutos

    Na camada Bronze, o CSV é ingerido sem transformações, preservando o formato original recebido dos fornecedores. Os objetivos das camadas são em garantir rastreabilidade, manter histórico de ingestão e permitir auditoria dos dados. Exemplo de uso serão armazenamento do CSV original no Data Lake e registro da data de carga e fonte.

Camada Silver - Dados Tratados

   Na camada Silver, os dados passam por uma padronização de tipos (datas, números, textos), validação de domínios (Raster/Vetorial, sistemas de coordenadas), normalização de formatos e escalas e enriquecimento com regras de negócio. Exemplos como conversão de preços para tipo numérico, padronização dos sistemas de coordenadas e classificação de dados públicos vs. privados podem ser aplicados.

Camada Gold - Dados Analíticos

    Na camada Gold, os dados são modelados para consumo analítico, suportando dashboards, relatórios e decisões estratégicas. Exemplos de análises podem ser aplicadas como custo total por categoria de produto, cobertura territorial por tipo de dado, percentual de dados públicos vs. comerciais e produtos mais utilizados por tipo de projeto Esses dados podem ser consumidos por ferramentas de BI, relatórios executivos ou aplicações internas..

Onde esse Dataset é Útil:

  Este projeto é ideal para treinos e portfólio em Engenharia de Dados, projetos de GIS e sensoriamento remoto. Assim também para exercícios com Python e Pandas, carga e modelagem em PostGIS, simulação de pipelines corporativos e implementação de Data Lakes com governança.

Criação e Gerenciamento do requirements.txt

  Após o desenvolvimento inicial do projeto e com o ambiente virtual devidamente ativado, é fundamental registrar corretamente as dependências utilizadas. Esse processo garante reprodutibilidade, portabilidade e confiabilidade do projeto.

Gerando um arquivo temporário de dependências

No terminal Git Bash, execute:

pip freeze > requirements_tmp.txt

Esse comando cria um arquivo temporário na raiz do projeto contendo todas as dependências instaladas no ambiente virtual, incluindo pacotes auxiliares e dependências indiretas.

Critério de engenheiro, não apenas de ferramenta:

O arquivo gerado pelo pip freeze não deve ser usado diretamente como requirements.txt.

Neste ponto, entra o papel do engenheiro de dados:

• Analisar as dependências listadas

• Remover pacotes que não são utilizados no projeto

• Manter apenas as bibliotecas realmente necessárias

• Garantir clareza e simplicidade

De forma prática:

1. Abra o arquivo requirements_tmp.txt

2. Remova dependências desnecessárias

3. Salve o conteúdo final como requirements.txt

4. Exclua o arquivo temporário

Esse cuidado evita ambientes inflados, conflitos desnecessários e dificuldades de manutenção. Ao instalar as dependências a partir do requirements.txt com o ambiente virtual ativado, execute:

pip install -r requirements.txt

  Esse comando instala exatamente as bibliotecas declaradas, respeitando as versões definidas e garantindo que qualquer pessoa consiga reproduzir o ambiente. Em alguns casos, o Jupyter Notebook não é instalado como o meta-pacote jupyter, mas sim como pacotes separados. Caso isso ocorra, instale explicitamente:

pip install jupyter
pip install jupyter ipykernel
pip install pandas

    Esses pacotes são comuns em projetos de Engenharia de Dados e análise exploratória, especialmente em fases de ingestão, validação e exploração dos dados.

Considerações Finais

    Este trabalho apresentou, de forma prática e estruturada, a construção de um pipeline de dados com Python, SQL, Git e GitHub, aplicado a um cenário empresarial fictício, porém realista, no contexto de geoprocessamento e engenharia de dados. Ao longo do projeto, foram abordadas boas práticas fundamentais, como:

• Uso disciplinado de ambientes virtuais

• Gerenciamento correto de dependências

• Versionamento profissional com Git e GitHub

• Organização do projeto em branches

• Aplicação da arquitetura Medallion (Bronze, Silver e Gold)

• Preocupação com reprodutibilidade, governança e qualidade dos dados

    O foco não esteve apenas nas ferramentas, mas principalmente nos conceitos e decisões técnicas, simulando desafios reais encontrados em ambientes corporativos e projetos colaborativos. Mais detalhes técnicos, código-fonte, estrutura do projeto e evolução do pipeline estão disponíveis no repositório do GitHub, onde todo o desenvolvimento está documentado e versionado.

    Este projeto faz parte de um portfólio técnico, com o objetivo de demonstrar competências práticas em Engenharia de Dados, desde a organização do ambiente até a preparação de dados para análise e consumo.