Connect to MySQL, PostgreSQL, Oracle, and SQL Server from your terminal or agent. Save encrypted connections, run one or more SQL statements, and receive complete structured results.
Start with the CLI, or install the Skill first and let your agent set up the CLI.
Download prebuilt packages from GitHub Releases, or use the installers below. See build from source for development.
The v0.1.3 release acceptance report records a real 0.1.2-to-0.1.3 self-update, public-download verification, preserved in-flight SQL/UI, and browser refresh workflows. Earlier v0.1.2 and v0.1.1 reports cover replacement/recovery and four-database/plugin acceptance.
Run:
curl -fsSL https://raw.githubusercontent.com/OtterMind/sqlx/main/scripts/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
sqlx --version
sqlx initThe installer selects your platform, downloads the executable from GitHub Releases, and verifies its SHA-256. It installs to ~/.local/bin. Add that directory to your shell's persistent PATH for future sessions. Set SQLX_INSTALL_DIR to choose another directory or SQLX_VERSION to select a release version.
Run in 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 initAdd %LOCALAPPDATA%\Programs\SQLX to your user PATH for future sessions. The installer verifies the download before installing. Both installers preserve an unrelated executable already named sqlx; use a different install directory in that case.
Prebuilt targets are macOS ARM64/x64, Linux ARM64/x64, and Windows x64. The initial Linux build baseline is Ubuntu 24.04; older distributions have not been verified. Release users do not need to install Rust, Node.js, Java, or database drivers separately. Database workers and a private JRE are downloaded only when needed.
Starting with 0.1.2, the CLI can update its own executable:
sqlx update check
sqlx update install
sqlx update statuscheck contacts GitHub and reports the latest stable version without installing it. install downloads the package for this platform, verifies its checksums and version, replaces the executable and verifies the installed path. Use sqlx update install --version <version> for an exact stable version. Updates do not stop running SQL or the UI service, modify saved connections, or automatically update Skills/plugins. Use sqlx skill update separately for managed Skills; UI plugins retain the user's selected version.
Interactive use checks in the background at most once per day and shows a cached notice on stderr. It does not install updates automatically. Piped/CI commands do not start automatic checks; SQLX_NO_UPDATE_CHECK=1 also disables them. Explicit update commands still work. status reads local history without network access. See update behavior and recovery.
Versions 0.1.0 and 0.1.1 do not have update commands. Rerun the installer above once to get the latest version; existing connections are preserved. Source builds and package-manager-owned paths use their original installation method.
Choose the agent you use:
# Codex
sqlx skill install --target codex
# Claude Code
sqlx skill install --target claudeFor another agent, provide its complete skill directory:
sqlx skill install --path /path/to/agent/skills/sqlx
sqlx skill statusThe CLI downloads the Skill from GitHub Releases. Reload skills or start a new agent session according to your agent's discovery mechanism. Later, sqlx skill update updates managed installations while preserving local edits.
The Skill source is available now and does not require the CLI. On macOS or Linux, install it for Codex with:
sqlx_checkout="$(mktemp -d)"
git clone --depth 1 https://github.com/OtterMind/sqlx.git "$sqlx_checkout"
mkdir -p "$HOME/.agents/skills"
if [ ! -e "$HOME/.agents/skills/sqlx" ]; then
cp -R "$sqlx_checkout/skills/sqlx" "$HOME/.agents/skills/sqlx"
else
echo "Skill directory already exists; existing files were preserved."
fiFor Claude Code, use ~/.claude/skills/sqlx as the destination. On Windows, the equivalent PowerShell steps for Codex are:
$checkout = Join-Path $env:TEMP ('sqlx-skill-' + [guid]::NewGuid())
git clone --depth 1 https://github.com/OtterMind/sqlx.git $checkout
$skillRoot = Join-Path $env:USERPROFILE '.agents\skills'
New-Item -ItemType Directory -Force $skillRoot | Out-Null
if (-not (Test-Path (Join-Path $skillRoot 'sqlx'))) {
Copy-Item -Recurse (Join-Path $checkout 'skills\sqlx') $skillRoot
} else {
Write-Output 'Skill directory already exists; existing files were preserved.'
}For another agent, copy the entire skills/sqlx folder, including references, into the agent's supported skill directory. Manual source installations remain manually managed; the CLI will not overwrite them as if it owned them.
After your agent discovers the Skill, you can ask:
Use the SQLX skill to install the OtterMind SQLX CLI if needed, then help me add and test a PostgreSQL connection. Ask me for missing connection details.
The Skill includes CLI installation instructions, so the agent can check its environment and follow the appropriate installation path.
Available starting with SQLX 0.1.1. Install the latest CLI using the instructions above, or rerun the installer to upgrade from 0.1.0; your saved connections are preserved.
Let the user enter the password directly in a local page. The CLI pre-fills the known connection settings:
sqlx datasource add --ui --name dev --type postgresql --host db.example.com --port 5432 --database appThe command returns immediately with a page URL and request_id. The user fills in their credentials and chooses Save & connect. SQLX verifies the connection and encrypts the saved configuration. The agent checks completion without receiving the password:
sqlx datasource setup-status --request-id <request-id>To edit an existing connection while keeping its saved password unless explicitly replaced:
sqlx datasource update --id dev --uiTo send an already written query to a results page:
sqlx sql execute --datasource dev --sql "SELECT id, name FROM users ORDER BY id" --viewSQLX executes once and returns a result URL. The page loads the results automatically, supports multiple result sets and pagination, and preserves exact values. Reloading, paging or reopening the page reads the cached result. In 0.1.3, Refresh explicitly reruns the original SQL batch against the database. Optional 5/10/30/60-second refresh intervals are off by default, wait for the previous run to finish, pause in hidden tabs, and stop on failure or navigation. SQL is executed unchanged, so any writes in the batch run again. A successful refresh replaces the displayed snapshot at the same URL; failures keep the previous result and do not roll back database changes. Results are retained locally for 24 hours, with owner-restricted permissions. The usual CLI execution mode still streams complete JSON to stdout.
sqlx ui opens the local workspace; sqlx ui status and sqlx ui stop inspect or stop it. --no-open returns a link without launching a browser. Pages are accessible on the same machine as SQLX. The local UI service and default UI plugin are separate packages, downloaded only when needed. Launch links expire after five minutes unless already exchanged for a browser session; in 0.1.3, authenticated activity renews the session for another 12 hours. The open page sends a heartbeat every 30 seconds. Unfinished setup requests expire after 30 minutes. The service exits after 30 idle minutes when no task is active.
Password entry through the page keeps credentials out of the normal agent conversation and tool response. It does not isolate credentials from an agent that can read files or control the browser as the same operating-system user. See the local UI design for the interface and storage boundaries.
SQLX 0.1.3 lists saved datasources in the workbench. Select a connection to inspect its settings, test connectivity or open its edit form while keeping the saved password.
The default interface is a plugin. CLI updates retain its selected version. To use the 0.1.3 page features after upgrading, let active work finish, run sqlx ui stop, install ui-default-0.1.3.zip from the 0.1.3 release with its SHA-256 from SHA256SUMS, and select default --version 0.1.3 using the commands below. The next sqlx ui starts the matching service.
You can also install a community interface and switch without changing saved connections or rerunning queries:
sqlx ui plugin install --url <plugin-zip-url> --sha256 <published-sha256>
sqlx ui plugin list
sqlx ui plugin use <plugin-id>Installation does not activate a plugin. After selecting it, reload an open page or run sqlx ui. To return to the default interface, run sqlx ui plugin use default. To remove an inactive version, stop the service with sqlx ui stop, then run sqlx ui plugin remove <plugin-id> --version <version>.
Plugins run locally and can access entered credentials and displayed data. Install interfaces from authors you trust; a checksum verifies the downloaded bytes, not the author's trustworthiness. SQLX validates API/CLI compatibility and preserves installed versions.
To build your own interface, see the UI plugin guide, typed browser SDK, and independent terminal UI example. Any framework that produces static browser assets can use the API. No Node.js runtime is needed by users.
Create a PostgreSQL connection. Replace the host and database with your own values; 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
sqlx sql execute --datasource dev --sql "SELECT current_database()" --sql "SELECT 1"For an agent or script, provide credentials through environment variables or a connection JSON object on stdin, as described below. TLS verifies the database certificate by default; use --tls disable only for a connection explicitly intended to be unencrypted.
| Operation | Command |
|---|---|
| Initialize local storage | sqlx init |
| Create a datasource | sqlx datasource add --name dev --type mysql --host localhost --database app --username-env DB_USER --password-env DB_PASSWORD |
| List connections | sqlx datasource list |
| Inspect a connection | sqlx datasource show --id dev |
| Change connection settings | sqlx datasource update --id dev --host db.example.com |
| Remove a saved connection | sqlx datasource remove --id dev |
| Test connectivity | sqlx datasource test --id dev |
| Execute SQL | sqlx sql execute --datasource dev --sql "SELECT 1" --sql "SELECT 2" |
| Install the Skill | sqlx skill install --target codex or --target claude |
| Install to another skill directory | sqlx skill install --path /path/to/skills/sqlx |
| Inspect/update managed Skills | sqlx skill status, sqlx skill update |
| Help/version | sqlx --help, sqlx --version |
--id and --datasource accept a stable datasource UUID or its unique name. Supported database type names are mysql, postgresql (postgres/pgsql), oracle, and sqlserver (mssql). Oracle requires --service. TLS defaults to certificate verification; --tls disable is available for explicitly unencrypted connections. The first authentication profile is username/password.
Credentials are read from named environment variables, hidden interactive prompts, or a connection JSON object on stdin. Do not put literal passwords in command arguments. For noninteractive creation or complete replacement, --connection-stdin accepts:
{
"database_type": "postgresql",
"host": "localhost",
"port": 5432,
"database": "app",
"service": "",
"username": "example_account",
"password": "replace_with_real_input",
"tls": "verify-full",
"properties": {}
}The object goes to stdin of sqlx datasource add --name dev --connection-stdin. It is not a SQL file input. Datasource responses omit usernames, passwords, and vendor properties.
Each invocation owns one database connection. Repeated --sql arguments execute in order, initially with autocommit, and stop at the first error. There is no implicit all-or-nothing transaction. Temporary tables and session variables do not survive another invocation. Do not submit client directives such as GO, DELIMITER, or psql backslash commands.
SQL output is one JSON object containing protocol_version, datasource_id, an ordered events array, and success. Events distinguish columns, positional row values, result boundaries, statement completion, errors, skipped statements, and overall completion. Duplicate labels remain distinct. Numbers are encoded as strings to preserve integer and decimal precision. Binary data and PostgreSQL types without a text decoder use Base64 with type metadata; an explicit SQL cast to text is available when a readable database representation is preferable.
Rows are streamed without a CLI row limit or silent truncation. The agent's own tool output limits still apply. Check the final success flag and exit status. An incomplete response or unknown write outcome must not trigger automatic replay.
User data lives in ~/.sqlx/. Use --data-dir or SQLX_DATA_DIR for another location. Saved connections use AES-256-GCM with an independently generated local key. Back up the key together with the encrypted data; losing the key prevents decryption. Device identity is generated locally, and this version does not upload device information.
The main executable contains no database drivers. MySQL and PostgreSQL use separate native Rust workers; Oracle and SQL Server use a separate JDBC worker. Downloaded resources are selected from the running CLI version's fixed GitHub Release manifest and verified before use. --manifest <https-url> selects a particular manifest or local test server.
The database references explain each SQL operation's purpose, parameters, result, and official documentation link.
Source development requires Git, Rust 1.95, Node.js 22, and the platform's native build tools. Node.js only builds UI plugin assets; release users do not need it. For Oracle or SQL Server development, also install a Java 17 JDK and Maven.
On macOS or 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 defaultOn 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 defaultKeep the checkout at that location, or copy the CLI and both native workers into a dedicated directory and update PATH and SQLX_WORKER_DIR accordingly. Add these settings to future sessions when needed. This source-build setup makes MySQL and PostgreSQL usable without a published worker manifest.
For Oracle and SQL Server, build the JDBC worker and place its driver JARs alongside those workers. On macOS or Linux:
mvn -B -f java/jdbc/pom.xml package
cp java/jdbc/target/sqlx-jdbc-0.1.3.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.jarOn Windows PowerShell:
mvn -B -f java/jdbc/pom.xml package
Copy-Item java/jdbc/target/sqlx-jdbc-0.1.3.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.jarJava 17 must be on PATH, or SQLX_JAVA_BIN can point to its executable. These manual dependencies are only needed for source development; a binary release downloads its private Java runtime and drivers automatically.
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
python3 tests/integration.py
python3 tests/ui_api.py
docker compose -f tests/compose.yaml down -vFor local native workers, set SQLX_WORKER_DIR to the absolute target/debug directory. For JDBC development, that directory also contains sqlx-jdbc.jar and ojdbc.jar or mssql-jdbc.jar; SQLX_JAVA_BIN can select Java 17 explicitly. These overrides are for development, not prerequisites for release users. The fixture scripts use dedicated test containers and test-only credentials.
See the design for implementation boundaries and deferred features. SQL-file input, persistent sessions, configurable transaction/error modes, result-file export, unattended update installation and telemetry are not included.
This public source repository retains the modified Chat2DB license for adapted code. It is not the unmodified Apache 2.0 license. See LICENSE and NOTICE; third-party dependencies retain their own licenses.