Instackup

O Instackup é uma biblioteca Python, publicada no PyPI, que padroniza e simplifica as conexões com os serviços de nuvem e bancos de dados usados no trabalho com dados: BigQuery, Google Cloud Storage, Google Sheets, Amazon S3, Redshift, PostgreSQL, MySQL e SQLite. O mesmo código roda no computador, durante o desenvolvimento, e em produção, em pipelines agendados (a documentação dela está em inglês).

Ela é instalada com os extras dos serviços que forem usados:

pip install 'instackup[gcp,postgresql]'

from instackup import BigQueryTool, PostgreSQLTool

with PostgreSQLTool() as pg:
    orders = pg.query("SELECT * FROM orders WHERE created_at >= %s", params=("2026-01-01",))

BigQueryTool().upload(orders, dataset="analytics", table="orders", if_exists="replace")

O projeto original

Comecei o Instackup em dezembro de 2019, quando estava começando na engenharia de dados. A ideia era parar de reescrever o mesmo código de conexão em cada script e ter o mesmo código rodando em desenvolvimento, no meu computador, e em produção, em pipelines agendados. Então juntei esse código em uma biblioteca, com uma classe para cada serviço (BigQueryTool, S3Tool, RedShiftTool...) e as credenciais de todos eles em um único arquivo YAML.

A primeira versão foi para o PyPI em janeiro de 2020. Até a versão 0.3.0, em fevereiro de 2021, foram 18 versões, que acrescentaram o Google Cloud Storage, o Google Sheets, os bancos de dados SQL e mais de uma conta por serviço. Depois disso, a biblioteca ficou parada por mais de cinco anos.

Cinco anos depois

Cinco anos é muito tempo no ecossistema Python, e isso apareceu:

• A biblioteca exigia o Python 3.6 e fixava versões antigas das dependências (como grpcio==1.34.0 e gspread==3.6.0), o que a tornava impossível de instalar junto com qualquer coisa moderna.
• As dependências mudaram: o pandas 3 removeu o DataFrame.to_gbq, usado para enviar dados ao BigQuery; as bibliotecas do BigQuery Data Transfer, do gspread e do Cloud Storage mudaram as suas APIs; e o oauth2client estava descontinuado desde 2017.
• As credenciais só vinham de um arquivo no disco, com chaves e senhas em texto puro. Não é assim que a produção deveria funcionar hoje, com gerenciadores de segredos e as identidades das próprias plataformas de nuvem (IAM roles, contas de serviço).
• Ela criava arquivos de log dentro da sua própria pasta de instalação, o que falha em sistemas somente leitura, como contêineres.
• E os testes cobriam um único módulo, então não havia como saber o que ainda funcionava.

A versão 0.4.0

A revisão manteve o propósito da biblioteca e os nomes dos seus módulos, classes e métodos, para que a maioria dos scripts existentes continue funcionando, e reconstruiu tudo ao redor deles:

• Python e dependências atuais. Python 3.11 a 3.15, pandas 3 e as bibliotecas atuais do Google e da AWS. Cada serviço virou um extra opcional: a instalação básica não traz mais todos os SDKs de nuvem (eram cerca de 100 pacotes), só o pandas e o PyYAML.
• Credenciais prontas para produção. Elas podem vir de variáveis de ambiente, do AWS Secrets Manager, do GCP Secret Manager ou de um arquivo que referencia variáveis de ambiente em vez de guardar os segredos. Quando nenhuma é configurada, as ferramentas de nuvem usam a identidade da própria plataforma (as Application Default Credentials do Google e a cadeia padrão de credenciais da AWS).
• Cerca de 30 bugs corrigidos. Alguns métodos sempre falhavam, como renomear e excluir arquivos no S3 ou enviar e baixar pastas no Cloud Storage, e três falhas de segurança foram fechadas: SQL injection pelo nome de uma tabela, shell injection na ferramenta do Heroku e downloads de pastas que podiam gravar arquivos fora da pasta de destino.
• Testes e automação. São 420 testes, com simulações e o moto no lugar dos serviços de nuvem, além de testes de integração com bancos PostgreSQL e MySQL de verdade. O GitHub Actions os roda no Python 3.11 a 3.15, no Linux, no macOS e no Windows, e publicar uma release no GitHub envia o pacote para o PyPI, sem nenhum token guardado (Trusted Publishing).
• Tipos e documentação. Type hints em todo o código, verificadas pelo mypy, documentação de cada módulo e um documento de arquitetura com os motivos de cada decisão e os próximos passos.

Todas as mudanças, inclusive as poucas que quebram a compatibilidade, estão no registro da versão.

Revisando com o Claude

Toda a revisão foi feita com o Claude Code, o agente de programação da Anthropic, usando o modelo Claude Opus 5.5, que assina os commits como coautor. É um único pull request, com 63 arquivos, cerca de 10.700 linhas adicionadas e 3.600 removidas, aberto, mesclado e publicado no PyPI no mesmo dia. É o tipo de trabalho que, num projeto pessoal, costuma ficar para sempre na lista do "um dia eu faço". O que fez a diferença:

• Código antigo, lido em minutos. Código que escrevi há cinco anos é quase código de outra pessoa. O Claude lê a biblioteca inteira, a documentação e o histórico em minutos, o que permitiu mudar tudo mantendo os scripts antigos funcionando.
• Cinco anos de mudanças de uma vez. Em vez de ler o changelog de uma dúzia de bibliotecas, tive a ajuda de quem já sabia o que mudou no pandas, nos SDKs do Google e da AWS e no gspread, e como migrar cada chamada.
• O trabalho que costuma ficar para depois. Testes, tipos, documentação e CI em três sistemas operacionais são o que torna uma biblioteca confiável, e também o que mais se adia num projeto pessoal. Com o Claude, eles deixam de ser a parte cara, e foi cobrindo cada método com testes que apareceram os bugs que ninguém tinha notado.
• Problemas em outros sistemas. A primeira execução do CI falhou no macOS e no Windows: o driver do MySQL usava uma constante de SSL que algumas versões do Python não têm, o pandas grava arquivos CSV com quebras de linha diferentes no Windows e o Windows encontra a pasta do usuário por outra variável. Tudo foi corrigido a partir dos logs do CI, em um segundo commit.
• Decisões registradas. Cada escolha, como o Python 3.11 como versão mínima, os extras opcionais e a compatibilidade com scripts antigos, está documentada com os seus motivos, o que deixa muito mais fácil revisar um pull request desse tamanho.

O Claude não substitui saber para que a biblioteca serve: o que manter, o que quebrar e o que deixar para depois continuam sendo decisões minhas. Mas ele transformou uma revisão que esperava havia cinco anos em um único pull request, e agora posso voltar a usar o Instackup em projetos novos, com 420 testes por trás.