SQLX

SQLX

Connect to 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 and MongoDB, or open a local SQLite, DuckDB or H2 file, from your terminal or from your agent. Connections are saved encrypted, one invocation runs one or more statements or commands, and the results come back complete and structured.

Quick start

# 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()"

Using an agent? See Use with your agent: install one plugin or extension and the agent calls SQLX directly.

Install the CLI

Three channels, pick one: prebuilt packages from GitHub Releases, the npx installer, or the platform install scripts.

macOS and Linux

curl -fsSL https://raw.githubusercontent.com/OtterMind/sqlx/main/scripts/install.sh | sh

export PATH="$HOME/.local/bin:$PATH" sqlx --version sqlx init

The installer selects your platform, downloads the executable and verifies its SHA-256. It installs to ~/.local/bin; add that directory to your shell's persistent PATH. SQLX_INSTALL_DIR chooses another directory and SQLX_VERSION selects a release version.

Windows x64

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 init

Add %LOCALAPPDATA%\Programs\SQLX to your user PATH for future sessions. Neither installer overwrites 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 Linux baseline is Ubuntu 24.04. Release users do not need Rust, Java or database drivers: database workers and a private JRE are downloaded only when needed.

Node.js (npx)

macOS, Linux and Windows x64 with Node.js 22 or newer:

npx -y @ottermind/sqlx@latest

export PATH="$HOME/.local/bin:$PATH" sqlx --version

The installer verifies the release manifest, SHA256SUMS and the downloaded archive before installing. It uses the same user-level location as the platform installers and installs the Skill into ./sqlx, which no agent watches: --target codex, --target claude, --target dsh, --target pi or --target place the Skill where it is actually discovered, and --cli-only installs the CLI alone. Any other first argument is run as a SQLX command instead of installing, so npx -y @ottermind/sqlx@latest mcp starts the MCP server. Node.js is needed only by the installer, never by the CLI.

Updates

The CLI updates its own executable:

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 installs an exact stable version. Updates do not stop running SQL or the UI service, do not modify saved connections, and do not update Skills or plugins automatically; use sqlx skill update for managed Skills, and an installed UI plugin keeps the version you selected (the default interface moves with the CLI release).

Interactive use checks in the background at most once per day and only prints a notice on stderr. Piped and CI commands skip that check, and SQLX_NO_UPDATE_CHECK=1 disables it. Source builds and package-manager-owned paths keep their own installation method.

Use with your agent

All four are ready as soon as they are installed: the plugin or extension installs the sqlx CLI itself when it is missing, so you never install it separately. Codex and Claude additionally require the CLI to meet the plugin's minimum version and refuse to start an older incompatible MCP server silently.

Each of them also leaves the Skill installed, because the CLI alone gives an agent the tools but none of the engine knowledge. A plugin installs the Skill into that agent's own directory on first launch when it is not there yet, and says so on stderr while it does.

Codex

codex plugin marketplace add OtterMind/sqlx@plugins

codex plugin add sqlx@ottermind

The plugin starts sqlx mcp over MCP. Read-only operations run directly; the two execution tools (sqlx_sql_execute and sqlx_sql_view) are marked destructive and Codex asks for approval by default.

Claude Code

claude plugin marketplace add OtterMind/sqlx@plugins

claude plugin install sqlx@ottermind

Headless runs need an explicit tool allowlist:

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 belong to a profile: install it into the profile you use, then restart dsh.

Pi

pi install npm:@ottermind/sqlx-pi

Any other MCP client

A client with no plugin system takes the server straight from the published package. It installs the sqlx CLI itself on first use, so this is the whole setup:

{

"mcpServers": { "sqlx": { "command": "npx", "args": ["-y", "@ottermind/sqlx@latest", "mcp"] } } }

Point command at an installed binary instead to start without npx; a GUI application often has no ~/.local/bin on its PATH, so give the absolute path (~/.local/bin/sqlx on macOS and Linux, %LOCALAPPDATA%\Programs\SQLX\sqlx.exe on Windows) and keep "args": ["mcp"].

Such a client receives no Skill, so its agent runs the tools without the engine recipes. Install it where the client reads instructions from with sqlx skill install --path .

SQLX is also listed in the MCP Registry as io.github.OtterMind/sqlx, which points at a container image for clients that install from there: docker run -i --rm ghcr.io/ottermind/sqlx:latest. A container reaches only the SQL-execution path — the credential page, the result page and the local workbench are served on the container's own 127.0.0.1, and the data directory lives inside it, so mount a volume at /root/.sqlx to keep saved connections. Prefer the package above when the user should type credentials or read results.

Skill only

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

For another agent, pass its skill directory with sqlx skill install --path .

Connections and SQL

Create a connection

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"

--id and --datasource accept a stable datasource UUID or its unique name.

To let the user type the password in a local page, so it never enters the conversation or a tool response:

sqlx datasource add --ui --name dev --type postgresql --host db.example.com --port 5432 --database app

sqlx datasource setup-status --request-id

To edit an existing connection and keep its saved password unless you replace it: sqlx datasource update --id dev --ui.

Connections do not use TLS unless you ask for