Iceberg Studio

Explorador web de tabelas Apache Iceberg, no espírito de uma IDE de dados (DataGrip/DBeaver): navegue por vários catálogos, inspecione schema, snapshots e arquivos, rode SQL com time travel e faça a manutenção das tabelas — tudo pelo navegador, rodando na sua máquina.

• Catálogos: REST (com SigV4), Hive, Glue, SQL e Hadoop, vários ao mesmo tempo.
• Tabela: schema (com histórico e diff entre versões), partition spec, propriedades, saúde (arquivos pequenos, deletes), evolução de registros e tamanho por snapshot.
• Snapshots: linha do tempo, comparação de schema e diff de dados (linhas que entraram e saíram), tags e branches, rollback e expire com confirmação e auditoria.
• SQL: por tabela ou num editor do catálogo inteiro, com JOIN entre tabelas, autocomplete, formatador (Ctrl+Shift+F), exportação CSV/Parquet e time travel (VERSION AS OF 'tag', TIMESTAMP AS OF '...').
• Manutenção: política de retenção de snapshots com prévia, evolução de schema e comandos prontos de limpeza física pra Spark/Trino.

Instalação

Precisa só do uv — ele baixa o Python certo sozinho se a máquina não tiver:

# Linux / macOS
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

E então:

uvx iceberg-studio

Sobe o servidor e abre o navegador em http://127.0.0.1:8000/ui/. Pra instalar de vez (fica o comando iceberg-studio no PATH):

uv tool install iceberg-studio      # ou: pipx install iceberg-studio
uv tool upgrade iceberg-studio      # atualizar

Opções:

Os catálogos que você cadastra e a trilha de auditoria ficam em ~/.iceberg-studio (ou --data-dir / ICEBERG_APP_DATA_DIR). Atualizar ou reinstalar o app não apaga nada lá.

Segurança

Feito pra uso local: CORS fechado pra outros domínios e sem login. Fora do localhost, qualquer um que alcançar a porta acessa os catálogos configurados. Antes de expor na rede, configure:

• ICEBERG_APP_API_KEY — exige o header X-API-Key em toda rota sob /catalogs. A UI pergunta a chave uma vez e guarda no navegador.
• ICEBERG_APP_ALLOWED_ORIGINS — origens (separadas por vírgula) autorizadas a chamar a API via JavaScript de outro domínio. Vazio = nenhuma.

Segredos de catálogo (s3.secret-access-key, tokens, senhas) ficam em texto no catalogs.json; pra evitar isso, use ${ENV:NOME_DA_VAR} como valor da propriedade — é resolvido do ambiente na hora de conectar.

Desenvolvimento

# backend + ferramentas de teste (instala o projeto em modo editável)
pip install -r requirements-dev.txt

# frontend: build de produção, embutida no pacote em iceberg_studio/web/
cd frontend && npm install && npm run build && cd ..

# sobe API + UI (também dá: iceberg-studio)
uvicorn iceberg_studio.main:app --reload --port 8000

Rodando do código-fonte, os dados ficam em config/ na raiz do projeto, em vez de ~/.iceberg-studio.

Frontend com hot reload (http://localhost:5173, com proxy pro backend em localhost:8000):

cd frontend && npm run dev

Testes:

pytest                       # backend (catálogo e warehouse temporários; não toca no config/)
cd frontend && npm test      # frontend (vitest)

Publicar uma versão

1. Suba version no pyproject.toml e faça o commit.
2. Crie e envie a tag correspondente:

   git tag v0.2.0 && git push origin v0.2.0
   

3. O workflow Release builda o frontend, gera o pacote, testa o pacote instalado, publica no PyPI e cria a release no GitHub com os arquivos.

A publicação usa Trusted Publishing (sem token guardado). Configuração única, em https://pypi.org/manage/account/publishing/ → Add a new pending publisher:

API

A UI usa a mesma API HTTP, que também pode ser chamada direto. Rotas de tabela ficam sob /catalogs/{catalogo}/tables/{namespace}/{tabela}.

Toda escrita exige actor (quem fez) e, nas destrutivas, a confirmação do nome da tabela; tudo fica na auditoria. Exemplo:

curl -X POST http://localhost:8000/catalogs/local/query \
  -H "Content-Type: application/json" \
  -d '{"sql": "select status, count(*) from ecommerce.orders version as of '"'"'v1'"'"' group by status"}'

Estrutura

iceberg_studio/         - backend (FastAPI), publicado como o pacote iceberg-studio
  cli.py                - comando `iceberg-studio`
  main.py               - monta o app: CORS, routers e a interface em /ui
  settings.py           - configuração via ambiente (diretório de dados, CORS)
  api/                  - rotas HTTP (catálogos, tabelas), modelos e dependências
  services/             - casos de uso (escritas auditadas, retenção, schema, refs)
  catalogs/             - registro de catálogos, tipos suportados, adapters, SigV4
  query.py              - SQL via DuckDB sobre scans Arrow (time travel, exportação)
  snapshot_diff.py      - diff de dados entre snapshots
  retention.py          - política de retenção de snapshots
  web/                  - build do frontend (gerada, fora do git)
frontend/               - SPA React + Vite + TypeScript + Tailwind v4
tests/                  - pytest, espelhando iceberg_studio/
config/                 - estado local ao rodar do código-fonte (fora do git)

Limitações conhecidas

• Limpeza física: o PyIceberg não apaga arquivos nem compacta dados. Expirar snapshots remove só os metadados; o app gera os comandos de Spark/Trino pra limpeza física.
• ORC: a leitura de data files em ORC é limitada no PyIceberg.
• Um usuário por instância: não há login; o "ator" da auditoria é um nome digitado.

Licença

Apache 2.0.