Linha de comando

Um binário autocontido. A máquina não precisa de nada instalado antes — nem runtime, nem gerenciador de pacotes. É o que permite usá-lo numa imagem de CI enxuta.

curl -fsSL https://api.datarunner.app/downloads/cli/install.sh | bash

irm https://api.datarunner.app/downloads/cli/install.ps1 | iex

Nenhum dos dois pede root ou administrador: instala no diretório do usuário e ajusta o PATH dele. O instalador confere o SHA256 publicado antes de instalar e recusa se não bater.

Em CI, fixe a versão. Um pipeline que resolve “latest” a cada execução é um pipeline cujo comportamento muda sem ninguém ter feito um commit.

curl -fsSL https://api.datarunner.app/downloads/cli/install.sh | bash -s -- --version 0.1.1

Depois de instalar, isto é uma sessão inteira do começo ao fim. O passo que costuma faltar é o segundo: uma consulta tem um id, e listar é o único lugar de onde ele sai.

1. 01Entrar, uma vez por máquina. A chave sai do console em Configurações → Chaves de API, e só é mostrada no momento em que você a cria.
2. 02Listar o que existe no workspace. É daqui que sai o id que os outros comandos pedem.
3. 03Rodar uma consulta e olhar o resultado.
4. 04Transformar a consulta numa verificação que o build entende.

datarunner auth login --url https://api.datarunner.app --key dr_...

Conectado como voce@acme.com (admin) em https://api.datarunner.app.
Perfil 'default' salvo em ~/.datarunner/config.json.

datarunner query list

id                                    nome             conexao     atualizada
────────────────────────────────────  ───────────────  ──────────  ──────────────
3f2a91c4-8e17-4b2a-9f03-1d5c7e8a2b60  Receita mensal   Postgres    2026-09-01 14:22
a7c04e12-3b95-4d81-b6ef-92a10c4d7f38  Pedidos orfaos   Postgres    2026-08-28 09:10

datarunner query run 3f2a91c4-8e17-4b2a-9f03-1d5c7e8a2b60

mes         total
──────────  ─────────
2026-07     184320.50
2026-08     201455.00

2 linha(s) em 340ms.

datarunner query assert a7c04e12-3b95-4d81-b6ef-92a10c4d7f38 --expect-empty

ok — 0 linha(s) em 120ms.

Esse último comando sai com código 0 quando não veio linha nenhuma e 1 quando veio. É isso, e só isso, que faz um pipeline parar quando a integridade dos dados quebrou.

A chave sai de Configurações → Chaves de API. Os escopos dela limitam o que a ferramenta alcança por cima do papel de quem a criou: uma chave restrita continua restrita mesmo pertencendo a um administrador, e nunca concede poderes de plataforma.

datarunner auth login --url https://api.datarunner.app --key dr_...

export DATARUNNER_URL=https://api.datarunner.app
export DATARUNNER_KEY=dr_...

Para rodar consultas num pipeline, marque o escopo run:queries. Ele já inclui a leitura e não permite alterar nada. Listar consultas e executar SQL contra um banco de produção são poderes diferentes, então read:queries sozinho não executa.

Chaves de API não estão disponíveis no plano gratuito, então a linha de comando também não.

Uma consulta que lista linhas órfãs é algo que qualquer pessoa escreve hoje e não consegue impor em lugar nenhum. Com o comando abaixo ela vira um passo do pipeline: se a migração quebrou a integridade referencial, o build falha, em vez de a produção descobrir depois.

datarunner query assert 3f2a... --expect-empty

Se o resultado bater no teto de linhas do plano, a verificação falha em vez de passar. Uma contagem cortada não é uma contagem, e um --expect-empty que passa porque o teto escondeu as linhas é pior que verificação nenhuma — alguém está confiando nele.

Cada comando tem ajuda própria: datarunner help query, datarunner help sync, e assim por diante. O comando datarunner help ci imprime um arquivo de pipeline pronto.

run:queries já inclui a leitura, então uma chave de CI que só verifica dados precisa apenas dele. Listar consultas e executar SQL contra um banco de produção são poderes diferentes — por isso read:queries sozinho não executa nada.

O primeiro reflexo de quem usa isto é apontar para homologação e depois para produção. Perfis existem para essa troca não ser um novo login.

datarunner auth login --url https://api.acme.dev --key dr_... --profile dev
datarunner auth login --url https://api.acme.com --key dr_... --profile prod

datarunner auth use prod
datarunner query list --profile dev    # sem trocar o atual

O arquivo fica em ~/.datarunner/config.json, com permissão 600 no Linux e no macOS. O logout remove o perfil da sua máquina; a chave continua válida no servidor até alguém revogá-la no console.

O formato padrão é tabela. Passe --json ou --csv quando um programa for ler a saída — e é só nesse caso que o progresso sai pela saída de erro, para não sujar o que você está capturando. Não há adivinhação: o PowerShell reporta a saída como redirecionada mesmo num prompt comum, então tentar detectar isso dava JSON na cara de quem só queria olhar.

datarunner query run 3f2a... | jq '.rows[0]'
datarunner query run 3f2a... --format csv > receita.csv

A separação entre 1 e 4 é o ponto: um pipeline precisa distinguir “o dado está errado” de “a ferramenta está quebrada” sem interpretar texto.

• datarunner monitor status --fail-on-down — trava um deploy enquanto algo já está fora do ar.
• datarunner sync run <id> --wait — dispara um sync e acompanha até o fim. Sem --wait, “enfileirado” não é “funcionou”.
• datarunner query list, connection list, whoami.