Consulta SQL

A Guara Cloud permite executar instruções somente leitura nos seus serviços gerenciados de PostgreSQL e MySQL sem nunca expor o banco à internet pública. As consultas rodam dentro do cluster, os resultados retornam pela API da plataforma e o mesmo recurso está disponível tanto no dashboard quanto na CLI.

Onde funciona

Serviço do catálogo	Suportado
PostgreSQL	✓
MySQL	✓
MongoDB / Redis / NATS / outros	— (sem superfície SQL)

O serviço precisa estar running e healthy. O acesso SQL faz parte do conjunto padrão do catálogo e segue as mesmas regras de membro de projeto que o restante do dashboard.

Modelo de segurança

Toda requisição roda dentro de uma transação somente leitura explícita (BEGIN READ ONLY no PostgreSQL, START TRANSACTION READ ONLY no MySQL). A plataforma também aplica:

Limite	Valor
Timeout de execução	30 s
Tamanho máximo da consulta	50 KB
Linhas retornadas no máximo	1 000 (servidor adiciona `LIMIT`)
Consultas simultâneas por usuário × serviço	3
TTL do cache de resultados	15 s

Cada requisição pode carregar apenas uma instrução. Sequências (SELECT 1; SELECT 2) são rejeitadas antes da execução. Se o resultado bater no limite de linhas a resposta traz truncated: true, e a CLI imprime uma linha amarela ⚠ result truncated sob a tabela.

Use a partir da CLI

Dois comandos vivem dentro do tópico existente catalog:

guara catalog query   # executa uma instrução SQL
guara catalog schema  # lista tabelas e colunas

Ambos resolvem projeto + serviço a partir de --project/--service, das variáveis de ambiente (GUARA_PROJECT, GUARA_SERVICE) ou de um arquivo .guara.json.

`guara catalog query`

Passe o SQL via --query, carregue de um arquivo com --file (alias -f, ou - para ler do stdin) ou envie pelo stdin (detectado automaticamente quando o stdin não é TTY):

# Instrução inline
guara catalog query --query "SELECT id, email FROM users LIMIT 10"

# De um arquivo .sql
guara catalog query --file ./reports/active-users.sql --format csv > users.csv

# Pelo stdin (detectado automaticamente quando stdout não é um TTY)
cat ./reports/active-users.sql | guara catalog query --service my-postgres

Formatos de saída — escolha um com --format (renderização TTY / arquivo):

`--format`	Resultado
`table` (padrão)	Tabela bonita do `cli-table3` com rodapé `{rows} · {ms}` (acrescido de `· cached @ {time}` quando o resultado vem do cache).
`csv`	CSV escapado segundo a RFC-4180 (aspas em volta de valores com vírgula, aspas ou nova linha). Células iniciadas por `=`, `+`, `-`, `@`, tab ou retorno de carro recebem o prefixo `'` para neutralizar injeção de fórmula em planilhas — desative com `--no-csv-safe` se precisar de fidelidade bruta.
`tsv`	Valores separados por tabulação. Tabs e quebras de linha dentro das células viram espaços para que cada linha permaneça em uma única linha. A mesma opção `--no-csv-safe` se aplica.

Flags globais de saída (aplicáveis independentemente do --format):

Flag	Resultado
`--json`	Envelope completo `SqlQueryResponse` — `columns`, `rows`, `rowCount`, `truncated`, `executionTimeMs`, `fromCache`, `cachedAt`. Sobrepõe o `--format`. Bytes de controle brutos das células são preservados aqui para que consumidores máquina vejam a verdade.
`--quiet`	Apenas a contagem de linhas em uma única linha (útil em condicionais de shell). Sobrepõe o `--format`.

Bytes de controle ANSI/OSC dentro de células string são removidos da renderização table/CSV/TSV para que um valor malicioso não consiga mover o cursor, falsificar o título do terminal ou mascarar hyperlinks. --json é a saída de fuga quando você precisa dos bytes originais.

`guara catalog schema`

guara catalog schema                       # lista cada tabela e suas colunas
guara catalog schema --filter users        # filtra por substring (case-insensitive)
guara catalog schema --json | jq .         # esquema completo em formato máquina
guara catalog schema --quiet               # um nome de tabela por linha

Cada tabela é renderizada como um bloco próprio com uma pequena tabela de colunas (Column, Type, Constraint).

Códigos de erro

A CLI mapeia os códigos da plataforma para dicas acionáveis. Cada um aparece como uma linha Hint: sob a mensagem vermelha ✖ e usa os exit codes padrão (1 para falha, 2 para autenticação).

Código	Quando	O que fazer
`SQL_QUERY_SERVICE_NOT_CAPABLE`	Serviço não é PostgreSQL/MySQL	Use um serviço de banco que liste `sql-query` em suas capabilities.
`SQL_QUERY_SERVICE_NOT_RUNNING`	Serviço não está running + healthy	Aguarde o serviço estabilizar (`guara services info`).
`SQL_QUERY_TOO_LONG`	Consulta excede 50 KB	Quebre a consulta ou use um `--file` menor.
`SQL_QUERY_TIMEOUT`	Bateu no timeout de 30 s	Adicione um `LIMIT`, restrinja o filtro ou pré-agregue.
`SQL_QUERY_EXECUTION_FAILED`	Banco rejeitou o SQL	Rode com `--json` para ler o payload completo.
`SQL_QUERY_CONNECTION_FAILED`	Não foi possível conectar	O serviço pode estar reiniciando — tente de novo em instantes.
`SQL_QUERY_SCHEMA_UNAVAILABLE`	Falha na introspecção do esquema	O serviço pode estar unhealthy — confira o status e tente de novo.
`SQL_QUERY_MULTI_STATEMENT`	Mais de uma instrução por requisição	Envie uma instrução por vez.
`SQL_QUERY_CONCURRENCY_EXCEEDED`	Já há três consultas em voo nesse serviço	Aguarde uma terminar ou cancele e tente de novo.

Use a partir do dashboard

O mesmo recurso vive em cada página de detalhe de serviço PostgreSQL e MySQL na aba SQL Query: um editor CodeMirror, uma grade virtualizada de resultados, um navegador de esquema na lateral e draft + histórico persistidos localmente. Dashboard e CLI conversam com os mesmos endpoints, então uma consulta executada pela CLI obedece aos mesmos limites e à mesma trilha de auditoria (catalog.sql_query e catalog.sql_schema).

Veja também

Visão geral do Service Catalog
guara catalog deploy — provisione um serviço de banco antes de consultá-lo.
Autenticação & API keys — a CLI usa o mesmo fluxo X-API-Key que os demais comandos.