dsh-sql

dsh-sql é um plugin de banco de dados para DSH (DeepSeek Harness) que permite ao agente conectar-se e operar bancos de dados. Ele fornece seis ferramentas, cobrindo gerenciamento de conexões, consultas somente leitura, operações de escrita, exploração de esquemas, visão geral de estatísticas e autoverificação de integridade. Visão geral das ferramentas: - sql_list: lista as conexões configuradas e testa a conectividade. - sql_query: consultas somente leitura, suporta SELECT/PRAGMA/EXPLAIN/SHOW/DESCRIBE/WITH, usa lista de permissões de palavras-chave e rejeita múltiplas declarações. - sql_exec: operações de escrita e DDL, pode executar scripts de múltiplas declarações, sujeito ao interruptor readOnly e ao portão de aprovação. - sql_schema: lista as tabelas ou exibe a estrutura de uma tabela específica; os nomes das tabelas passam por validação na lista de permissões de identificadores. - sql_stats: fornece uma visão geral do número de tabelas, linhas e tamanho do banco de dados; as falhas de consulta ficam isoladas entre si. - sql_health: verifica a atividade conexão por conexão e inspeciona a configuração de segurança, sem exibir senhas. Motores e conexões: SQLite usa node:sqlite integrado ao Node 22.13+, sem dependências; MySQL usa o pool de conexões mysql2; PostgreSQL usa o pool de conexões pg. A configuração pode declarar várias conexões nomeadas, especificando o motor e os parâmetros de conexão de cada uma. Se nenhuma configuração for fornecida, uma conexão SQLite :memory: é criada por padrão; no entanto, se houver configuração e o formato for inválido, a carga falhará com erro explícito, sem reverter silenciosamente para o banco em memória. Design de segurança: - Proteção somente leitura em nível léxico: sql_query remove strings e comentários antes de validar; rejeita CTEs de modificação de dados (WITH…DELETE/UPDATE), SELECT INTO, FOR UPDATE/FOR SHARE, atribuições de PRAGMA e múltiplas declarações. - Portão de aprovação de escrita: sql_exec solicita aprovação por padrão; em ambientes headless, sem canal de aprovação, a execução é recusada. - Modo readOnly: pode desabilitar totalmente as operações de escrita, adequado para bancos de produção. - Limitação de linhas em streaming: os eventos de linha do iterador SQLite, do modo Readable do MySQL e da Query do PostgreSQL coletam no máximo maxRows+1 linhas; se exceder, a marcação truncated é aplicada. Quando o limite é atingido no MySQL e no PostgreSQL, a conexão dedicada dessa consulta é encerrada; caso contrário, a conexão retorna ao pool, evitando que todos os resultados fiquem residentes em memória. - Execução cancelável: consultas e operações de escrita obedecem ao exec.signal do Harness; ao cancelar, o wait é interrompido e as conexões dedicadas MySQL/PostgreSQL em uso são destruídas. - Big integers sem perda: bigint é emitido como number dentro do intervalo de inteiros seguros do JavaScript; fora do intervalo, é emitido como string decimal, evitando perda silenciosa de precisão. - Validação de identificadores: nomes de tabelas permitem apenas letras, números e sublinhados, prevenindo injeção de esquema. - Segredos fora da configuração: as senhas podem ser fornecidas por meio da variável de ambiente DSH_SQL_PASSWORD_ + nome da conexão. Os itens de configuração incluem maxRows (limite máximo de linhas retornadas por consulta, 1-10000), queryTimeoutMs (timeout por consulta, padrão de 60 segundos), execTimeoutMs (timeout por operação de escrita, padrão de 120 segundos), readOnly e writeApproval. Para instalar, use dsh plugin --profile web add dsh-sql; após desinstalar, é necessário reiniciar o serviço Web. O projeto é licenciado sob MIT; no desenvolvimento, use pnpm install e pnpm test (compilação com suíte de testes completa, incluindo integração real com SQLite). O README indica que foi validado no @deepseek-ai/dsh@0.1.5-rc.1 oficial e no Node 24.16.0, usando o modelo de pacote combinado cordis.patch.yml e dsh.bundle.patch.