SQLX
CLI de base de datos para agentes: 31 motores, credenciales escritas por el humano en una página local y nunca enviadas al modelo, resultados estructurados completos.
Documentación
SQLX
Conéctate 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 y MongoDB, o abre un archivo local de SQLite, DuckDB o H2, desde tu terminal o desde tu agente. Las conexiones se guardan cifradas, una invocación ejecuta una o más sentencias o comandos, y los resultados vuelven completos y estructurados.
Inicio 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()"
¿Usas un agente? Consulta Uso con tu agente: instala un plugin o extensión y el agente llama a SQLX directamente.
Instalar la CLI
Tres canales, elige uno: paquetes precompilados de GitHub Releases, el instalador npx, o los scripts de instalación por plataforma.
macOS y Linux
curl -fsSL https://raw.githubusercontent.com/OtterMind/sqlx/main/scripts/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
sqlx --version
sqlx init
El instalador selecciona tu plataforma, descarga el ejecutable y verifica su SHA-256. Instala en ~/.local/bin; añade ese directorio al PATH persistente de tu shell. SQLX_INSTALL_DIR elige otro directorio y SQLX_VERSION selecciona una versión de lanzamiento.
Windows x64
Ejecuta en 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
Añade %LOCALAPPDATA%\Programs\SQLX a tu PATH de usuario para futuras sesiones. Ningún instalador sobrescribe un ejecutable no relacionado que ya se llame sqlx; usa un directorio de instalación diferente en ese caso.
Los objetivos precompilados son macOS ARM64/x64, Linux ARM64/x64 y Windows x64; la base de Linux es Ubuntu 24.04. Los usuarios de versiones de lanzamiento no necesitan Rust, Java ni controladores de base de datos: los trabajadores de base de datos y un JRE privado se descargan solo cuando se necesitan.
Node.js (npx)
macOS, Linux y Windows x64 con Node.js 22 o más reciente:
npx -y @ottermind/sqlx@latest
export PATH="$HOME/.local/bin:$PATH"
sqlx --version
El instalador verifica el manifiesto de lanzamiento, SHA256SUMS y el archivo descargado antes de instalar. Usa la misma ubicación a nivel de usuario que los instaladores de plataforma e instala la Skill en ./sqlx; --target codex, --target claude, --target dsh, --target pi o --target <directory> colocan la Skill en otro lugar. Node.js solo lo necesita el instalador, nunca la CLI.
Actualizaciones
La CLI actualiza su propio ejecutable:
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 una versión estable exacta. Las actualizaciones no detienen SQL en ejecución ni el servicio de interfaz, no modifican las conexiones guardadas y no actualizan Skills ni plugins automáticamente; usa sqlx skill update para Skills gestionadas, y un plugin de interfaz instalado mantiene la versión que seleccionaste (la interfaz predeterminada se mueve con el lanzamiento de la CLI).
El uso interactivo comprueba en segundo plano como máximo una vez al día y solo imprime un aviso en stderr. Los comandos canalizados y de CI omiten esa comprobación, y SQLX_NO_UPDATE_CHECK=1 la desactiva. Las compilaciones desde fuente y las rutas gestionadas por gestores de paquetes mantienen su propio método de instalación.
Uso con tu agente
Los cuatro están listos en cuanto se instalan: el plugin o extensión instala la CLI sqlx
ella misma si falta, así que nunca la instalas por separado. Codex y Claude además
requieren que la CLI cumpla la versión mínima del plugin y se niegan a iniciar un servidor MCP
incompatible más antiguo en silencio.
Codex
codex plugin marketplace add OtterMind/sqlx@plugins
codex plugin add sqlx@ottermind
El plugin inicia sqlx mcp a través de MCP. Las operaciones de solo lectura se ejecutan directamente; las dos herramientas de ejecución (sqlx_sql_execute y sqlx_sql_view) están marcadas como destructivas y Codex pide aprobación por defecto.
Claude Code
claude plugin marketplace add OtterMind/sqlx@plugins
claude plugin install sqlx@ottermind
Las ejecuciones sin interfaz necesitan una lista explícita de herramientas 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
Los plugins pertenecen a un perfil: instálalo en el perfil que uses y reinicia dsh.
Pi
pi install npm:@ottermind/sqlx-pi
Solo 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 otro agente, pasa su directorio de skills con sqlx skill install --path <directory>.
Conexiones y SQL
Crear una conexión
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"
| Base de datos | Valores de --type | Ejecución | Valores requeridos y predeterminados |
|---|---|---|---|
| MySQL | mysql | trabajador nativo | puerto 3306 por defecto |
| MariaDB | mariadb | reutiliza el trabajador de MySQL | puerto 3306 por defecto |
| TiDB | tidb | reutiliza el trabajador de MySQL | puerto 4000 por defecto |
| GreatSQL | greatsql | reutiliza el trabajador de MySQL | puerto 3306 por defecto |
| OceanBase | oceanbase, ob | reutiliza el trabajador de MySQL | puerto 2881 por defecto; conéctate como user@tenant |
| StarRocks | starrocks | reutiliza el trabajador de MySQL | puerto 9030 por defecto; no tiene base de datos de usuario hasta que se crea una |
| Apache Doris | doris | reutiliza el trabajador de MySQL | puerto 9030 por defecto; no tiene base de datos de usuario hasta que se crea una |
| PostgreSQL | postgresql, postgres, pgsql | trabajador nativo | puerto 5432 por defecto |
| CockroachDB | cockroachdb, cockroach, crdb | reutiliza el trabajador de PostgreSQL | |
| YugabyteDB | yugabytedb, yugabyte, yb | reutiliza el trabajador de PostgreSQL | puerto 5433 por defecto |
| openGauss | opengauss, gaussdb | trabajador JDBC | puerto 5432 por defecto; autentica con su propio controlador |
| Oracle | oracle | trabajador JDBC | --service <service-name> es obligatorio |
| SQL Server | sqlserver, mssql | trabajador JDBC | puerto 1433 por defecto |
| ClickHouse | clickhouse | trabajador JDBC | se conecta al puerto HTTP, 8123 por defecto |
| Trino | trino | trabajador JDBC | --database <catalog>[.<schema>] es obligatorio |
| TDengine | tdengine, taos | trabajador JDBC | se conecta a través de taosAdapter, 6041 por defecto |
| Dameng | dameng, dm | trabajador JDBC | puerto 5236 por defecto; la cuenta también es el esquema predeterminado |
| KingbaseES | kingbase, kingbasees | trabajador JDBC | puerto 54321 por defecto |
| Redis | redis | trabajador nativo | puerto 6379 por defecto; cada --command es un comando de Redis, no SQL |
| MongoDB | mongodb, mongo | trabajador nativo | puerto 27017 por defecto; cada --command es un documento de comando, no SQL |
| SQLite | sqlite, sqlite3 | trabajador nativo | --path <file> (o --database) abre o crea un archivo local; sin host, puerto ni credenciales; --property mode=ro y --property busy_timeout=<ms> |
| DuckDB | duckdb | trabajador nativo | --path <file> abre o crea un archivo local, :memory: mantiene uno para la invocación; --property read_only=true y --property threads=<n> |
| H2 | h2 | trabajador JDBC | --path <file> abre un archivo local, o --host y --port (9092 por defecto) alcanzan un servidor TCP |
| Presto | presto, prestodb | trabajador JDBC | puerto 8080 por defecto; --database <catalog>[.<schema>] es obligatorio; --username es obligatorio y una contraseña solo se envía a través de TLS |
| Hive | hive | trabajador JDBC | puerto 10000 por defecto; --database selecciona la base de datos de Hive, default cuando no está definido |
| Apache Kylin | kylin | trabajador JDBC | puerto 7070 por defecto; --database lleva el proyecto de Kylin, y la cuenta predeterminada es ADMIN/KYLIN |
| XuguDB | xugu, xugudb | trabajador JDBC | puerto 5138 por defecto; SYSTEM es la base de datos del sistema |
| IBM Db2 | db2, ibmdb2 | trabajador JDBC | puerto 50000 por defecto; necesita un controlador que proporciones, consulta Controladores que proporcionas |
| IBM Informix | informix, ifx | trabajador JDBC | puerto 9088 por defecto; --service <server-instance> es obligatorio y el controlador debe proporcionarse |
| SUNDB | sundb | trabajador JDBC | puerto 22581 por defecto; ejecuta el motor Goldilocks y necesita el controlador de la imagen del proveedor |
| GBase 8s | gbase8s, gbasedbt | trabajador JDBC | puerto 9088 por defecto; --service <server-instance> es obligatorio y el controlador debe proporcionarse |
--id y --datasource aceptan un UUID de datasource estable o su nombre único.
Para permitir que el usuario escriba la contraseña en una página local, de modo que nunca entre en la conversación ni en una respuesta de herramienta:
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 una conexión existente y mantener su contraseña guardada a menos que la reemplaces: sqlx datasource update --id dev --ui.
Las conexiones no usan TLS a menos que lo solicites: --tls tiene como valor predeterminado disable. Añade --tls verify-full para verificar el certificado de la base de datos; una base de datos que no sirve ningún certificado que tu máquina confíe falla entonces con invalid peer certificate: UnknownIssuer (MySQL), error performing TLS handshake (PostgreSQL) o una conexión cerrada (Oracle), que es el caso habitual de un contenedor local. Cualquiera de las dos opciones también está disponible como actualización:
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
Credenciales
Las credenciales provienen de variables de entorno con nombre, avisos interactivos ocultos o un objeto JSON de conexión en stdin. Nunca pongas una contraseña literal en un 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": {}
}
Las respuestas de datasource omiten nombres de usuario, contraseñas y propiedades del proveedor.
Importar conexiones
Una herramienta que ya almacena conexiones puede entregarlas todas en un solo documento versionado, de modo que una migración nunca necesite una contraseña en un argumento de comando. examples/import-connections.json es un punto de partida ejecutable:
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 es el mismo objeto que acepta --connection-stdin. merge (el predeterminado) añade nombres nuevos y actualiza los existentes en su lugar mientras mantiene sus IDs, y nunca elimina una conexión almacenada. Cada entrada se valida por separado, así que un motor no compatible o una conexión incompleta se informa en skipped con su motivo en lugar de fallar el 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 informa sin almacenar nada, --strict rechaza todo el documento cuando cualquier entrada no es válida, y --file <path> lee el documento de un archivo para llamadores que no pueden canalizar stdin. El almacén se escribe una sola vez, así que una importación nunca se aplica a medias.
total cuenta cada conexión que la importación consideró: las conexiones ya almacenadas más las entradas del documento, incluidas las que omitió. Con una conexión almacenada y dos entradas, una de ellas no válida, la respuesta informa total: 3, added: 1 y una entrada skipped.
Comandos
| Operación | Comando |
|---|---|
| Inicializar almacenamiento local | sqlx init |
| Crear una conexión | sqlx datasource add --name dev --type mysql --host localhost --database app --username-env DB_USER --password-env DB_PASSWORD |
| Listar conexiones | sqlx datasource list |
| Inspeccionar una conexión | sqlx datasource show --id dev |
| Cambiar la configuración de la conexión | sqlx datasource update --id dev --host db.example.com |
| Importar conexiones guardadas | sqlx datasource import --stdin |
| Eliminar una conexión guardada | sqlx datasource remove --id dev |
| Probar conectividad | sqlx datasource test --id dev |
| Ejecutar SQL | sqlx sql execute --datasource dev --command "SELECT 1" --command "SELECT 2" |
| Descargar workers, el runtime JDBC y la interfaz de usuario con antelación | 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 o all; los cuatro motores cuyo driver usted proporciona obtienen solo el runtime compartido) |
| Instalar un driver que la versión no puede incluir | sqlx driver add --type db2 --jar <path>, sqlx driver list, sqlx driver remove --type db2 |
| Ejecutar y abrir una página de resultados | sqlx sql execute --datasource dev --command "SELECT 1" --view |
| Leer un resultado almacenado | sqlx results list, sqlx results rows --id <result-id> --offset 100 --limit 50 |
| Mostrar o cambiar la configuración | sqlx setting list, sqlx setting set preview-rows 20, sqlx setting set results-dir ~/sqlx-results |
| Devolver un resultado grande en línea | sqlx sql execute --datasource dev --command "SELECT …" --full |
| Banco de trabajo local | sqlx ui, sqlx ui status, sqlx ui stop |
| Crear un gráfico y colocarlo en un panel | 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 en cualquier otro lugar, --sql se acepta como alias) |
| Ejecutar de nuevo el SQL de un gráfico guardado | sqlx analytics chart run revenue |
| Listar o eliminar gráficos y paneles | sqlx analytics list, sqlx analytics dashboard add --name "Sales", sqlx analytics remove chart revenue |
| Servir MCP a través de stdio | sqlx mcp |
| Instalar la Skill | sqlx skill install --target codex, --target claude, --target dsh o --target pi |
| Instalar en otro directorio de skills | sqlx skill install --path /path/to/skills/sqlx |
| Inspeccionar y actualizar Skills gestionadas | sqlx skill status, sqlx skill update |
| Dejar de gestionar una instalación de Skill | sqlx skill remove --path /path/to/skills/sqlx (los archivos se conservan) |
| Ayuda y versión | sqlx --help, sqlx --version |
Comportamiento de ejecución
Cada invocación posee una conexión de base de datos. Los argumentos --command repetidos se ejecutan en orden, inicialmente con autocommit, y se detienen en el primer error; no hay transacción implícita de todo o nada. Las tablas temporales y las variables de sesión no sobreviven a otra invocación. No envíe directivas de cliente como GO, DELIMITER o comandos de barra invertida de psql.
--command es la bandera actual y --sql todavía se acepta como alias.
La salida es un objeto JSON con un elemento por cada sentencia ejecutada: results[].stmt identifica la sentencia, cols lista las columnas como pares [name, type] (base64, boolean y json se unen como una tercera entrada cuando los valores no son texto plano), rows contiene los valores posicionales y count contiene el recuento de filas del driver. Las etiquetas duplicadas permanecen distintas. Los números se codifican como cadenas para preservar la precisión de enteros y decimales, y los datos binarios usan Base64. Una sentencia fallida lleva su propio error con un outcome; las sentencias que nunca se ejecutaron se listan en skipped; el objeto termina con success, que también es el estado de salida del proceso.
Solo una vista previa viaja a través de la salida estándar. Un conjunto de resultados con más filas que preview-rows (10 por defecto) o más de 16 KiB de valores se escribe completamente en results/<id>/<statement>-<result>.jsonl dentro del directorio de resultados, y su elemento lleva una ruta file más el id del objeto. Lea más filas de ese archivo, o páginelas con sqlx results rows --id <id> --offset 100. El directorio de resultados predeterminado es un directorio privado dentro del directorio temporal del sistema, por lo que los resultados desaparecen cuando la máquina se reinicia; sqlx setting set results-dir ~/sqlx-results los conserva, y sqlx setting set results-retention-hours 0 detiene la limpieza de 24 horas.
Un llamador que no puede leer archivos necesita el resultado completo en una sola respuesta: --full imprime cada fila y no almacena nada, sqlx setting set result-mode full hace que eso sea el valor predeterminado para esta máquina, y la herramienta MCP sqlx_sql_execute toma "full": true para una llamada. Un resultado grande entonces llena el propio presupuesto de salida del llamador, por lo que la vista previa es el valor predeterminado.
--events imprime el flujo de eventos crudo del worker en su lugar (protocol_version, datasource_id, events, success) para scripts que lo analizan, y nunca almacena nada. --preview <rows> anula el tamaño de la vista previa para una llamada.
Verifique la bandera final success y el estado de salida, y nunca reproduzca automáticamente una escritura incierta.
Páginas locales
Permita que el usuario inspeccione los resultados en un navegador e ingrese la contraseña allí.
sqlx sql execute --datasource dev --command "SELECT id, name FROM users ORDER BY id" --view
SQLX se ejecuta una vez y devuelve una URL local. La página carga los resultados automáticamente, admite múltiples conjuntos de resultados y paginación, y preserva los valores exactos. Recargar, paginar o reabrir la página lee el resultado en caché; Actualizar en la página vuelve a ejecutar el lote SQL original contra la base de datos, por lo que cualquier escritura en ese lote se ejecuta de nuevo. Una actualización exitosa reemplaza la instantánea mostrada en la misma URL; un fallo conserva el resultado anterior y no revierte los cambios de la base de datos. Los resultados se conservan localmente durante 24 horas.
sqlx ui abre el banco de trabajo local, sqlx ui status y sqlx ui stop inspeccionan o detienen el servicio, y --no-open devuelve un enlace sin abrir un navegador. El banco de trabajo también renderiza los gráficos y paneles creados con sqlx analytics (ver Analítica local); ese comando no necesita un servicio en ejecución. Las páginas solo son accesibles en la máquina que ejecuta SQLX, cargan automáticamente una sesión de navegador HttpOnly, y el servicio permanece activo hasta sqlx ui stop.
Escribir la contraseña en la página mantiene las credenciales fuera de la conversación, pero no las aísla de un agente que pueda leer archivos o controlar el navegador como el mismo usuario del sistema operativo. Consulte el diseño de la interfaz local para las fronteras de interfaz y almacenamiento.
Elija su interfaz de usuario
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 no activa un plugin; después de seleccionarlo, recargue una página abierta o ejecute sqlx ui. Las actualizaciones de CLI mantienen la versión de un plugin que usted instaló y mueven la interfaz predeterminada a la versión de la versión, y cambiar de versión necesita sqlx ui stop primero. Los plugins se ejecutan localmente y pueden acceder a credenciales ingresadas y datos mostrados, así que instale interfaces de autores en los que confíe: una suma de verificación prueba que los bytes descargados están intactos, no que el autor sea confiable.
Para construir su propia interfaz, consulte la guía de plugins de interfaz, el SDK de navegador tipado y el ejemplo de interfaz de terminal independiente. Los usuarios no necesitan un runtime de Node.js.
Datos y descargas
Los datos del usuario viven en ~/.sqlx/; use --data-dir o SQLX_DATA_DIR para otra ubicación. La configuración se almacena en ~/.sqlx/settings.json y se gestiona con sqlx setting list|get|set|unset; SQLX_PREVIEW_ROWS, SQLX_RESULTS_DIR, SQLX_RESULTS_RETENTION_HOURS y SQLX_RESULT_MODE anulan el archivo para un entorno, y una bandera de línea de comandos anula ambos. Los resultados almacenados viven en el directorio de resultados descrito anteriormente, se conservan 24 horas por defecto y permanecen bajo 1 GiB en total; los resultados más antiguos se eliminan antes de que se ejecute el siguiente comando, y los resultados de página de --view son gestionados por el servicio local. Las conexiones guardadas usan AES-256-GCM con una clave local generada independientemente: haga una copia de seguridad de la clave junto con los datos cifrados, porque perder la clave impide el descifrado. La identidad del dispositivo se genera localmente y esta versión no sube información del dispositivo.
El ejecutable principal no contiene drivers de base de datos; el worker de cada base de datos se descarga en el primer uso. MySQL, MariaDB, TiDB, GreatSQL, OceanBase, StarRocks y Apache Doris comparten el worker de MySQL, Redis, MongoDB, SQLite y DuckDB se ejecutan en sus propios workers nativos, PostgreSQL, CockroachDB y YugabyteDB comparten el worker de PostgreSQL, y Oracle, SQL Server, ClickHouse, Trino, Presto, TDengine, openGauss, Dameng, KingbaseES, H2, Hive, Apache Kylin, XuguDB, IBM Db2, IBM Informix, SUNDB y GBase 8s usan el worker JDBC (la tabla de bases de datos lista qué worker sirve a qué base de datos). Los recursos descargados provienen del manifiesto de versión fijo de la versión CLI en ejecución y se verifican antes de su uso; --manifest <https-url> selecciona otro manifiesto o un servidor de prueba local.
Las descargas ocurren en el primer uso y se almacenan en caché después. Cada una imprime Downloading … con velocidad y tiempo estimado, y una línea final Downloaded … in 12.3s (390 KB/s) en stderr; la línea de progreso se actualiza solo cuando stderr es una terminal, por lo que el JSON canalizado permanece limpio. Una transferencia interrumpida se reintenta hasta tres veces, y volver a ejecutar un comando fallido reutiliza cada componente que ya está instalado. Para evitar esperar dentro de la primera consulta o 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
Las referencias de bases de datos explican el propósito, los parámetros, el resultado y el enlace de documentación oficial de cada operación SQL.
Solución de problemas
| Síntoma | Qué hacer |
|---|---|
invalid peer certificate: UnknownIssuer, error performing TLS handshake | La conexión solicita verificación TLS y la base de datos no sirve ningún certificado que su máquina confíe (común en contenedores locales); elimine --tls verify-full (el valor predeterminado es disable) |
sqlx: command not found | El directorio de instalación falta en PATH: ~/.local/bin (macOS, Linux) o %LOCALAPPDATA%\Programs\SQLX (Windows) |
| La primera consulta parece atascada descargando | Ejecute sqlx prefetch <component> primero; después de una interrupción, volver a ejecutar reutiliza los componentes instalados |
| Cambiar la versión del plugin de interfaz falla | Ejecute sqlx ui stop primero, luego sqlx ui plugin remove |
| Una actualización falla | Verifique sqlx update status; vuelva a ejecutar el instalador si es necesario, las conexiones guardadas no se ven afectadas |
| Oracle o SQL Server reporta un error relacionado con JDBC | Vuelva a ejecutar con SQLX_JDBC_DEBUG=1 para ver los diagnósticos propios del driver |
Compilar desde el código fuente
El desarrollo de fuentes requiere Git, Rust 1.95, Node.js 22 y las herramientas de compilación nativas de la plataforma; Node.js solo compila los activos de plugins de interfaz. Para desarrollo de Oracle o SQL Server, instale también un JDK de Java 17 y Maven.
En macOS o 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
En 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
Mantenga el checkout en esa ubicación, o copie el CLI y ambos workers nativos en un directorio dedicado y actualice PATH y SQLX_WORKER_DIR en consecuencia. Esta compilación de fuentes hace que MySQL y PostgreSQL sean utilizables sin un manifiesto de worker publicado.
Para Oracle y SQL Server, compile el worker JDBC y coloque sus JARs de driver junto a esos workers. En macOS o 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
En 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 debe estar en PATH, o SQLX_JAVA_BIN puede apuntar a su ejecutable. Estas dependencias manuales solo son necesarias para el desarrollo de fuentes; una versión binaria descarga su runtime de Java privado y los drivers automáticamente.
Desarrollo y validación
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 locales, establezca SQLX_WORKER_DIR al directorio absoluto target/debug. Para desarrollo JDBC, ese directorio también contiene sqlx-jdbc.jar y ojdbc.jar o mssql-jdbc.jar; SQLX_JAVA_BIN puede seleccionar Java 17 explícitamente. Estas anulaciones son para desarrollo, no requisitos previos para usuarios de versiones. Los scripts de fixtures usan contenedores de prueba dedicados y credenciales solo de prueba.
Drivers que usted proporciona
La mayoría de los drivers JDBC se incluyen con la versión y se descargan en el primer uso. Los proveedores que no permiten que su driver sea redistribuido no están empaquetados: IBM Db2, IBM Informix, SUNDB y GBase 8s se conectan con un driver que usted instala una vez desde el proveedor.
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 el jar en <data-dir>/drivers/<engine>/, verifica que realmente contiene la
clase del driver del motor, y cada comando posterior lo carga desde allí. Un jar que tú proporciones también tiene prioridad sobre un
componente publicado, que es como se usa un driver de proveedor más nuevo antes de que la versión publicada lo alcance. Ejecutar una
sentencia para uno de estos motores sin un driver explica el comando exacto a ejecutar:
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> ejecuta la misma
ruta que toma un usuario de una versión publicada: instala el jar y luego ejecuta sin anulaciones de desarrollo, por lo que la CLI
resuelve el JRE y el ejecutor JDBC desde el manifiesto publicado. Necesita una versión publicada cuyo ejecutor JDBC
ya conozca el motor, así que ejecútalo contra una versión publicada en lugar de desde una rama de características.
De dónde provienen los drivers:
| Motor | Archivo a proporcionar | Clase del driver |
|---|---|---|
| IBM Db2 | jcc-<version>.jar de IBM o Maven Central (com.ibm.db2:jcc) | com.ibm.db2.jcc.DB2Driver |
| IBM Informix | el driver JDBC de Informix, línea 4.50 (com.ibm.informix:jdbc); la línea 15.x falla contra un servidor Informix 14.10 | com.informix.jdbc.IfxDriver |
| SUNDB | goldilocks8.jar de la imagen del proveedor en /goldilocks_home/lib/ | sunje.goldilocks.jdbc.GoldilocksDriver |
| GBase 8s | el ifxjdbc.jar del proveedor; un jar contenedor que lo incluya debe descomprimirse primero | com.gbasedbt.jdbc.IfxDriver |
Versiones publicadas y documentación
- Paquetes y sumas de verificación: GitHub Releases
- Notas de versión: docs/release-notes.md
- Límites de diseño e implementación: docs/design.md
- Comportamiento de actualización y recuperación: docs/updates.md
- Interfaz local y complementos: docs/local-ui.md, docs/ui-plugins.md
- Integraciones de agentes: integrations/README.md, Skill
No incluido: entrada de archivos SQL, sesiones persistentes, modos de transacción y error configurables, exportación de archivos de resultados, instalación de actualizaciones desatendida y telemetría.
Licencia
Este repositorio público de código fuente conserva la licencia Chat2DB modificada para el código adaptado. No es la licencia Apache 2.0 sin modificar. Consulta LICENSE y NOTICE; las dependencias de terceros conservan sus propias licencias.