OtterMind/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. 安装 CLI（macOS、Linux 和 Windows x64；Node.js 22 或更新版本）
npx -y @ottermind/sqlx@latest
export PATH="$HOME/.local/bin:$PATH"

2. 创建连接（交互式终端会提示输入用户名和密码）
sqlx datasource add --name dev --type postgresql --host db.example.com --port 5432 --database app
sqlx datasource test --id dev

3. 运行 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 或数据库驱动：数据库 worker 和私有 JRE 仅在需要时下载。

Node.js（npx）

macOS、Linux 和 Windows x64，需 Node.js 22 或更新版本：

npx -y @ottermind/sqlx@latest
export PATH="$HOME/.local/bin:$PATH"
sqlx --version
安装程序在安装前会验证发布清单、SHA256SUMS 和下载的归档文件。它使用与平台安装程序相同的用户级位置，并将 Skill 安装到 ./sqlx；--target codex、--target claude、--target dsh、--target pi 或 --target  会将 Skill 放到其他位置。Node.js 仅由安装程序需要，CLI 从不需要。

更新

CLI 会更新自身的可执行文件：

sqlx update check       # 报告最新的稳定版本而不安装它
sqlx update install     # 下载、验证并替换可执行文件
sqlx update status      # 在不访问网络的情况下读取本地历史记录

sqlx update install --version  会安装一个确切的稳定版本。更新不会停止正在运行的 SQL 或 UI 服务，不会修改已保存的连接，也不会自动更新 Skills 或插件；对于托管的 Skills，请使用 sqlx skill update，而已安装的 UI 插件会保留你选择的版本（默认界面随 CLI 版本一起更新）。

交互式使用每天最多在后台检查一次，并且仅在 stderr 上打印通知。管道和 CI 命令会跳过该检查，而 SQLX_NO_UPDATE_CHECK=1 会禁用它。源码构建和由包管理器管理的路径会保留各自的安装方式。

与你的 agent 一起使用

这四个在安装后即可使用：插件或扩展会在 sqlx CLI 缺失时自行安装它，因此你无需单独安装。Codex 和 Claude 还要求 CLI 满足插件的最低版本，并拒绝静默启动较旧的不兼容 MCP 服务器。

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    # 浏览器 UI
dsh plugin --profile tui add @ottermind/sqlx-dsh    # 终端 UI

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

Pi

pi install npm:@ottermind/sqlx-pi

仅 Skill

sqlx skill install --target codex     # Codex 和 dsh 共享 ~/.agents/skills
sqlx skill install --target claude
sqlx skill install --target dsh
sqlx skill install --target pi

sqlx skill status                     # 列出托管的安装
sqlx skill update                     # 更新它们，同时保留本地编辑

对于其他 agent，请通过 sqlx skill install --path  传入其 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  |
| SQL Server | sqlserver、mssql | JDBC worker | 默认端口 1433 |
| ClickHouse | clickhouse | JDBC worker | 连接到 HTTP 端口，默认 8123 |
| Trino | trino | JDBC worker | 必须提供 --database [.] |
| TDengine | tdengine、taos | JDBC worker | 通过 taosAdapter 连接，默认 6041 |
| Dameng | dameng、dm | JDBC worker | 默认端口 5236；账户同时也是默认 schema |
| 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 （或 --database）打开或创建本地文件；无需主机、端口或凭据；--property mode=ro 和 --property busy_timeout= |
| DuckDB | duckdb | 原生 worker | --path  打开或创建本地文件，:memory: 在本次调用期间保留一个；--property read_only=true 和 --property threads= |
| H2 | h2 | JDBC worker | --path  打开本地文件，或使用 --host 和 --port（默认 9092）连接 TCP 服务器 |
| Presto | presto、prestodb | JDBC worker | 默认端口 8080；必须提供 --database [.]；必须提供 --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 ，且必须提供驱动 |
| SUNDB | sundb | JDBC worker | 默认端口 22581；运行 Goldilocks 引擎，需要来自厂商镜像的驱动 |
| GBase 8s | gbase8s、gbasedbt | JDBC worker | 默认端口 9088；必须指定 --service ，且必须提供驱动 |

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

要让用户在本地页面中输入密码，使其永远不会进入对话或工具响应：
sh
sqlx datasource add --ui --name dev --type postgresql --host db.example.com --port 5432 --database app
sqlx datasource setup-status --request-id

要编辑现有连接并保留其已保存的密码，除非你替换它：sqlx datasource update --id dev --ui。

TLS 默认验证数据库证书。本地容器中的数据库通常不会提供你的机器信任的证书，此时连接会失败并报错 invalid peer certificate: UnknownIssuer（MySQL）、error performing TLS handshake（PostgreSQL）或连接关闭（Oracle）。对此类连接显式禁用传输加密：
sh
sqlx datasource add --name dev --type mysql --host 127.0.0.1 --port 3306 --database app \
--username-env DB_USER --password-env DB_PASSWORD --tls disable
sqlx datasource update --id dev --tls disable

凭据

凭据来自命名的环境变量、隐藏的交互式提示，或 stdin 上的连接 JSON 对象。切勿在命令参数中放入明文密码。
sh
sqlx datasource add --name dev --connection-stdin
json
{
"database_type": "postgresql",
"host": "localhost",
"port": 5432,
"database": "app",
"service": "",
"username": "example_account",
"password": "replace_with_real_input",
"tls": "verify-full",
"properties": {}
}

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

导入连接

已经存储了连接的工具可以在一个带版本号的文档中一次性移交所有连接，因此迁移永远不需要在命令参数中提供密码。examples/import-connections.json 是一个可运行的起点：
sh
sqlx datasource import --stdin  会从文件读取文档，供无法通过管道传入 stdin 的调用方使用。存储只会写入一次，因此导入绝不会只应用一半。

命令

| 操作 | 命令 |
|---|---|
| 初始化本地存储 | 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" |
| 提前下载 worker、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 、sqlx driver list、sqlx driver remove --type db2 |
| 执行并打开结果页面 | sqlx sql execute --datasource dev --command "SELECT 1" --view |
| 读取已存储的结果 | sqlx results list、sqlx results rows --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 |
| 通过 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 |
| 检查并更新受管理的 Skill | 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//-.jsonl，其条目带有 file 路径以及该对象的 id。从该文件中读取更多行，或用 sqlx results rows --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 改为打印原始 worker 事件流（protocol_version、datasource_id、events、success），供解析它的脚本使用，并且从不存储任何内容。--preview  可为单次调用覆盖预览大小。

检查最终的 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 的机器访问，会自动加载一个 HttpOnly 浏览器会话，并且服务会一直运行，直到执行 sqlx ui stop。

在页面中输入密码可以让凭据不进入对话，但这并不能将它们与能够以同一操作系统用户身份读取文件或控制浏览器的代理隔离开来。有关接口和存储边界，请参阅本地 UI 设计。

选择你的 UI
sh
sqlx ui plugin install --url  --sha256
sqlx ui plugin list
sqlx ui plugin use           # default restores the default interface
sqlx ui plugin remove  --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 和独立生成的本地密钥：请将密钥与加密数据一起备份，因为丢失密钥将无法解密。设备标识在本地生成，此版本不会上传任何设备信息。

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

下载在首次使用时进行，之后会被缓存。每次下载都会打印 Downloading … 以及速度和预计时间，并在 stderr 上输出最终的 Downloaded … in 12.3s (390 KB/s) 行；进度行仅在 stderr 为终端时刷新，因此通过管道传递的 JSON 保持干净。中断的传输最多重试三次，重新运行失败的命令会复用所有已安装的组件。为避免在首次查询或分页时等待：
sh
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 disable |
| sqlx: command not found | 安装目录未加入 PATH：~/.local/bin（macOS、Linux）或 %LOCALAPPDATA%\Programs\SQLX（Windows） |
| 首次查询似乎卡在下载 | 先运行 sqlx prefetch ；中断后重新运行会复用已安装的组件 |
| 切换 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 上：
sh
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 上：
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 和两个原生 worker 复制到一个专用目录，并相应更新 PATH 和 SQLX_WORKER_DIR。这种源码构建方式使 MySQL 和 PostgreSQL 无需已发布的 worker 清单即可使用。

对于 Oracle 和 SQL Server，构建 JDBC worker，并将其驱动 JAR 与这些 worker 放在一起。在 macOS 或 Linux 上：
sh
mvn -B -f java/jdbc/pom.xml package
cp java/jdbc/target/sqlx-jdbc-0.1.17.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 上：
powershell
mvn -B -f java/jdbc/pom.xml package
Copy-Item java/jdbc/target/sqlx-jdbc-0.1.17.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 运行时和驱动程序。

开发与验证
sh
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
一次一组；StarRocks 和 Doris 各需要一个前端和一个后端
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 和 KingbaseES 没有公共镜像；请将测试夹具指向本地实例
并在密码不同时导出 SQLX_TEST_DAMENG_PASSWORD 或 SQLX_TEST_KINGBASE_PASSWORD
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 和 Informix 轮流进行，因为每个都需要数 GB 内存
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 需要厂商驱动及其自己的实例；SUNDB 需要授权安装
而 XuguDB 需要一个密码已知的试用镜像。tests/databases.py 列出了所有变量。
export SQLX_TEST_GBASE8S_DRIVER=~/gbasedbt-jdbc.jar
python3 tests/databases.py gbase8s

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

由你提供的驱动程序

大多数 JDBC 驱动程序随发行版一起提供，并在首次使用时下载。不允许的厂商
需要重新分发的驱动程序未打包：IBM Db2、IBM Informix、SUNDB 和 GBase 8s 需要连接
使用你从供应商处一次性安装的驱动程序。
sh
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 复制到 /drivers//，检查它确实包含
该引擎的驱动程序类，之后每条命令都会从那里加载它。你提供的 jar 也会优先于
已发布的组件，这就是在发布版本跟上之前使用更新供应商驱动程序的方式。在没有驱动程序的情况下
为这些引擎之一运行语句时，会说明要运行的确切命令：
sh
sqlx sql execute --datasource  --command "SELECT 1 FROM SYSIBM.SYSDUMMY1"
SQLX does not redistribute the db2 driver; run sqlx driver add --type db2 --jar  with the vendor driver jar first

scripts/release-driver-check.sh      会运行与
发布用户相同的路径——安装 jar，然后在没有开发覆盖的情况下执行，因此 CLI
会从已发布的清单中解析 JRE 和 JDBC 运行器。它需要一个其 JDBC 运行器
已经知道该引擎的发布版本，因此请针对已发布的版本运行它，而不是从功能分支运行。

驱动程序的来源：

| 引擎 | 要提供的文件 | 驱动程序类 |
| --- | --- | --- |

| IBM Db2 | jcc-.jar from IBM or Maven Central (com.ibm.db2:jcc) | com.ibm.db2.jcc.DB2Driver |
| IBM Informix | the Informix JDBC driver, 4.50 line (com.ibm.informix:jdbc); the 15.x line fails against an Informix 14.10 server | com.informix.jdbc.IfxDriver |
| SUNDB | goldilocks8.jar from the vendor image at /goldilocks_home/lib/ | sunje.goldilocks.jdbc.GoldilocksDriver |
| GBase 8s | the vendor's ifxjdbc.jar; a wrapper jar that contains it must be unpacked first | com.gbasedbt.jdbc.IfxDriver |

Releases and documentation

- Packages and checksums: GitHub Releases
- Release notes: docs/release-notes.md
- Design and implementation boundaries: docs/design.md
- Update behavior and recovery: docs/updates.md
- Local interface and plugins: docs/local-ui.md, docs/ui-plugins.md
- Agent integrations: integrations/README.md, Skill

Not included: SQL-file input, persistent sessions, configurable transaction and error modes, result-file export, unattended update installation, and telemetry.

License

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.