fluigcli db — consultas SQL de diagnóstico

O grupo db executa SQL de leitura contra um datasource do servidor de aplicação do Fluig. Você faz isso do terminal, sem acesso direto ao banco. Use o grupo para diagnóstico. Por exemplo, você confere as permissões do login do datasource. Você valida um SQL antes de colar num dataset. Você checa se um objeto ou uma coluna existe.

Estes comandos precisam do componente auxiliar fluigcliHelper 0.6.0 ou superior no servidor. Instale ou atualize o helper com o comando fluigcli server install-helper <name> [--force].

Estes comandos precisam de um usuário administrador do tenant. O helper aceita apenas consultas SELECT ou WITH. O helper recusa qualquer instrução de escrita (INSERT, UPDATE, DELETE, MERGE, INTO, DDL) em qualquer posição da consulta. O helper também recusa mais de uma instrução por consulta. A verificação ignora literais, comentários e nomes entre colchetes ou aspas. Por isso WHERE acao = 'update' e uma coluna [delete] continuam válidos.

A verificação é um guarda-corpo, não uma fronteira de segurança

A verificação é textual. Ela protege contra o comando errado, não contra um usuário mal-intencionado. A fronteira real é a permissão do usuário do datasource no banco de dados.

Não confie no modo somente leitura da conexão JDBC. O helper abre a conexão com setReadOnly(true), mas o driver do SQL Server ignora essa marca.

Para garantia real, aponte o --jndi para um datasource somente leitura, se o servidor publicar um. O comando db datasources mostra os nomes disponíveis.

O db é SQL cru de diagnóstico. Ele não é o mesmo que o dataset query, que executa um dataset cadastrado no Fluig.

fluigcli db datasources

Este comando lista os datasources JNDI disponíveis no servidor.

fluigcli db datasources
fluigcli db datasources --json

O comando marca o datasource padrão (/jdbc/AppDS, o banco do Fluig) em verde. Use um destes nomes na opção --jndi do db query.

O helper enumera os datasources pelo naming do servidor de aplicação. Alguns ambientes não permitem esta enumeração. Neste caso, a lista vem vazia. Passe o nome do datasource direto na opção --jndi do db query.

fluigcli db query

Este comando executa uma consulta de leitura e mostra o resultado em tabela.

fluigcli db query "select suser_sname() as login, db_name() as db"
fluigcli db query "select has_perms_by_name(?, 'OBJECT', 'INSERT') as ok" --param dbo.MINHA_TABELA
fluigcli db query "select top 10 * from wcm_application" --jndi /jdbc/TotvsRM
fluigcli db query "select 1" --json

• --jndi — o datasource JNDI. O valor padrão é /jdbc/AppDS (o banco do Fluig). Use db datasources para ver os nomes disponíveis.
• --param — o valor de um ? do SQL. A ordem dos --param segue a ordem dos ?. Repita a opção para cada ?. Use os ? para não concatenar valores no texto do SQL.
• --max-rows — o teto de linhas. O valor padrão é 500. O valor máximo é 10000.

O tempo limite deste comando tem piso de 2 minutos, não os 30 segundos do padrão global. Consulta de diagnóstico em tabela grande passa dos 30 segundos com facilidade. A opção --timeout sempre vence, inclusive para baixo. Com -v, a CLI informa no stderr quando eleva o valor.

O tempo limite é do cliente. Quando ele estoura, o servidor continua executando a consulta. Aumentar o valor deixa a espera mais longa, não mais barata.

No terminal, o comando mostra os nomes das colunas no cabeçalho. Ele mostra um valor nulo do banco como (null). Quando o resultado chega ao teto de linhas, o comando avisa. Neste caso, aumente o valor de --max-rows.

Com --json, o envelope traz {columns[], rows[], rowCount, truncated}. Cada item de columns tem name e type (o nome do tipo do driver). As linhas em rows são posicionais. Cada linha é um vetor alinhado com columns na ordem. Um valor nulo do banco vem como null no JSON.

Quando a consulta tem um erro de SQL, o servidor devolve a mensagem do banco. A CLI mostra esta mensagem e termina com o código 5. Quando a consulta não é de leitura, o servidor recusa com a mesma via.

⚠️ Status de solicitação: use o request, não SQL

As tabelas do Fluig guardam o status em colunas numéricas. Para status de solicitação, use o comando próprio:

fluigcli request list --process "Meu Processo" --status open        # em aberto
fluigcli request list --process "Meu Processo" --status finalized   # concluídas
fluigcli request list --process "Meu Processo" --status canceled    # canceladas

O comando devolve o mesmo conjunto que o SQL, sem depender de você lembrar o número certo. A tabela abaixo existe para quando o request não cobre o caso, por exemplo num cruzamento com tabela de negócio.

Enums das tabelas de processo

Medido na homologação em 2026-08-10 (Fluig Voyager 2.0.0), por cruzamento entre o SQL e os comandos da CLI. O schema interno não é contrato público da TOTVS. Confira antes de confiar numa versão diferente.

PROCES_WORKFLOW — uma linha por solicitação:

STATUS	significado	comando equivalente
0	em aberto	request list --status open
1	cancelada	request list --status canceled
2	concluída	request list --status finalized

⚠️ O 1 é canceled e o 2 é finalized. A ordem intuitiva seria a inversa. Este é o ponto que mais gera relatório errado.

TAR_PROCES — uma linha por tarefa de cada movimento:

IDI_STATUS	significado
0	NOT_COMPLETED — a tarefa está aberta
1	PENDING_CONSENSUS — aguarda consenso da atividade colaborativa
2	COMPLETED — a tarefa foi concluída
3	TRANSFERRED — a tarefa foi transferida
4	CANCELED — a tarefa foi cancelada

CLOSURE_STATUS	significado
0	a tarefa ainda está aberta
1	encerrada no prazo (ON_TIME)
2	encerrada em alerta (WARNING)
3	encerrada fora do prazo (EXPIRED)

O CLOSURE_STATUS da TAR_PROCES guarda o SLA no encerramento, não o resultado da tarefa. O resultado está no IDI_STATUS. A coluna LOG_ATIV = 1 marca a tarefa corrente.

⚠️ A coluna CLOSURE_STATUS da PROCES_WORKFLOW é diferente. Ela vale 0 em todas as 214.188 linhas da homologação. Não tire conclusão dela.

Como isso foi medido: 135 movimentos de 19 solicitações, comparando o request show --json de cada uma com as linhas da TAR_PROCES, sem nenhuma divergência. Os cinco valores de IDI_STATUS e os quatro de CLOSURE_STATUS apareceram na amostra. Os três valores de PROCES_WORKFLOW.STATUS foram conferidos em quatro processos, por contagem exata contra o request list --status.

Use o db query para o que o request não cobre: conferir se um objeto existe, testar permissão, medir volume ou cruzar tabelas de negócio.

Rodar um script .sql com --file

A opção --file lê um script e executa as instruções em sequência, uma por requisição. O servidor aceita uma instrução por chamada, por isso a CLI separa o script antes de enviar.

fluigcli db query --file diagnostico.sql --list          # só lista o que reconheceu
fluigcli db query --file diagnostico.sql                 # executa tudo, em ordem
fluigcli db query --file diagnostico.sql --statement 2   # executa só a 2ª

A CLI separa as instruções por ; e por GO sozinho na linha. A varredura ignora:

• literais ('a;b', com '' como escape);
• identificadores entre colchetes ([coluna;estranha]) e entre aspas;
• comentários de linha (--) e de bloco (/* */, inclusive aninhados).

Por isso um ; dentro de um texto ou de um comentário não separa nada. Uma instrução que só tem comentário é descartada.

A CLI também remove o comentário que vem antes do SQL de cada instrução. O servidor decide se a consulta é de leitura pela primeira palavra do texto que recebe, e ele não pula comentário. Sem essa limpeza, um -- nota acima de um select faria o servidor recusar a consulta. Os comentários no meio e no fim da instrução seguem intactos, e o campo sql do --json mostra exatamente o que foi enviado.

Comece por --list. Ele mostra o número, a linha no arquivo e o início de cada instrução, e não executa nada. Assim você confere a separação antes de rodar.

• --statement N — executa só a N-ésima instrução. A numeração começa em 1 e é a mesma que o --list mostra. Com --list junto, o comando lista só essa instrução — útil para conferir o texto dela antes de rodar.
• --param com --file exige --statement. Os ? são posicionais por instrução. Aplicar a mesma lista a várias instruções ligaria os valores ao SQL errado, em silêncio. Por isso a CLI recusa com o código 2.

Cada instrução vira um item de data.statements[] no --json, com index, line, sql, success e o resultado (columns, rows, rowCount). A instrução que falha traz error e não interrompe o script. Neste caso o comando termina com o código 6. Com --list, o envelope traz executed: false.

Um script (ou um --statement) com uma instrução só é alvo único. Aí o erro dela é o erro do comando, com o código dele — normalmente 5. Não existe falha parcial quando só há um item.

O SQL passado como argumento mantém o formato antigo de data ({columns[], rows[], rowCount, truncated}). O statements[] só aparece com --file.

A regra de leitura continua no servidor

O --file não relaxa nada. Cada instrução passa pela mesma validação do helper. Um script com UPDATE falha naquela instrução, e as demais seguem.

fluigcli db grants

Este comando confere as permissões do login do datasource nas tabelas que você informa. Use o comando como preflight antes de rodar um dataset de escrita. Sem ele, um grant faltante (por exemplo, INSERT para o login fluig) só aparece como erro de SQL quando o dataset roda. O comando mostra o problema antes, com o login e o banco em destaque.

fluigcli db grants dbo.ZMDFLANFLUIG
fluigcli db grants dbo.ZMDFLANFLUIG dbo.WCM_APPLICATION --perm INSERT,UPDATE
fluigcli db grants dbo.MINHA_TABELA --jndi /jdbc/TotvsRM
fluigcli db grants dbo.ZMDFLANFLUIG --json

O comando é para SQL Server. Para cada tabela, ele checa as permissões com a função HAS_PERMS_BY_NAME. Ele monta um único SELECT de leitura e o executa pela mesma via do db query.

• --perm — as permissões a checar. O valor padrão é SELECT,INSERT,UPDATE,DELETE. Separe os valores por vírgula. Os valores aceitos são SELECT, INSERT, UPDATE e DELETE.
• --jndi — o datasource JNDI. O valor padrão é /jdbc/AppDS. Use db datasources para ver os nomes disponíveis.

No terminal, o comando mostra uma linha com o login e o banco do datasource. Depois, ele mostra uma tabela com uma linha por objeto. Cada célula de permissão tem um marcador. O ✓ (verde) indica permissão concedida. O ✗ (vermelho) indica permissão negada. O ? (amarelo) indica objeto inexistente no banco daquele datasource.

O ? costuma ser datasource errado, não permissão faltando. Cada datasource aponta para um banco. O default /jdbc/AppDS é o banco FLUIG. As tabelas do RM ficam no banco TOTVSRM. Por exemplo, a tabela dbo.ZMDFLANFLUIG é do RM. Neste caso, use --jndi /jdbc/TotvsRM. O comando confere a existência do objeto com OBJECT_ID, não com o retorno do HAS_PERMS_BY_NAME.

Com --json, o envelope traz {login, database, perms[], tables[], ok}. Cada item de tables tem table, exists, grants e missing. O campo grants mapeia cada permissão para o veredicto (true concedida, false negada, null indeterminada). O campo missing lista as permissões não confirmadas, na ordem pedida. Itere missing para saber o que falta. O campo ok é true só quando todo objeto existe e toda permissão está concedida.

Quando falta qualquer permissão, ou quando um objeto não existe, o comando termina com o código 6. Neste caso, o envelope sai com ok: false.

Exit codes

código	quando
0	sucesso
2	uso incorreto (falta o SQL/tabela, flag ou --perm inválido)
4	o datasource não existe
5	o servidor recusou a consulta (erro de SQL ou consulta que não é de leitura)
6	db grants — falta uma permissão ou um objeto não existe · db query --file — parte das instruções falhou
7	fluigcliHelper ausente ou desatualizado (< 0.6.0, sem as rotas de db). Atualize com server install-helper <name> --force.