SQLX
CLI de banco de dados para agentes: 31 engines, credenciais digitadas pelo humano em uma página local e nunca enviadas ao modelo, resultados estruturados completos.
Documentação
SQLX
Conecte-se a MySQL, MariaDB, TiDB, GreatSQL, OceanBase, PostgreSQL, CockroachDB, YugabyteDB, openGauss, Oracle, SQL Server, ClickHouse, Trino, Presto, StarRocks, Apache Doris, TDengine, Dameng, KingbaseES, Apache Kylin, XuguDB, IBM Db2, IBM Informix, SUNDB, GBase 8s, Redis e MongoDB, ou abra um arquivo local SQLite, DuckDB ou H2, a partir do seu terminal ou do seu agente. As conexões são salvas criptografadas, uma invocação executa uma ou mais instruções ou comandos, e os resultados retornam completos e estruturados.
Início rápido
# 1. Install the CLI (macOS, Linux and Windows x64; Node.js 22 or newer)
npx -y @ottermind/sqlx@latest
export PATH="$HOME/.local/bin:$PATH"
# 2. Create a connection (an interactive terminal prompts for the username and password)
sqlx datasource add --name dev --type postgresql --host db.example.com --port 5432 --database app
sqlx datasource test --id dev
# 3. Run SQL
sqlx sql execute --datasource dev --command "SELECT current_database()"
Usando um agente? Veja Uso com seu agente: instale um plugin ou extensão e o agente chama o SQLX diretamente.
Instalar a CLI
Três canais, escolha um: pacotes pré-compilados de GitHub Releases, o instalador npx, ou os scripts de instalação da plataforma.
macOS e Linux
curl -fsSL https://raw.githubusercontent.com/OtterMind/sqlx/main/scripts/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
sqlx --version
sqlx init
O instalador seleciona sua plataforma, baixa o executável e verifica seu SHA-256. Ele instala em ~/.local/bin; adicione esse diretório ao PATH persistente do seu shell. SQLX_INSTALL_DIR escolhe outro diretório e SQLX_VERSION seleciona uma versão de lançamento.
Windows x64
Execute no PowerShell:
$installer = Join-Path $env:TEMP 'sqlx-install.ps1'
Invoke-WebRequest 'https://raw.githubusercontent.com/OtterMind/sqlx/main/scripts/install.ps1' -OutFile $installer
powershell -NoProfile -ExecutionPolicy Bypass -File $installer
$env:Path = "$env:LOCALAPPDATA\Programs\SQLX;$env:Path"
sqlx --version
sqlx init
Adicione %LOCALAPPDATA%\Programs\SQLX ao PATH do seu usuário para sessões futuras. Nenhum instalador sobrescreve um executável não relacionado já nomeado sqlx; use um diretório de instalação diferente nesse caso.
Os alvos pré-compilados são macOS ARM64/x64, Linux ARM64/x64 e Windows x64; a base Linux é Ubuntu 24.04. Usuários de lançamento não precisam de Rust, Java ou drivers de banco de dados: os workers de banco de dados e um JRE privado são baixados apenas quando necessário.
Node.js (npx)
macOS, Linux e Windows x64 com Node.js 22 ou mais recente:
npx -y @ottermind/sqlx@latest
export PATH="$HOME/.local/bin:$PATH"
sqlx --version
O instalador verifica o manifesto de lançamento, SHA256SUMS e o arquivo baixado antes de instalar. Ele usa o mesmo local de nível de usuário que os instaladores de plataforma e instala a Skill em ./sqlx; --target codex, --target claude, --target dsh, --target pi ou --target <directory> colocam a Skill em outro lugar. Node.js é necessário apenas pelo instalador, nunca pela CLI.
Atualizações
A CLI atualiza seu próprio executável:
sqlx update check # report the latest stable version without installing it
sqlx update install # download, verify and replace the executable
sqlx update status # read local history without network access
sqlx update install --version <version> instala uma versão estável exata. As atualizações não interrompem SQL em execução ou o serviço de UI, não modificam conexões salvas e não atualizam Skills ou plugins automaticamente; use sqlx skill update para Skills gerenciadas, e um plugin de UI instalado mantém a versão que você selecionou (a interface padrão acompanha o lançamento da CLI).
O uso interativo verifica em segundo plano no máximo uma vez por dia e apenas imprime um aviso no stderr. Comandos via pipe e CI pulam essa verificação, e SQLX_NO_UPDATE_CHECK=1 a desativa. Builds de fonte e caminhos gerenciados por gerenciadores de pacotes mantêm seu próprio método de instalação.
Uso com seu agente
Todos os quatro estão prontos assim que são instalados: o plugin ou extensão instala a CLI sqlx
ela mesma quando está ausente, então você nunca a instala separadamente. Codex e Claude adicionalmente
exigem que a CLI atenda à versão mínima do plugin e se recusam a iniciar um servidor MCP
incompatível mais antigo silenciosamente.
Codex
codex plugin marketplace add OtterMind/sqlx@plugins
codex plugin add sqlx@ottermind
O plugin inicia sqlx mcp via MCP. Operações somente leitura são executadas diretamente; as duas ferramentas de execução (sqlx_sql_execute e sqlx_sql_view) são marcadas como destrutivas e o Codex pede aprovação por padrão.
Claude Code
claude plugin marketplace add OtterMind/sqlx@plugins
claude plugin install sqlx@ottermind
Execuções headless precisam de uma lista explícita de ferramentas permitidas:
claude --allowedTools "mcp__plugin_sqlx_sqlx__*" -p "List my SQLX datasources"
DeepSeek Harness
dsh plugin --profile web add @ottermind/sqlx-dsh # browser UI
dsh plugin --profile tui add @ottermind/sqlx-dsh # terminal UI
Plugins pertencem a um perfil: instale-o no perfil que você usa e reinicie o dsh.
Pi
pi install npm:@ottermind/sqlx-pi
Somente Skill
sqlx skill install --target codex # Codex and dsh share ~/.agents/skills
sqlx skill install --target claude
sqlx skill install --target dsh
sqlx skill install --target pi
sqlx skill status # list managed installations
sqlx skill update # update them, keeping local edits
Para outro agente, passe o diretório de skill dele com sqlx skill install --path <directory>.
Conexões e SQL
Criar uma conexão
sqlx datasource add --name dev --type postgresql --host db.example.com --port 5432 --database app
sqlx datasource test --id dev
sqlx sql execute --datasource dev --command "SELECT current_database()" --command "SELECT 1"
| Banco de dados | Valores de --type | Execução | Valores obrigatórios e padrões |
|---|---|---|---|
| MySQL | mysql | worker nativo | porta 3306 por padrão |
| MariaDB | mariadb | reutiliza o worker MySQL | porta 3306 por padrão |
| TiDB | tidb | reutiliza o worker MySQL | porta 4000 por padrão |
| GreatSQL | greatsql | reutiliza o worker MySQL | porta 3306 por padrão |
| OceanBase | oceanbase, ob | reutiliza o worker MySQL | porta 2881 por padrão; conecte como user@tenant |
| StarRocks | starrocks | reutiliza o worker MySQL | porta 9030 por padrão; não tem banco de dados de usuário até que um seja criado |
| Apache Doris | doris | reutiliza o worker MySQL | porta 9030 por padrão; não tem banco de dados de usuário até que um seja criado |
| PostgreSQL | postgresql, postgres, pgsql | worker nativo | porta 5432 por padrão |
| CockroachDB | cockroachdb, cockroach, crdb | reutiliza o worker PostgreSQL | |
| YugabyteDB | yugabytedb, yugabyte, yb | reutiliza o worker PostgreSQL | porta 5433 por padrão |
| openGauss | opengauss, gaussdb | worker JDBC | porta 5432 por padrão; autentica com seu próprio driver |
| Oracle | oracle | worker JDBC | --service <service-name> é obrigatório |
| SQL Server | sqlserver, mssql | worker JDBC | porta 1433 por padrão |
| ClickHouse | clickhouse | worker JDBC | conecta à porta HTTP, 8123 por padrão |
| Trino | trino | worker JDBC | --database <catalog>[.<schema>] é obrigatório |
| TDengine | tdengine, taos | worker JDBC | conecta via taosAdapter, 6041 por padrão |
| Dameng | dameng, dm | worker JDBC | porta 5236 por padrão; a conta também é o schema padrão |
| KingbaseES | kingbase, kingbasees | worker JDBC | porta 54321 por padrão |
| Redis | redis | worker nativo | porta 6379 por padrão; cada --command é um comando Redis, não SQL |
| MongoDB | mongodb, mongo | worker nativo | porta 27017 por padrão; cada --command é um documento de comando, não SQL |
| SQLite | sqlite, sqlite3 | worker nativo | --path <file> (ou --database) abre ou cria um arquivo local; sem host, porta ou credenciais; --property mode=ro e --property busy_timeout=<ms> |
| DuckDB | duckdb | worker nativo | --path <file> abre ou cria um arquivo local, :memory: mantém um para a invocação; --property read_only=true e --property threads=<n> |
| H2 | h2 | worker JDBC | --path <file> abre um arquivo local, ou --host e --port (9092 por padrão) alcançam um servidor TCP |
| Presto | presto, prestodb | worker JDBC | porta 8080 por padrão; --database <catalog>[.<schema>] é obrigatório; --username é obrigatório e uma senha só é enviada via TLS |
| Hive | hive | worker JDBC | porta 10000 por padrão; --database seleciona o banco de dados Hive, default quando não definido |
| Apache Kylin | kylin | worker JDBC | porta 7070 por padrão; --database carrega o projeto Kylin, e a conta padrão é ADMIN/KYLIN |
| XuguDB | xugu, xugudb | worker JDBC | porta 5138 por padrão; SYSTEM é o banco de dados do sistema |
| IBM Db2 | db2, ibmdb2 | worker JDBC | porta 50000 por padrão; precisa de um driver que você fornece, veja Drivers que você fornece |
| IBM Informix | informix, ifx | worker JDBC | porta 9088 por padrão; --service <server-instance> é obrigatório e o driver deve ser fornecido |
| SUNDB | sundb | worker JDBC | porta 22581 por padrão; executa o mecanismo Goldilocks e precisa do driver da imagem do fornecedor |
| GBase 8s | gbase8s, gbasedbt | worker JDBC | porta 9088 por padrão; --service <server-instance> é obrigatório e o driver deve ser fornecido |
--id e --datasource aceitam um UUID de datasource estável ou seu nome único.
Para permitir que o usuário digite a senha em uma página local, para que ela nunca entre na conversa ou em uma resposta de ferramenta:
sqlx datasource add --ui --name dev --type postgresql --host db.example.com --port 5432 --database app
sqlx datasource setup-status --request-id <request-id>
Para editar uma conexão existente e manter sua senha salva, a menos que você a substitua: sqlx datasource update --id dev --ui.
Conexões não usam TLS a menos que você peça: --tls padrão é disable. Adicione --tls verify-full para verificar o certificado do banco de dados; um banco de dados que não serve nenhum certificado que sua máquina confie então falha com invalid peer certificate: UnknownIssuer (MySQL), error performing TLS handshake (PostgreSQL) ou uma conexão fechada (Oracle), que é o caso usual para um contêiner local. Qualquer escolha também está disponível como uma atualização:
sqlx datasource add --name dev --type mysql --host 127.0.0.1 --port 3306 --database app \
--username-env DB_USER --password-env DB_PASSWORD # no TLS, the default
sqlx datasource update --id dev --tls verify-full # verify the server certificate
Credenciais
Credenciais vêm de variáveis de ambiente nomeadas, prompts interativos ocultos, ou um objeto JSON de conexão no stdin. Nunca coloque uma senha literal em um argumento de comando.
sqlx datasource add --name dev --connection-stdin
{
"database_type": "postgresql",
"host": "localhost",
"port": 5432,
"database": "app",
"service": "",
"username": "example_account",
"password": "replace_with_real_input",
"tls": "disable",
"properties": {}
}
Respostas de datasource omitem nomes de usuário, senhas e propriedades do fornecedor.
Importando conexões
Uma ferramenta que já armazena conexões pode entregar todas elas em um único documento versionado, então uma migração nunca precisa de uma senha em um argumento de comando. examples/import-connections.json é um ponto de partida executável:
sqlx datasource import --stdin < connections.json
{
"version": 1,
"mode": "merge",
"datasources": [
{
"name": "dev",
"connection": {
"database_type": "postgresql",
"host": "localhost",
"port": 5432,
"database": "app",
"username": "example_account",
"password": "replace_with_real_input",
"tls": "disable"
}
}
]
}
Cada connection é o mesmo objeto que --connection-stdin aceita. merge (o padrão) adiciona novos nomes e atualiza os existentes no lugar, mantendo seus IDs, e nunca exclui uma conexão armazenada. Cada entrada é validada individualmente, então um mecanismo não suportado ou uma conexão incompleta é relatado em skipped com seu motivo em vez de falhar o documento:
{"success":true,"data":{"mode":"merge","added":1,"updated":0,"unchanged":0,"total":1,"datasources":[{"id":"...","name":"dev","connection":{"database_type":"postgresql"}}],"skipped":[{"name":"legacy","reason":"invalid_connection","detail":"..."}]}}
--dry-run valida e relata sem armazenar nada, --strict recusa o documento inteiro quando qualquer entrada é inválida, e --file <path> lê o documento de um arquivo para chamadores que não podem usar pipe no stdin. O armazenamento é gravado uma vez, então uma importação nunca é aplicada pela metade.
total conta cada conexão que a importação considerou: as conexões já armazenadas mais as entradas do documento, incluindo as que foram puladas. Com uma conexão armazenada e duas entradas, uma delas inválida, a resposta relata total: 3, added: 1 e uma entrada skipped.
Comandos
| Operação | Comando |
|---|---|
| Inicializar armazenamento local | sqlx init |
| Criar uma conexão | sqlx datasource add --name dev --type mysql --host localhost --database app --username-env DB_USER --password-env DB_PASSWORD |
| Listar conexões | sqlx datasource list |
| Inspecionar uma conexão | sqlx datasource show --id dev |
| Alterar configurações da conexão | sqlx datasource update --id dev --host db.example.com |
| Importar conexões salvas | sqlx datasource import --stdin |
| Remover uma conexão salva | sqlx datasource remove --id dev |
| Testar conectividade | sqlx datasource test --id dev |
| Executar SQL | sqlx sql execute --datasource dev --command "SELECT 1" --command "SELECT 2" |
| Baixar workers, o runtime JDBC e a interface antecipadamente | sqlx prefetch mysql ui (mariadb, tidb, greatsql, oceanbase, starrocks, doris, postgres, cockroachdb, yugabytedb, opengauss, oracle, sqlserver, clickhouse, trino, presto, hive, kylin, xugu, db2, informix, sundb, gbase8s, tdengine, dameng, kingbase, redis, mongodb, sqlite, duckdb, h2, skill ou all; os quatro mecanismos cujo driver você fornece buscam apenas o runtime compartilhado) |
| Instalar um driver que a versão não pode distribuir | sqlx driver add --type db2 --jar <path>, sqlx driver list, sqlx driver remove --type db2 |
| Executar e abrir uma página de resultados | sqlx sql execute --datasource dev --command "SELECT 1" --view |
| Ler um resultado armazenado | sqlx results list, sqlx results rows --id <result-id> --offset 100 --limit 50 |
| Mostrar ou alterar configurações | sqlx setting list, sqlx setting set preview-rows 20, sqlx setting set results-dir ~/sqlx-results |
| Retornar um resultado grande inline | sqlx sql execute --datasource dev --command "SELECT …" --full |
| Workbench local | sqlx ui, sqlx ui status, sqlx ui stop |
| Criar um gráfico e colocá-lo em um painel | sqlx analytics chart add --name revenue --datasource dev --command "SELECT month, SUM(revenue) AS revenue FROM sales GROUP BY month" --type line --x month --y revenue --run --dashboard "Sales" (como em qualquer outro lugar, --sql é aceito como um alias) |
| Executar novamente o SQL de um gráfico salvo | sqlx analytics chart run revenue |
| Listar ou excluir gráficos e painéis | sqlx analytics list, sqlx analytics dashboard add --name "Sales", sqlx analytics remove chart revenue |
| Servir MCP via stdio | sqlx mcp |
| Instalar a Skill | sqlx skill install --target codex, --target claude, --target dsh ou --target pi |
| Instalar em outro diretório de skills | sqlx skill install --path /path/to/skills/sqlx |
| Inspecionar e atualizar Skills gerenciadas | sqlx skill status, sqlx skill update |
| Parar de gerenciar uma instalação de Skill | sqlx skill remove --path /path/to/skills/sqlx (os arquivos são mantidos) |
| Ajuda e versão | sqlx --help, sqlx --version |
Comportamento de execução
Cada invocação possui uma conexão de banco de dados. Argumentos --command repetidos executam em ordem, inicialmente com autocommit, e param no primeiro erro; não há transação implícita de tudo-ou-nada. Tabelas temporárias e variáveis de sessão não sobrevivem a outra invocação. Não envie diretivas de cliente como GO, DELIMITER ou comandos de barra invertida do psql.
--command é o sinalizador atual e --sql ainda é aceito como um alias.
A saída é um objeto JSON com um item por instrução executada: results[].stmt identifica a instrução, cols lista as colunas como pares [name, type] (base64, boolean e json se juntam como uma terceira entrada quando os valores não são texto simples), rows contém valores posicionais e count contém a contagem de linhas do driver. Rótulos duplicados permanecem distintos. Números são codificados como strings para preservar a precisão inteira e decimal, e dados binários usam Base64. Uma instrução com falha carrega seu próprio error com um outcome; instruções que nunca foram executadas são listadas em skipped; o objeto termina com success, que também é o status de saída do processo.
Apenas uma prévia viaja pela saída padrão. Um conjunto de resultados com mais linhas do que preview-rows (10 por padrão) ou mais de 16 KiB de valores é gravado completamente em results/<id>/<statement>-<result>.jsonl dentro do diretório de resultados, e seu item carrega um caminho file mais o id do objeto. Leia mais linhas desse arquivo ou pagine-as com sqlx results rows --id <id> --offset 100. O diretório de resultados padrão é um diretório privado dentro do diretório temporário do sistema, então os resultados desaparecem quando a máquina reinicia; sqlx setting set results-dir ~/sqlx-results os mantém, e sqlx setting set results-retention-hours 0 interrompe a limpeza de 24 horas.
Um chamador que não pode ler arquivos precisa do resultado inteiro em uma resposta: --full imprime cada linha e não armazena nada, sqlx setting set result-mode full torna isso o padrão para esta máquina, e a ferramenta MCP sqlx_sql_execute aceita "full": true para uma chamada. Um resultado grande então preenche o próprio orçamento de saída do chamador, que é o motivo pelo qual a prévia é o padrão.
--events imprime o fluxo bruto de eventos do worker (protocol_version, datasource_id, events, success) para scripts que o analisam, e nunca armazena nada. --preview <rows> substitui o tamanho da prévia para uma chamada.
Verifique o sinalizador final success e o status de saída, e nunca reproduza automaticamente uma gravação incerta.
Páginas locais
Deixe o usuário inspecionar resultados em um navegador e inserir a senha lá.
sqlx sql execute --datasource dev --command "SELECT id, name FROM users ORDER BY id" --view
SQLX executa uma vez e retorna uma URL local. A página carrega os resultados automaticamente, suporta múltiplos conjuntos de resultados e paginação, e preserva valores exatos. Recarregar, paginar ou reabrir a página lê o resultado em cache; Atualizar na página reexecuta o lote SQL original contra o banco de dados, então qualquer gravação nesse lote é executada novamente. Uma atualização bem-sucedida substitui o instantâneo exibido na mesma URL; uma falha mantém o resultado anterior e não reverte alterações no banco de dados. Os resultados são retidos localmente por 24 horas.
sqlx ui abre o workbench local, sqlx ui status e sqlx ui stop inspecionam ou param o serviço, e --no-open retorna um link sem abrir um navegador. O workbench também renderiza os gráficos e painéis criados com sqlx analytics (veja Analytics local); esse comando não precisa de serviço em execução. As páginas são acessíveis apenas na máquina que executa SQLX, carregam uma sessão de navegador HttpOnly automaticamente, e o serviço permanece ativo até sqlx ui stop.
Digitar a senha na página mantém as credenciais fora da conversa, mas não as isola de um agente que pode ler arquivos ou controlar o navegador como o mesmo usuário do sistema operacional. Veja o design da UI local para a interface e os limites de armazenamento.
Escolha sua UI
sqlx ui plugin install --url <plugin-zip-url> --sha256 <published-sha256>
sqlx ui plugin list
sqlx ui plugin use <plugin-id> # default restores the default interface
sqlx ui plugin remove <plugin-id> --version <version>
Instalar não ativa um plugin; após selecioná-lo, recarregue uma página aberta ou execute sqlx ui. Atualizações de CLI mantêm a versão de um plugin que você instalou e movem a interface padrão para a versão da release, e alternar versões precisa de sqlx ui stop primeiro. Plugins executam localmente e podem acessar credenciais inseridas e dados exibidos, então instale interfaces de autores em quem você confia: um checksum prova que os bytes baixados estão intactos, não que o autor é confiável.
Para construir sua própria interface, veja o guia de plugins de UI, o SDK de navegador tipado e o exemplo independente de UI de terminal. Os usuários não precisam de runtime Node.js.
Dados e downloads
Os dados do usuário vivem em ~/.sqlx/; use --data-dir ou SQLX_DATA_DIR para outro local. As configurações são armazenadas em ~/.sqlx/settings.json e gerenciadas com sqlx setting list|get|set|unset; SQLX_PREVIEW_ROWS, SQLX_RESULTS_DIR, SQLX_RESULTS_RETENTION_HOURS e SQLX_RESULT_MODE substituem o arquivo para um ambiente, e um sinalizador de linha de comando substitui ambos. Resultados armazenados vivem no diretório de resultados descrito acima, mantêm 24 horas por padrão e ficam abaixo de 1 GiB no total; resultados mais antigos são removidos antes do próximo comando ser executado, e resultados de página de --view são gerenciados pelo serviço local. Conexões salvas usam AES-256-GCM com uma chave local gerada independentemente: faça backup da chave junto com os dados criptografados, porque perder a chave impede a descriptografia. A identidade do dispositivo é gerada localmente e esta versão não envia informações do dispositivo.
O executável principal não contém drivers de banco de dados; o worker de cada banco é baixado no primeiro uso. MySQL, MariaDB, TiDB, GreatSQL, OceanBase, StarRocks e Apache Doris compartilham o worker MySQL, Redis, MongoDB, SQLite e DuckDB executam em seus próprios workers nativos, PostgreSQL, CockroachDB e YugabyteDB compartilham o worker PostgreSQL, e Oracle, SQL Server, ClickHouse, Trino, Presto, TDengine, openGauss, Dameng, KingbaseES, H2, Hive, Apache Kylin, XuguDB, IBM Db2, IBM Informix, SUNDB e GBase 8s usam o worker JDBC (a tabela de bancos de dados lista qual worker atende qual banco). Recursos baixados vêm do manifesto de release fixo da versão CLI em execução e são verificados antes do uso; --manifest <https-url> seleciona outro manifesto ou um servidor de teste local.
Os downloads acontecem no primeiro uso e são armazenados em cache depois. Cada um imprime Downloading … com velocidade e tempo estimado, e uma linha final Downloaded … in 12.3s (390 KB/s) no stderr; a linha de progresso é atualizada apenas quando o stderr é um terminal, então JSON canalizado permanece limpo. Uma transferência interrompida é tentada novamente até três vezes, e reexecutar um comando com falha reutiliza cada componente já instalado. Para evitar esperar dentro da primeira consulta ou página:
sqlx prefetch mysql ui # MySQL worker and the local browser UI
sqlx prefetch all # adds the PostgreSQL, CockroachDB, YugabyteDB, openGauss, MariaDB, TiDB, GreatSQL, OceanBase, StarRocks, Doris, Oracle, SQL Server, ClickHouse, Trino, Presto, Hive, Kylin, XuguDB, TDengine, Dameng, KingbaseES, Redis, MongoDB, SQLite, DuckDB and H2 components, the JDBC runtime and the JRE
As referências de banco de dados explicam o propósito, parâmetros, resultado e link de documentação oficial de cada operação SQL.
Solução de problemas
| Sintoma | O que fazer |
|---|---|
invalid peer certificate: UnknownIssuer, error performing TLS handshake | A conexão pede verificação TLS e o banco de dados não fornece um certificado que sua máquina confie (comum em contêineres locais); remova --tls verify-full (o padrão é disable) |
sqlx: command not found | O diretório de instalação está ausente do PATH: ~/.local/bin (macOS, Linux) ou %LOCALAPPDATA%\Programs\SQLX (Windows) |
| A primeira consulta parece travada no download | Execute sqlx prefetch <component> primeiro; após uma interrupção, reexecutar reutiliza componentes instalados |
| Alternar a versão do plugin de UI falha | Execute sqlx ui stop primeiro, depois sqlx ui plugin remove |
| Uma atualização falha | Verifique sqlx update status; reexecute o instalador se necessário, conexões salvas não são afetadas |
| Oracle ou SQL Server relata um erro relacionado a JDBC | Reexecute com SQLX_JDBC_DEBUG=1 para ver os diagnósticos do próprio driver |
Compilar a partir do código-fonte
O desenvolvimento do código-fonte requer Git, Rust 1.95, Node.js 22 e as ferramentas de build nativas da plataforma; Node.js apenas compila os ativos de plugins de UI. Para desenvolvimento com Oracle ou SQL Server, instale também um JDK Java 17 e Maven.
No macOS ou Linux:
git clone https://github.com/OtterMind/sqlx.git
cd sqlx
npm --prefix ui ci
npm --prefix ui run build
cargo build --workspace --release --locked
export PATH="$PWD/target/release:$PATH"
export SQLX_WORKER_DIR="$PWD/target/release"
sqlx --version
sqlx init
sqlx ui plugin install --path ui/dist
sqlx ui plugin use default
No Windows PowerShell:
git clone https://github.com/OtterMind/sqlx.git
Set-Location sqlx
npm --prefix ui ci
npm --prefix ui run build
cargo build --workspace --release --locked
$env:Path = "$PWD\target\release;$env:Path"
$env:SQLX_WORKER_DIR = "$PWD\target\release"
sqlx --version
sqlx init
sqlx ui plugin install --path ui/dist
sqlx ui plugin use default
Mantenha o checkout nesse local, ou copie o CLI e ambos os workers nativos para um diretório dedicado e atualize PATH e SQLX_WORKER_DIR de acordo. Este build de código-fonte torna MySQL e PostgreSQL utilizáveis sem um manifesto de worker publicado.
Para Oracle e SQL Server, compile o worker JDBC e coloque seus JARs de driver ao lado desses workers. No macOS ou Linux:
mvn -B -f java/jdbc/pom.xml package
cp java/jdbc/target/sqlx-jdbc-0.1.20.jar target/release/sqlx-jdbc.jar
curl -fL https://repo.maven.apache.org/maven2/com/oracle/database/jdbc/ojdbc11/23.6.0.24.10/ojdbc11-23.6.0.24.10.jar -o target/release/ojdbc.jar
curl -fL https://repo.maven.apache.org/maven2/com/microsoft/sqlserver/mssql-jdbc/12.10.1.jre11/mssql-jdbc-12.10.1.jre11.jar -o target/release/mssql-jdbc.jar
No Windows PowerShell:
mvn -B -f java/jdbc/pom.xml package
Copy-Item java/jdbc/target/sqlx-jdbc-0.1.20.jar target/release/sqlx-jdbc.jar
Invoke-WebRequest 'https://repo.maven.apache.org/maven2/com/oracle/database/jdbc/ojdbc11/23.6.0.24.10/ojdbc11-23.6.0.24.10.jar' -OutFile target/release/ojdbc.jar
Invoke-WebRequest 'https://repo.maven.apache.org/maven2/com/microsoft/sqlserver/mssql-jdbc/12.10.1.jre11/mssql-jdbc-12.10.1.jre11.jar' -OutFile target/release/mssql-jdbc.jar
Java 17 deve estar no PATH, ou SQLX_JAVA_BIN pode apontar para seu executável. Essas dependências manuais são necessárias apenas para desenvolvimento de código-fonte; uma release binária baixa seu runtime Java privado e drivers automaticamente.
Desenvolvimento e validação
npm --prefix ui ci
npm --prefix ui run build
cargo build --workspace --locked
cargo test --workspace --locked
cargo clippy --workspace --all-targets --locked -- -D warnings
mvn -B -f java/jdbc/pom.xml verify
python3 tests/distribution.py
python3 tests/ui_lifecycle.py
python3 tests/ui_distribution.py
python3 tests/ui_plugins.py
python3 tests/updates.py
docker compose -f tests/compose.yaml up -d --wait mysql postgres
python3 tests/integration.py
python3 tests/ui_api.py
docker compose -f tests/compose.yaml down -v
# one group at a time; StarRocks and Doris each need a frontend and a backend
docker compose -f tests/compose.yaml up -d --wait tidb yugabytedb
python3 tests/databases.py tidb yugabytedb
docker compose -f tests/compose.yaml down -v
docker compose -f tests/compose.yaml up -d --wait starrocks
python3 tests/databases.py starrocks
docker compose -f tests/compose.yaml down -v
docker compose -f tests/compose.yaml up -d --wait doris
python3 tests/databases.py doris
docker compose -f tests/compose.yaml down -v
docker compose -f tests/compose.yaml up -d --wait greatsql tdengine
python3 tests/databases.py greatsql tdengine
docker compose -f tests/compose.yaml down -v
# Dameng and KingbaseES have no public image; point the fixtures at a local instance
# and export SQLX_TEST_DAMENG_PASSWORD or SQLX_TEST_KINGBASE_PASSWORD when they differ
python3 tests/databases.py dameng kingbase
docker compose -f tests/compose.yaml up -d --wait presto hive
bash scripts/jdbc-fixture.sh presto
bash scripts/jdbc-fixture.sh hive
python3 tests/databases.py presto hive
docker compose -f tests/compose.yaml down -v
# Kylin, XuguDB, Db2 and Informix take turns because each needs several gigabytes
docker compose -f tests/compose.yaml up -d --wait kylin
bash scripts/jdbc-fixture.sh kylin
python3 tests/databases.py kylin
docker compose -f tests/compose.yaml down -v
# GBase 8s takes the vendor driver and its own instance; SUNDB needs a licensed installation
# and XuguDB a trial image whose password is known. tests/databases.py lists every variable.
export SQLX_TEST_GBASE8S_DRIVER=~/gbasedbt-jdbc.jar
python3 tests/databases.py gbase8s
Para workers nativos locais, defina SQLX_WORKER_DIR para o diretório absoluto target/debug. Para desenvolvimento JDBC, esse diretório também contém sqlx-jdbc.jar e ojdbc.jar ou mssql-jdbc.jar; SQLX_JAVA_BIN pode selecionar Java 17 explicitamente. Essas substituições são para desenvolvimento, não pré-requisitos para usuários de release. Os scripts de fixture usam contêineres de teste dedicados e credenciais apenas de teste.
Drivers que você fornece
A maioria dos drivers JDBC acompanha a release e é baixada no primeiro uso. Fornecedores que não permitem que seu driver seja redistribuído não são empacotados: IBM Db2, IBM Informix, SUNDB e GBase 8s conectam com um driver que você instala uma vez do fornecedor.
sqlx driver add --type db2 --jar ~/Downloads/jcc-12.1.0.0.jar
sqlx driver list
sqlx driver remove --type db2
sqlx driver add copia o jar para <data-dir>/drivers/<engine>/, verifica se ele realmente contém a
classe de driver do mecanismo, e cada comando posterior o carrega a partir daí. Um jar que você fornece também tem precedência sobre um
componente publicado, que é como um driver de fornecedor mais novo é usado antes que o release o alcance. Executar uma
instrução para um desses mecanismos sem um driver explica o comando exato a ser executado:
sqlx sql execute --datasource <id> --command "SELECT 1 FROM SYSIBM.SYSDUMMY1"
# SQLX does not redistribute the db2 driver; run `sqlx driver add --type db2 --jar <path>` with the vendor driver jar first
scripts/release-driver-check.sh <engine> <jar> <data-dir> <connection-json> <statement> executa o mesmo
caminho que um usuário de release percorre — instale o jar, depois execute sem overrides de desenvolvimento, para que a CLI
resolva o JRE e o runner JDBC a partir do manifesto publicado. Ele precisa de um release cujo runner JDBC
já conheça o mecanismo, então execute-o contra uma versão publicada em vez de a partir de um branch de feature.
De onde vêm os drivers:
| Mecanismo | Arquivo a fornecer | Classe de driver |
|---|---|---|
| IBM Db2 | jcc-<version>.jar da IBM ou Maven Central (com.ibm.db2:jcc) | com.ibm.db2.jcc.DB2Driver |
| IBM Informix | o driver JDBC Informix, linha 4.50 (com.ibm.informix:jdbc); a linha 15.x falha contra um servidor Informix 14.10 | com.informix.jdbc.IfxDriver |
| SUNDB | goldilocks8.jar da imagem do fornecedor em /goldilocks_home/lib/ | sunje.goldilocks.jdbc.GoldilocksDriver |
| GBase 8s | o ifxjdbc.jar do fornecedor; um jar wrapper que o contém deve ser descompactado primeiro | com.gbasedbt.jdbc.IfxDriver |
Releases e documentação
- Pacotes e checksums: GitHub Releases
- Notas de release: docs/release-notes.md
- Limites de design e implementação: docs/design.md
- Comportamento de atualização e recuperação: docs/updates.md
- Interface local e plugins: docs/local-ui.md, docs/ui-plugins.md
- Integrações de agentes: integrations/README.md, Skill
Não incluídos: entrada de arquivos SQL, sessões persistentes, modos de transação e erro configuráveis, exportação de arquivos de resultado, instalação de atualização não assistida e telemetria.
Licença
Este repositório público de código-fonte mantém a licença Chat2DB modificada para código adaptado. Não é a licença Apache 2.0 não modificada. Consulte LICENSE e NOTICE; dependências de terceiros mantêm suas próprias licenças.