SQLX

SQLX

通过终端或 Agent 连接 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 和 MongoDB，也可以打开本地 SQLite、DuckDB 或 H2 文件。连接会以加密形式保存；每次调用可运行一条或多条语句或命令，结果会完整、结构化地返回。

快速开始

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

要与 Agent 配合使用？请参阅与 Agent 配合使用：安装一个插件或扩展，Agent 就会直接调用 SQLX。

安装 CLI

有三种安装渠道，可任选其一：从 GitHub Releases 下载预构建包、使用 npx 安装程序，或使用平台安装脚本。

macOS 和 Linux

curl -fsSL https://raw.githubusercontent.com/OtterMind/sqlx/main/scripts/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
sqlx --version
sqlx init

安装程序会选择适合你平台的版本，下载可执行文件并验证其 SHA-256。它会安装到 ~/.local/bin；请将该目录添加到 shell 的持久 PATH 中。SQLX_INSTALL_DIR 可指定其他目录，SQLX_VERSION 可选择发布版本。

Windows x64

在 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

将 %LOCALAPPDATA%\Programs\SQLX 添加到用户 PATH，以便在后续会话中使用。如果已有无关的可执行文件名为 sqlx，两种安装程序都不会覆盖它；遇到这种情况时，请使用其他安装目录。

预构建目标平台包括 macOS ARM64/x64、Linux ARM64/x64 和 Windows x64；Linux 的基准环境为 Ubuntu 24.04。使用发布版本无需安装 Rust、Java 或数据库驱动程序：只有在需要时才会下载数据库工作进程和私有 JRE。

Node.js（npx）

适用于安装了 Node.js 22 或更高版本的 macOS、Linux 和 Windows x64：

npx -y @ottermind/sqlx@latest
export PATH="$HOME/.local/bin:$PATH"
sqlx --version

安装程序会验证发布清单、SHA256SUMS 和下载的归档文件，然后再进行安装。它使用与平台安装程序相同的用户级目录，并将 Skill 安装到 ./sqlx；没有 Agent 会监视此目录。使用 --target codex、--target claude、--target dsh、--target pi 或 --target <directory>，即可将 Skill 放到实际会被发现的位置；--cli-only 则只安装 CLI。除安装外，其他任意首个参数都会作为 SQLX 命令运行，因此 npx -y @ottermind/sqlx@latest mcp 会启动 MCP 服务。Node.js 仅供安装程序使用，CLI 本身不需要它。

更新

CLI 可以自行更新可执行文件：

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> 会安装指定的稳定版本。更新不会停止正在运行的 SQL 或 UI 服务，不会修改已保存的连接，也不会自动更新 Skill 或插件；托管的 Skill 请使用 sqlx skill update 更新。已安装的 UI 插件会保留你选择的版本（默认界面会随 CLI 发布版本更新）。

交互式使用时，CLI 最多每天在后台检查一次，并且只会在 stderr 上显示通知。通过管道运行的命令和 CI 命令会跳过此检查；设置 SQLX_NO_UPDATE_CHECK=1 可将其禁用。通过源码构建的安装以及由包管理器管理的路径，仍需使用各自的安装方式进行管理。

与 Agent 配合使用

四种方案安装完成后即可使用：如果缺少 sqlx CLI，插件或扩展会自行安装，无需单独安装。Codex 和 Claude 还要求 CLI 满足插件的最低版本要求；如果 MCP 服务版本较旧且不兼容，它们会拒绝静默启动。

此外，每种方案都会安装 Skill，因为只有 CLI 虽然能为 Agent 提供工具，却不包含任何引擎知识。如果 Agent 自己的目录中尚未安装 Skill，插件会在首次启动时将其安装到该目录，并在安装时通过 stderr 告知你。

Codex

codex plugin marketplace add OtterMind/sqlx@plugins
codex plugin add sqlx@ottermind

插件会通过 MCP 启动 sqlx mcp。只读操作可直接运行；两个执行工具（sqlx_sql_execute 和 sqlx_sql_view）会标记为具有破坏性，Codex 默认会要求批准。

Claude Code

claude plugin marketplace add OtterMind/sqlx@plugins
claude plugin install sqlx@ottermind

无头运行需要显式指定工具允许列表：

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

插件属于某个配置文件：将其安装到你使用的配置文件中，然后重启 dsh。

Pi

pi install npm:@ottermind/sqlx-pi

其他 MCP 客户端

没有插件系统的客户端会直接从已发布的软件包获取服务。首次使用时，它会自行安装 sqlx CLI，因此只需进行以下设置：

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

也可以将 command 指向已安装的二进制文件，以便不通过 npx 启动；GUI 应用通常不会在 PATH 中包含 ~/.local/bin，因此请提供绝对路径（macOS 和 Linux 上为 ~/.local/bin/sqlx，Windows 上为 %LOCALAPPDATA%\Programs\SQLX\sqlx.exe），并保留 "args": ["mcp"]。

此类客户端不会收到 Skill，因此其中的 Agent 运行工具时无法使用引擎配方。请使用 sqlx skill install --path <directory> 将其安装到客户端读取指令的位置。

SQLX 也已列入 MCP Registry，名称为 io.github.OtterMind/sqlx。对于从该处安装的客户端，它指向一个容器镜像：docker run -i --rm ghcr.io/ottermind/sqlx:latest。容器只能访问 SQL 执行路径——凭据页面、结果页面和本地工作台都由容器自身的 127.0.0.1 提供服务，数据目录也位于容器内，因此请在 /root/.sqlx 挂载卷以保留已保存的连接。如果希望用户输入凭据或查看结果，建议使用上面的软件包。

仅安装 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

对于其他 Agent，请使用 sqlx skill install --path <directory> 指定其 Skill 目录。

连接和 SQL

创建连接

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"

数据库	--type 值	执行方式	必需值和默认值
MySQL	mysql	原生 worker	默认端口为 3306
MariaDB	mariadb	复用 MySQL worker	默认端口为 3306
TiDB	tidb	复用 MySQL worker	默认端口为 4000
GreatSQL	greatsql	复用 MySQL worker	默认端口为 3306
OceanBase	oceanbase、ob	复用 MySQL worker	默认端口为 2881；以 user@tenant 格式连接
StarRocks	starrocks	复用 MySQL worker	默认端口为 9030；创建用户数据库之前没有用户数据库
Apache Doris	doris	复用 MySQL worker	默认端口为 9030；创建用户数据库之前没有用户数据库
PostgreSQL	postgresql、postgres、pgsql	原生 worker	默认端口为 5432
CockroachDB	cockroachdb、cockroach、crdb	复用 PostgreSQL worker
YugabyteDB	yugabytedb、yugabyte、yb	复用 PostgreSQL worker	默认端口为 5433
openGauss	opengauss、gaussdb	JDBC worker	默认端口为 5432；使用自己的驱动进行身份验证
Oracle	oracle	JDBC worker	必须指定 --service <service-name>
SQL Server	sqlserver、mssql	JDBC worker	默认端口为 1433
ClickHouse	clickhouse	JDBC worker	连接 HTTP 端口，默认为 8123
Trino	trino	JDBC worker	必须指定 --database <catalog>[.<schema>]
TDengine	tdengine、taos	JDBC worker	通过 taosAdapter 连接，默认端口为 6041
Dameng	dameng、dm	JDBC worker	默认端口为 5236；账户也用作默认架构
KingbaseES	kingbase、kingbasees	JDBC worker	默认端口为 54321
Redis	redis	原生 worker	默认端口为 6379；每个 --command 都是一条 Redis 命令，而不是 SQL
MongoDB	mongodb、mongo	原生 worker	默认端口为 27017；每个 --command 都是一份命令文档，而不是 SQL
SQLite	sqlite、sqlite3	原生 worker	--path <file>（或 --database）用于打开或创建本地文件；无需主机、端口或凭据；支持 --property mode=ro 和 --property busy_timeout=<ms>
DuckDB	duckdb	原生 worker	--path <file> 用于打开或创建本地文件，:memory: 会在本次调用期间保留内存数据库；支持 --property read_only=true 和 --property threads=<n>
H2	h2	JDBC worker	--path <file> 用于打开本地文件；也可通过 --host 和 --port 连接 TCP 服务（默认端口为 9092）
Presto	presto、prestodb	JDBC worker	默认端口为 8080；必须指定 --database <catalog>[.<schema>]；必须指定 --username，且仅通过 TLS 发送密码
Hive	hive	JDBC worker	默认端口为 10000；--database 用于选择 Hive 数据库，未设置时默认为 default
Apache Kylin	kylin	JDBC worker	默认端口为 7070；--database 用于指定 Kylin 项目，默认账户为 ADMIN/KYLIN
XuguDB	xugu、xugudb	JDBC worker	默认端口为 5138；SYSTEM 是系统数据库
IBM Db2	db2、ibmdb2	JDBC worker	默认端口为 50000；需要使用你提供的驱动，参见你提供的驱动
IBM Informix	informix、ifx	JDBC worker	默认端口为 9088；必须指定 --service <server-instance>，且必须提供驱动
SUNDB	sundb	JDBC worker	默认端口为 22581；运行 Goldilocks 引擎，需要使用供应商镜像中的驱动
GBase 8s	gbase8s、gbasedbt	JDBC worker	默认端口为 9088；必须指定 --service <server-instance>，且必须提供驱动

--id 和 --datasource 接受稳定的数据源 UUID 或其唯一名称。

若要让用户在本地页面中输入密码，使其不会进入对话或工具响应：

sqlx datasource add --ui --name dev --type postgresql --host db.example.com --port 5432 --database app
sqlx datasource setup-status --request-id <request-id>

若要编辑现有连接，并保留已保存的密码（除非替换密码）：sqlx datasource update --id dev --ui。 除非显式启用 TLS，否则连接不会使用 TLS：--tls 默认值为 disable。添加 --tls verify-full 可验证数据库证书；如果数据库提供的证书不受你的计算机信任，则连接会失败，并出现 invalid peer certificate: UnknownIssuer（MySQL）、error performing TLS handshake（PostgreSQL）或连接关闭（Oracle）。本地容器通常就是这种情况。两种选项也都可以通过更新设置：

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

凭据

凭据可以来自命名环境变量、隐藏的交互式提示，或通过 stdin 传入的连接 JSON 对象。切勿将明文密码放在命令参数中。

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": {}
}

数据源响应会省略用户名、密码和供应商属性。

导入连接

已存储连接的工具可以通过一份带版本的文档一次性交出所有连接，因此迁移时无需在命令参数中提供密码。examples/import-connections.json 是一个可运行的起始示例：

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"
      }
    }
  ]
}

每个 connection 都是 --connection-stdin 接受的同一种对象。merge（默认值）会添加新名称，并原位更新现有名称，同时保留其 ID，且绝不会删除已存储的连接。每个条目都会单独验证，因此不受支持的引擎或不完整的连接会连同原因一起列在 skipped 中，而不会导致整份文档失败：

{"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 会验证并报告，但不会存储任何内容；--strict 会在任何条目无效时拒绝整份文档；对于无法通过管道传入 stdin 的调用方，--file <path> 会从文件读取文档。存储内容只会写入一次，因此导入绝不会只应用一部分。

total 统计导入处理的所有连接：已存储的连接加上文档中的条目，包括跳过的条目。若已存储一个连接，文档中有两个条目，其中一个无效，则响应会报告 total: 3、added: 1，以及一个 skipped 条目。

命令

操作	命令
初始化本地存储	sqlx init
创建连接	sqlx datasource add --name dev --type mysql --host localhost --database app --username-env DB_USER --password-env DB_PASSWORD
列出连接	sqlx datasource list
检查连接	sqlx datasource show --id dev
更改连接设置	sqlx datasource update --id dev --host db.example.com
导入已保存的连接	sqlx datasource import --stdin
移除已保存的连接	sqlx datasource remove --id dev
测试连通性	sqlx datasource test --id dev
执行 SQL	sqlx sql execute --datasource dev --command "SELECT 1" --command "SELECT 2"
提前下载工作进程、JDBC 运行时和 UI	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 或 all；对于由你提供驱动程序的四种引擎，仅下载共享运行时）
安装发行版无法随附的驱动程序	sqlx driver add --type db2 --jar <path>、sqlx driver list、sqlx driver remove --type db2
执行查询并打开结果页面	sqlx sql execute --datasource dev --command "SELECT 1" --view
读取已存储的结果	sqlx results list、sqlx results rows --id <result-id> --offset 100 --limit 50
显示或更改设置	sqlx setting list、sqlx setting set preview-rows 20、sqlx setting set results-dir ~/sqlx-results
在内联结果中返回大量数据	sqlx sql execute --datasource dev --command "SELECT …" --full
本地工作台	sqlx ui、sqlx ui status、sqlx ui stop
创建图表并将其添加到仪表板	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"（与其他地方一样，也接受 --sql 作为别名）
再次运行已保存图表的 SQL	sqlx analytics chart run revenue
列出或删除图表和仪表板	sqlx analytics list、sqlx analytics dashboard add --name "Sales"、sqlx analytics remove chart revenue
通过 stdio 提供 MCP 服务	sqlx mcp
安装 Skill	sqlx skill install --target codex、--target claude、--target dsh 或 --target pi
安装到其他 Skill 目录	sqlx skill install --path /path/to/skills/sqlx
检查并更新受管理的 Skills	sqlx skill status、sqlx skill update
停止管理 Skill 安装	sqlx skill remove --path /path/to/skills/sqlx（保留文件）
帮助和版本	sqlx --help、sqlx --version

执行行为

每次调用都会使用一个数据库连接。重复的 --command 参数会按顺序执行，初始状态为自动提交，并在遇到第一个错误时停止；不会隐式开启全有或全无的事务。临时表和会话变量不会保留到另一次调用中。不要提交 GO、DELIMITER 或 psql 反斜杠命令等客户端指令。

--command 是当前标志，仍接受 --sql 作为别名。

输出为一个 JSON 对象，每条已执行语句对应一个条目：results[].stmt 标识语句，cols 将列列为 [name, type] 对（值不是纯文本时，base64、boolean 和 json 会作为第三个条目加入），rows 保存位置值，count 保存驱动程序的行数。重复的标签仍会分别保留。数字会编码为字符串，以保留整数和小数精度；二进制数据使用 Base64 编码。执行失败的语句会带有自己的 error 和 outcome；尚未运行的语句会列在 skipped 中；对象以 success 结尾，该值也同时作为进程退出状态。

标准输出中只会显示预览。如果结果集的行数超过 preview-rows（默认值为 10），或值的总量超过 16 KiB，则会将完整结果写入结果目录中的 results/<id>/<statement>-<result>.jsonl，相应条目会带有 file 路径和对象的 id。可从该文件读取更多行，或使用 sqlx results rows --id <id> --offset 100 分页读取。默认结果目录是系统临时目录中的私有目录，因此机器重启后结果会消失；使用 sqlx setting set results-dir ~/sqlx-results 可保留结果，使用 sqlx setting set results-retention-hours 0 可关闭 24 小时清理。

无法读取文件的调用方需要在一次答复中获取完整结果：--full 会打印所有行且不存储任何内容，sqlx setting set result-mode full 可将其设为本机默认模式，MCP 工具 sqlx_sql_execute 则可在单次调用中传入 "full": true。大型结果可能会占满调用方自身的输出预算，因此默认使用预览模式。

对于需要解析事件流的脚本，--events 会改为打印原始工作器事件流（protocol_version、datasource_id、events、success），且不会存储任何内容。--preview <rows> 可为单次调用覆盖预览行数。

请检查最终的 success 标志和退出状态；对于结果不确定的写入操作，绝不要自动重放。

本地页面

让用户在浏览器中查看结果并输入密码。

sqlx sql execute --datasource dev --command "SELECT id, name FROM users ORDER BY id" --view

SQLX 执行一次后会返回一个本地 URL。页面会自动加载结果，支持多个结果集和分页，并保留精确值。重新加载、翻页或重新打开页面时，会读取缓存的结果；在页面上点击 Refresh 会将原始 SQL 批次重新提交到数据库执行，因此该批次中的任何写入操作都会再次运行。刷新成功后，会在同一 URL 上替换所显示的快照；刷新失败则保留之前的结果，且不会回滚数据库更改。结果会在本地保留 24 小时。

sqlx ui 会打开本地工作台，sqlx ui status 和 sqlx ui stop 可用于检查或停止服务，--no-open 则只返回链接，不会启动浏览器。工作台还会呈现使用 sqlx analytics 创建的图表和仪表板（参见本地分析）；该命令无需服务运行。页面只能在运行 SQLX 的机器上访问，会自动加载 HttpOnly 浏览器会话；服务会持续运行，直到执行 sqlx ui stop。

在页面中输入密码可避免凭据进入对话，但无法防止能以同一操作系统用户身份读取文件或控制浏览器的 Agent 获取这些凭据。有关界面和存储边界，请参见本地 UI 设计。

选择你的 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>

安装插件不会自动启用它；选择插件后，请重新加载已打开的页面，或运行 sqlx ui。CLI 更新会保留已安装插件的版本，并将默认界面更新到当前发行版的版本；切换版本前需要先运行 sqlx ui stop。插件在本地运行，可以访问输入的凭据和显示的数据，因此请只安装来自可信作者的界面：校验和只能证明下载的字节未损坏，不能证明作者可信。

如需构建自己的界面，请参阅 UI 插件指南、类型化浏览器 SDK 和独立的终端 UI 示例。用户无需安装 Node.js 运行时。

数据与下载

用户数据存储在 ~/.sqlx/；使用 --data-dir 或 SQLX_DATA_DIR 可指定其他位置。设置存储在 ~/.sqlx/settings.json 中，并通过 sqlx setting list|get|set|unset 管理；SQLX_PREVIEW_ROWS、SQLX_RESULTS_DIR、SQLX_RESULTS_RETENTION_HOURS 和 SQLX_RESULT_MODE 可在当前环境中覆盖该文件的设置，而命令行标志可同时覆盖两者。存储的结果位于上文所述的结果目录中，默认保留 24 小时，总量不超过 1 GiB；下次命令运行前会删除较早的结果，而 --view 的页面结果由本地服务管理。已保存的连接使用 AES-256-GCM 加密，并采用独立生成的本地密钥：请将密钥与加密数据一起备份，因为密钥丢失后将无法解密。设备身份在本地生成，此版本不会上传任何设备信息。

主可执行文件不包含数据库驱动；每种数据库的工作进程都会在首次使用时下载。MySQL、MariaDB、TiDB、GreatSQL、OceanBase、StarRocks 和 Apache Doris 共用 MySQL 工作进程；Redis、MongoDB、SQLite 和 DuckDB 使用各自的原生工作进程；PostgreSQL、CockroachDB 和 YugabyteDB 共用 PostgreSQL 工作进程；Oracle、SQL Server、ClickHouse、Trino、Presto、TDengine、openGauss、Dameng、KingbaseES、H2、Hive、Apache Kylin、XuguDB、IBM Db2、IBM Informix、SUNDB 和 GBase 8s 使用 JDBC 工作进程（数据库表格列出了各数据库使用的工作进程）。下载的资源来自当前 CLI 版本的固定发行清单，并会在使用前进行验证；--manifest <https-url> 可指定其他清单或本地测试服务。

下载在首次使用时进行，之后会缓存。每次下载都会显示带有速度和预计时间的 Downloading …，并在 stderr 上输出最终的 Downloaded … in 12.3s (390 KB/s) 行；仅当 stderr 是终端时才会刷新进度行，因此通过管道传输的 JSON 不会受到干扰。中断的传输最多重试三次，重新运行失败的命令时会复用已安装的所有组件。要避免在首次查询或打开页面时等待：

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

数据库参考说明了每种 SQL 操作的用途、参数、结果以及官方文档链接。

故障排除

症状	处理方法
invalid peer certificate: UnknownIssuer、error performing TLS handshake	连接要求进行 TLS 验证，但数据库未提供你的计算机信任的证书（在本地容器中很常见）；请去掉 --tls verify-full（默认值为 disable）
sqlx: command not found	安装目录未加入 PATH：~/.local/bin（macOS、Linux）或 %LOCALAPPDATA%\Programs\SQLX（Windows）
首次查询似乎卡在下载	先运行 sqlx prefetch <component>；中断后重新运行会复用已安装的组件
切换 UI 插件版本失败	先运行 sqlx ui stop，然后运行 sqlx ui plugin remove
更新失败	检查 sqlx update status；如有需要，重新运行安装程序，已保存的连接不会受影响
Oracle 或 SQL Server 报告 JDBC 相关错误	使用 SQLX_JDBC_DEBUG=1 重新运行，以查看驱动程序自身的诊断信息

从源代码构建

从源代码开发需要 Git、Rust 1.95、Node.js 22 和平台原生构建工具；Node.js 仅用于构建 UI 插件资源。开发 Oracle 或 SQL Server 时，还需安装 Java 17 JDK 和 Maven。

在 macOS 或 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

在 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

将检出内容保留在该位置，或将 CLI 和两个原生工作器复制到专用目录，并相应更新 PATH 和 SQLX_WORKER_DIR。此源代码构建无需发布的工作器清单即可使用 MySQL 和 PostgreSQL。

对于 Oracle 和 SQL Server，请构建 JDBC 工作器，并将其驱动 JAR 放在这些工作器旁边。在 macOS 或 Linux 上：

mvn -B -f java/jdbc/pom.xml package
cp java/jdbc/target/sqlx-jdbc-0.1.21.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

在 Windows PowerShell 上：

mvn -B -f java/jdbc/pom.xml package
Copy-Item java/jdbc/target/sqlx-jdbc-0.1.21.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 必须位于 PATH 中，也可以通过 SQLX_JAVA_BIN 指定其可执行文件。这些手动依赖仅在从源代码开发时需要；二进制版本会自动下载专用 Java 运行时和驱动。

开发与验证

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

对于本地原生工作器，将 SQLX_WORKER_DIR 设置为绝对路径的 target/debug 目录。对于 JDBC 开发，该目录还包含 sqlx-jdbc.jar 和 ojdbc.jar 或 mssql-jdbc.jar；可以通过 SQLX_JAVA_BIN 显式选择 Java 17。这些覆盖项仅用于开发，不是发布版本用户的前置条件。fixture 脚本使用专用测试容器和仅用于测试的凭据。

由你提供的驱动

大多数 JDBC 驱动都随发布版本提供，并会在首次使用时下载。对于不允许重新分发驱动的供应商，其驱动不会打包：连接 IBM Db2、IBM Informix、SUNDB 和 GBase 8s 时，需要从供应商处安装一次驱动。

sqlx driver add --type db2 --jar ~/Downloads/jcc-12.1.0.0.jar
sqlx driver list
sqlx driver remove --type db2

sqlx driver add 会将 JAR 复制到 <data-dir>/drivers/<engine>/，检查其中是否确实包含该引擎的驱动类，之后的每条命令都会从该位置加载驱动。你提供的 JAR 也会优先于发布版本中的组件，因此可以在发布版本更新之前使用较新的供应商驱动。对于这些引擎，如果执行语句时没有驱动，系统会说明应运行的确切命令：

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> 会执行与发布版本用户相同的流程——安装 JAR，然后在没有开发覆盖项的情况下执行，以便 CLI 从已发布的清单解析 JRE 和 JDBC 运行器。它需要一个已支持该引擎的 JDBC 运行器的发布版本，因此请使用已发布版本进行测试，而不要从功能分支运行。

驱动的来源：

引擎	需提供的文件	驱动类
IBM Db2	来自 IBM 或 Maven Central（com.ibm.db2:jcc）的 jcc-<version>.jar	com.ibm.db2.jcc.DB2Driver
IBM Informix	Informix JDBC 驱动，4.50 系列（com.ibm.informix:jdbc）；15.x 系列无法连接 Informix 14.10 服务器	com.informix.jdbc.IfxDriver
SUNDB	来自供应商镜像 /goldilocks_home/lib/ 的 goldilocks8.jar	sunje.goldilocks.jdbc.GoldilocksDriver
GBase 8s	供应商的 ifxjdbc.jar；必须先解包包含该文件的封装 JAR	com.gbasedbt.jdbc.IfxDriver

发布版本与文档

• 安装包和校验和：GitHub Releases
• 发布说明：docs/release-notes.md
• 设计与实现边界：docs/design.md
• 更新行为与恢复：docs/updates.md
• 本地界面与插件：docs/local-ui.md、docs/ui-plugins.md
• Agent 集成：integrations/README.md、Skill

不包括：SQL 文件输入、持久会话、可配置的事务和错误模式、结果文件导出、无人值守的更新安装以及遥测。

许可证

此公开源代码仓库中的改编代码仍采用修改后的 Chat2DB 许可证，而非未经修改的 Apache 2.0 许可证。请参阅 LICENSE 和 NOTICE；第三方依赖项仍采用其各自的许可证。