datasette-upload-dbs 0.5a0 ganha API para trocar bancos SQLite em produção

Se você já publicou dados abertos ou montou uma análise exploratória em cima de um dump, conhece a dor: hospedar um dataset consultável costuma exigir um Postgres↳PostgreSQL11 conteúdosPostgreSQL via SSL com GolangData · abr 20195 itens legais sobre data types do PostgreSQLData · mar 20195 serviços gratuitos na cloud para bancos de dados PostgresData · fev 2025Ver tudo em Data → gerenciado, uma API custom ou algum serviço que cobra por linha. O Datasette, de Simon Willison, resolve isso de outro jeito, ele pega um arquivo .db SQLite e serve como site navegável, com interface de exploração e API JSON de graça. O plugin datasette-upload-dbs é a peça que faltava para transformar isso num fluxo de publicação de verdade, e o release 0.5a0 (11 de agosto de 2026) acaba de formalizar a parte mais importante: uma API para trocar bancos.

O que o plugin faz

O datasette-upload-dbs existe há um tempo e tem uma função simples: deixar você enviar um banco SQLite novo para uma instância Datasette hospedada. Assim que o upload termina, aquele banco passa a ser servido pela instância, sem redeploy, sem reiniciar processo.

O detalhe que sempre foi bom e agora fica explícito é a troca atômica. Quando você sobe uma versão mais recente de um banco que já existe, o plugin salva o arquivo enviado, verifica que ele é um SQLite válido e só então faz o swap. Do ponto de vista de quem está consultando /nome, a rota nunca serve um arquivo pela metade: ou responde a versão antiga, ou a nova. Isso importa porque SQLite é um arquivo único, e escrever por cima de um banco que está sendo lido é receita para corrupção. O datasette-upload-dbs encapsula esse cuidado para você.

A novidade do 0.5a0: API por HTTP

Até aqui, o upload era coisa de interface web. O 0.5a0 adiciona uma API formalizada, o que muda o jogo para automação. Substituir um banco existente (ou adicionar um novo) vira um único POST:

curl -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Accept: application/json" \
  -F "db=@content.db" \
  -F "db_name=content" \
  https://your-instance.example.com/-/upload-dbs

É um multipart/form-data com dois campos: o arquivo (db=@content.db) e o nome lógico do banco (db_name=content), autenticado por bearer token. Nada de SDK, nada de dependência extra, curl resolve. Se content já existe na instância, a chamada substitui atomicamente; se não existe, cria.

A consequência prática, e é isso que Willison destaca, é que dá para buildar o banco num ambiente como o GitHub Actions e fazer o swap em produção assim que o build termina. O padrão fica assim: um workflow agendado busca os dados na origem, monta o .db com sqlite-utils ou o que for, e no passo final faz o curl acima com o token guardado nos secrets. Publicação de dados vira commit-and-push.

Por que isso interessa no stack brasileiro

Dado aberto no Brasil é abundante e mal servido. Portal da Transparência, dados do TSE, IBGE, séries do Banco Central, boletins de secretarias estaduais, quase tudo sai como CSV ou planilha que ninguém consegue consultar sem baixar e abrir em algo. O caminho tradicional para deixar isso explorável (subir num Postgres, escrever uma API, hospedar) tem custo de infra recorrente que mata projeto de dados abertos feito por uma pessoa ou por uma ONG.

O combo Datasette + datasette-upload-dbs derruba esse custo para quase zero:

• Você mantém o pipeline de transformação no CI (grátis para repositório público no GitHub Actions), onde o CSV bruto vira SQLite tratado.
• A instância Datasette roda num container barato ou em algo como Fly.io/Railway/Render, com disco persistente pequeno, já que SQLite é um arquivo.
• A atualização é um POST no fim do build. Se a fonte publica novos dados toda semana, seu dataset acompanha sem intervenção manual.

Para quem trabalha com Supabase ou Convex no dia a dia, vale o contraste: esses BaaS brilham em app transacional com escrita constante de usuário. Um dataset de dados abertos é o oposto, escrita em lote (uma vez por ciclo) e leitura pública massiva. Nesse cenário, servir um SQLite read-only pelo Datasette é mais simples e mais barato do que manter uma tabela num Postgres gerenciado só para consulta. É a ferramenta certa para o formato do problema.

O que observar antes de adotar

Honestidade sobre limitações, porque a facilidade esconde algumas arestas:

• É um alpha. A versão é 0.5a0, ou seja, pré-release. A API está formalizada, mas o contrato ainda pode mudar antes de um 0.5 estável. Fixe a versão no seu ambiente.
• Modelo é read-mostly. O Datasette serve dados; você não faz INSERT incremental por essa via. O fluxo é rebuildar o banco inteiro e trocar. Para datasets grandes, o custo é reconstruir e transferir o arquivo a cada atualização, o que fica caro se o .db tem gigabytes.
• Tamanho do upload. Trocar bancos muito grandes por HTTP tem os limites de timeout e de disco da sua hospedagem. Para volumes maiores, o padrão de gerar o arquivo diretamente no host (em vez de fazer upload) pode ser melhor.
• Segurança do token. O $API_TOKEN dá poder de sobrescrever qualquer banco da instância. Trate como segredo de deploy, com escopo e rotação.

Como testar em cinco minutos

O caminho mais rápido para ver funcionando, localmente:

pip install datasette datasette-upload-dbs sqlite-utils

# monta um banco de exemplo a partir de um CSV
sqlite-utils insert content.db dados dados.csv --csv

# sobe a instância com o plugin
datasette --root

Com a instância no ar e um token gerado (o Datasette tem geração de tokens embutida), o mesmo curl do release troca o banco. A partir daí, é replicar esse passo dentro de um .github/workflows/*.yml e você tem publicação contínua de dados sem manter servidor de aplicação nenhum.

O release é pequeno em linhas de código, mas fecha uma lacuna real: agora o ciclo de vida de um dataset publicado, do CSV bruto à página consultável na web, cabe inteiro num pipeline de CI. Para dados abertos no Brasil, onde a barreira quase nunca é técnica e quase sempre é de custo e manutenção, isso é exatamente o tipo de atrito que precisava sumir.

Fonte: Simon Willison