API 参考
SQLly Embedded 桥接管理 API 的每个端点,由它的 OpenAPI(swagger.json)文档生成,外加 sqlly.app 的关联端点。
嵌入模式下的 SQLly 桥接器会在其管理监听器上公开此 API(--manage-bind,默认 127.0.0.1:8445)。你的 Web 应用会从它的服务器端调用它,用来存储连接配置文件、测试连接、为已登录用户签发启动令牌、跟踪席位使用情况,以及读取或修改许可证状态。
每个 /manage/... 调用需要 Authorization: Bearer <manage token> (桥接的 --manage-token,至少 16 个字符)。请求体和响应体都是 JSON,最大 8 MB(超出时以 413 too_large 一旦超过限制)。路径段和查询字符串值会进行百分号解码;无效的转义是 400 bad_request。错误始终是 { "error": "<code>", "message": "<sentence>" },以及 problems 当凭据文档无效时。API 不发送 CORS 响应头:请让它只在回环地址或专用网络中运行,切勿将其暴露给浏览器,因为配置文件保存着数据库密码。
这 Linking 操作不在桥上:它们是 sqlly.app 的公共端点,管理员应用用来将安装链接到许可证而无需复制密钥。它们的服务器是 sqlly.app.
约定
- 身份验证:
Authorization: Bearer <manage token>在每个/manage/…调用。缺失或错误的令牌会被401 unauthorized./healthz而 sqlly.app 的链接端点则完全不需要。 - 错误 是
{ "error": "<code>", "message": "<sentence>" }。根据error; 显示message。无效的凭证文档会添加problems,每个错误一条字符串。 - 主体 是 JSON,最大 8 MB。这个限制在请求体传输过程中就会执行:桥接会回应
413 too_large在请求体传入的那一刻即会发出,且绝不缓冲更多。需要超过 30 秒才能到达的请求体就是408 timeout。无法解析的内容会400 bad_json,而未知路由则是404 not_found. - 路径段和查询值 是经过百分号解码的,因此需要对用户 ID 和时间戳进行 URL 编码(
DELETE /manage/seats/a%2Fb会释放用户a/b)。无效的转义或非 UTF-8 的结果会400 bad_request. - 字段名称 在 API 自身的载荷中是驼峰命名。而在凭证文档里,它们遵循凭证格式(
sql_auth_accounts,trust_server_certificate).
端点
- GET
/healthz - GET
/manage/status - POST
/manage/license/checkin - PUT
/manage/license - 删除(DELETE)
/manage/license - GET
/manage/engines - GET
/manage/profiles - GET
/manage/profiles/{id} - PUT
/manage/profiles/{id} - 删除(DELETE)
/manage/profiles/{id} - POST
/manage/tokens - GET
/manage/seats - 删除(DELETE)
/manage/seats/{user} - POST
/manage/test-connection - GET
/manage/queries - POST
/api/embedded/links - POST
/api/embedded/links/token - GET
/api/embedded/public-key
健康状态
存活检测,无需令牌。
/healthz
无令牌
存活探针
管理监听器一启动即可响应。无需令牌;可从启动脚本和服务健康检查中调用。
- 200
- 管理 API 正在监听。
200 响应示例
{
"ok": true
}
许可证
桥接所运行的许可证:状态、签到、关联与解除关联。
/manage/status
桥接和许可证状态
管理页面需要的一切:许可证状态及其来源、已签发授权所含的配额、正在使用的席位、活动会话,以及浏览器所用的代理 URL。
- 200
- 当前状态。
- 401
unauthorized: 管理令牌缺失或有误。
200 响应示例
{
"version": "1.1.0",
"instanceId": "b5e1c0f2-7d3a-4c8e-9a61-0f2d4b7e9c13",
"mode": "connected",
"license": {
"state": "ok",
"source": "linked",
"licenseId": "emb_Q2x0b3VkU3FsbHkxMjM0NTY3",
"plan": "embedded-25",
"planName": "SQLly Embedded 25",
"status": "active",
"seats": 25,
"sessionsPerSeat": 4,
"instances": 1,
"domain": "portal.example.com",
"periodEnd": "2027-10-14T00:00:00+00:00",
"graceEnd": null,
"daysRemaining": 365,
"lastCheckinAt": "2026-10-14T15:00:02Z",
"staleAt": "2026-10-14T15:40:02Z",
"licenseFile": null,
"message": null,
"fromCache": false,
"features": [
"embedded",
"unlimited-connections",
"all-engines",
"test-connection"
]
},
"seatsUsed": 3,
"activeSessions": 4,
"proxyUrl": "wss://portal.example.com/sqlly/proxy",
"allowLocalhostOrigins": false,
"storeUrl": "https://sqlly.app",
"allowFileEngines": false
}
401 响应示例
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
/manage/license/checkin
立即向 sqlly.app 签入
已连接并绑定的许可证:立即签到,而不是等 20 分钟一轮的循环。离线许可证:重新读取许可证文件,从不联网。无论哪种,回复都是尝试后的状态;失败则状态保持不变。
- 200
- 签到后的状态。
- 401
unauthorized: 管理令牌缺失或有误。- 409
not_linked: 该桥接器未获得许可,没有可签入的内容。- 422
license_file_invalid(离线):文件缺失、损坏,或者是用另一个密钥签的名。- 502
store_unreachable或者grant_invalid:无法访问 sqlly.app,或其回复未通过验证。
401 响应示例
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
409 响应示例
{
"error": "not_linked",
"message": "this bridge is not linked to a license yet"
}
/manage/license
安装关联的许可证密钥
让启动时未带 --license-key / --license-file 它在运行时使用的密钥(通常是你的管理应用刚通过链接流程从 sqlly.app 收来的密钥)。桥接会先用它签到,并把它保存(<state-dir>/license-key,模式 0600),而且只有当 sqlly.app 回应了经过验证的授权时才会这样做;从此它作为已连接的桥接运行,密钥在重启后继续沿用。失败时一切照旧:正在使用的密钥会继续服务,直到新密钥验证成功。用另一张许可证的密钥替换已关联的密钥,会在新密钥验证后释放旧许可证的实例槽位;同一许可证重新生成的密钥会重用存储里的实例行。
请求体(LinkLicenseRequest)
{
"licenseKey": "sqe_2xH7c0VqHk9LmZr1aPq4tN8bW6yD3sJfUe5o"
}
- 200
- 已关联。状态现在显示
license.source: linked. - 400
invalid_license_key:空的、格式错误的、未知的或被撤销的密钥。- 401
unauthorized: 管理令牌缺失或有误。- 409
license_from_flag: 该桥接器启动时使用了--license-key或者--license-file,因此它的许可证不通过此 API 管理。- 502
store_unreachable: 无法访问 sqlly.app,或其回复未通过验证。
401 响应示例
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
/manage/license
解除此安装的绑定
释放此桥接的实例槽,在 sqlly.app 上吊销其密钥(尽力而为),删除存储的密钥,关闭所有打开的会话并将桥接返回到 unlicensed.
- 204
- 已取消链接。
- 401
unauthorized: 管理令牌缺失或有误。- 404
not_linked: 不存储任何关联的密钥。- 409
license_from_flag: 该桥接器启动时使用了--license-key或者--license-file,因此它的许可证不通过此 API 管理。
401 响应示例
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
引擎
凭据格式所接受的数据库引擎,这样你的界面就永远不用硬编码这份列表。
/manage/engines
凭据格式所接受的引擎
SQLly 支持的每个数据库引擎,连同 engine 写入凭据文档的 ID、它的默认端口,以及是否 server 是文件路径,而 authentication.type 它接受的值。
- 200
- 引擎。
- 401
unauthorized: 管理令牌缺失或有误。
200 响应示例
[
{
"id": "sql-server",
"name": "Microsoft SQL Server",
"defaultPort": 1433,
"fileBased": false,
"authentication": [
"sql-login",
"integrated",
"entra-browser",
"entra-device-code"
]
},
{
"id": "postgres",
"name": "PostgreSQL",
"defaultPort": 5432,
"fileBased": false,
"authentication": [
"sql-login"
]
},
{
"id": "sqlite",
"name": "SQLite",
"defaultPort": 0,
"fileBased": true,
"authentication": [
"none"
]
}
]
401 响应示例
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
配置文件
配置文件是一份命名的 SQLly 凭证文档:某一组用户能看到的连接(和标签)。桥接器是记录的权威存储;机密信息永远不会到达浏览器。
/manage/profiles
列出配置文件
所有已存的配置文件,均不含凭据。
- 200
- 配置。
- 401
unauthorized: 管理令牌缺失或有误。
200 响应示例
[
{
"id": "analysts",
"name": "Analysts",
"connections": 2,
"updatedAt": "2026-10-14T15:02:11Z"
}
]
401 响应示例
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
/manage/profiles/{id}
读取单个配置档案
该配置及其完整凭据文档(含密钥):调用方是你信任的服务器端应用。
- id
- 路径 · 字符串,须匹配 ^[A-Za-z0-9_-]{1,64}$ · 必填 - 你的配置文件 ID。
- 200
- 该配置。
- 400
invalid_profile_id: 配置文件 ID 由 1-64 个如下字符组成:A-Z a-z 0-9 _ -.- 401
unauthorized: 管理令牌缺失或有误。- 404
unknown_profile: 没有使用该 ID 的配置文件。
401 响应示例
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
404 响应示例
{
"error": "unknown_profile",
"message": "no profile with id analysts"
}
/manage/profiles/{id}
创建或替换配置文件
将配置档案存储在以下位置 id (创建或替换)。在写入任何内容之前,会对凭证文档进行完整验证:解析器发现的每个问题都会在 problems,并且无效的文档不会有任何更改。包含基于文件的引擎(SQLite、DuckDB)的文档同样会被拒绝,除非桥接器以 --allow-file-engines true,因为这样的连接会让用户拿到桥接主机上的文件访问权。已打开的会话保留启动时的目录;编辑在下次启动时生效。
- id
- 路径 · 字符串,须匹配 ^[A-Za-z0-9_-]{1,64}$ · 必填 - 你的配置文件 ID。
请求体(PutProfileRequest)
{
"name": "Analysts",
"credentials": {
"format": "sqlly-credentials",
"version": 1,
"clients": [
{
"name": "Northwind Traders",
"color": "#1E88E5"
}
],
"environments": [
{
"name": "Production",
"color": "#C62828",
"safety": {
"only_allow_select": true
}
}
],
"sql_auth_accounts": [
{
"name": "Reader",
"username": "reader",
"password": "…"
}
],
"connections": [
{
"name": "Northwind",
"engine": "sql-server",
"server": "sql01.internal",
"database": "Northwind",
"environment": "production",
"client": "Northwind Traders",
"authentication": {
"type": "sql-login",
"account": "Reader"
},
"tls": {
"encrypt": true,
"trust_server_certificate": true
}
},
{
"name": "Warehouse",
"engine": "postgres",
"server": "dw.internal",
"database": "dw",
"environment": "production",
"client": "Northwind Traders",
"authentication": {
"type": "sql-login",
"account": "Reader"
},
"tls": {
"mode": "verify-full"
}
}
]
}
}
- 200
- 已存储。
- 400
invalid_profile(带有problems: 解析器问题,或每个基于文件的引擎在--allow-file-engines处于关闭状态),或者invalid_profile_id.- 401
unauthorized: 管理令牌缺失或有误。- 500
storage:无法写入状态目录。
400 响应示例
{
"error": "invalid_profile",
"message": "the credential document has 2 problems",
"problems": [
"connections[0].engine: unknown engine \"postgress\"",
"connections[1].authentication.pasword: unknown key"
]
}
401 响应示例
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
/manage/profiles/{id}
删除配置文件
移除该配置文件。已打开的会话保留启动时的目录;之后为它签发的新启动令牌都会被拒绝,并返回 unknown_profile.
- id
- 路径 · 字符串,须匹配 ^[A-Za-z0-9_-]{1,64}$ · 必填 - 你的配置文件 ID。
- 204
- 已删除。
- 400
invalid_profile_id: 配置文件 ID 由 1-64 个如下字符组成:A-Z a-z 0-9 _ -.- 401
unauthorized: 管理令牌缺失或有误。- 404
unknown_profile: 没有使用该 ID 的配置文件。
401 响应示例
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
404 响应示例
{
"error": "unknown_profile",
"message": "no profile with id analysts"
}
启动
启动令牌让单个用户以单个配置文件打开 SQLly。席位即并发用户数。
/manage/tokens
签发启动令牌
创建一个短期有效的令牌,用于为 user 与 profile,也可以直接进查询标签页(open,启动上下文)。将返回的 proxyUrl 和 token 放入加载 SQLly 的页面中(globalThis.SQLLY_PROXY_URL / globalThis.SQLLY_PROXY_TOKEN)。令牌可以反复使用,直到过期(页面重新加载);配置文件则在签发时即被捕获。
用户只要有打开的会话或未过期的令牌,就占用一个席位。为已持有席位的用户签发令牌绝不会因席位数而失败;为新用户签发令牌则会失败,并返回 seat_limit 当许可的每个席位都在使用时,统计该许可下每个桥接器上的用户数。
请求体(MintTokenRequest)
{
"user": "dana.analyst",
"profile": "analysts",
"open": {
"connection": "Shop",
"database": "sales",
"title": "Big orders",
"script": "SELECT *\nFROM orders\nWHERE total > @min_total",
"parameters": {
"min_total": 500
},
"cursor": {
"line": 3,
"column": 7
}
}
}
- 201
- 令牌。
- 400
invalid_user(为空或包含空白,最多 128 个字符),invalid_profile(存储的配置文件不再通过校验,或者它使用的是基于文件的引擎,而--allow-file-engines处于关闭状态),或者invalid_open(启动上下文引用了未知的连接、未知的字段或类型、错误的参数名或值、越界的光标,或传入了超限的值;problems列出每个错误及其路径,例如open[1].cursor: …).- 401
unauthorized: 管理令牌缺失或有误。- 404
unknown_profile: 没有使用该 ID 的配置文件。- 409
seat_limit: 每个席位都已被占用。释放一个(DELETE /manage/seats/{user})或购买更大的套餐。- 503
license_not_ok: 许可证不是ok或者grace(已失效、已过期、已吊销、未获准入、域名不匹配或未获许可)。消息会说明具体是哪一种。
201 响应示例
{
"token": "elt_q3J0n8w2Zx5rVb1kTq9yLs4dHf7cMa6p",
"expiresAt": "2026-10-14T15:12:11Z",
"proxyUrl": "wss://portal.example.com/sqlly/proxy",
"user": "dana.analyst",
"profile": "analysts",
"seatsUsed": 3,
"seats": 25,
"openTabs": 0
}
401 响应示例
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
/manage/seats
正在使用的席位
持有此桥接席位的用户及其打开的会话和有效令牌。 seatsUsed 还统计 sqlly.app 报告的同一许可证下其他桥接上的用户。
- 200
- 席位使用情况。
- 401
unauthorized: 管理令牌缺失或有误。
200 响应示例
{
"seats": 25,
"seatsUsed": 2,
"users": [
{
"user": "dana.analyst",
"activeSessions": 1,
"tokens": 1,
"since": "2026-10-14T15:02:11Z"
},
{
"user": "sam.support",
"activeSessions": 2,
"tokens": 1,
"since": "2026-10-14T14:40:03Z"
}
]
}
401 响应示例
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
/manage/seats/{user}
释放用户的席位
撤销该用户的令牌并关闭其会话,立即释放席位。当用户在你的应用中登出或失去访问权限时调用。释放未持有席位的用户并不会报错。路径段会进行百分号解码: a%2Fb 会释放用户 a/b.
- 用户
- 路径 · 字符串 · 必填 - 你为其签发令牌的用户 ID(URL 编码)。
- 204
- 已发布。
- 400
bad_request:该段不是有效的百分号编码。- 401
unauthorized: 管理令牌缺失或有误。
401 响应示例
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
连接
在任何人使用之前,先验证连接可用。
/manage/test-connection
测试单个连接
针对一个恰好只含一条连接的凭据文档运行一个一次性引擎,并执行一条简单查询。连接失败会报告为 ok: false 带有引擎自身的消息(HTTP 200);只有无法使用的文档才会返回 HTTP 错误。
请求体(TestConnectionRequest)
{
"credentials": {
"format": "sqlly-credentials",
"version": 1,
"connections": [
{
"name": "Northwind",
"engine": "sql-server",
"server": "sql01.internal",
"database": "Northwind",
"authentication": {
"type": "sql-login",
"username": "reader",
"password": "…"
},
"tls": {
"encrypt": true,
"trust_server_certificate": true
}
}
]
}
}
- 200
- 结果,不论成功与否。
- 400
invalid_profile: 文档无效、所含连接不是恰好一个,或包含基于文件的引擎,而--allow-file-engines处于关闭状态(参见problems).- 401
unauthorized: 管理令牌缺失或有误。
200 响应示例
{
"ok": true,
"elapsedMs": 212,
"message": "Connected: SQL Server 17.0"
}
401 响应示例
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
审核
查询审计记录:会话运行过的每条查询和每次行编辑,由谁运行、针对哪个连接、如何结束。保存在内存以及 <state-dir>/queries.jsonl (包含 SQL 文本),除非桥接启动时带了 --query-log false.
/manage/queries
查询审核记录
桥接会话运行过的每一条查询和每一次行编辑,最新的在前:启动令牌的用户和配置文件,它点名的连接(名称、服务器、引擎、数据库),SQL 文本(截断到 64 KiB,参见 sqlTruncated)、开始时间、状态和时长,以及失败时来自引擎的错误。仍在运行的请求会显示其状态 running;因许可证状态异常而被拒绝的请求状态为 failed 带有许可证信息;当会话关闭时正在运行的任何内容是 cancelled 带有错误 session closed.
桥接器保留最新的 --query-log-max-entries 条(默认 20 000 条)存放在内存和 <state-dir>/queries.jsonl,因此这条轨迹重启后依然保留。借助 --query-log false 不会记录任何内容,回复为 { "enabled": false, "queries": [] }.
- 限制
- 查询 · 整数 - 返回的条目数量,限制为 1-1000。
- 用户
- 查询 · 字符串 - 仅此用户 ID(完全匹配,URL 编码)。
- 配置文件
- 查询 · 字符串 - 仅此配置文件 ID(完全匹配)。
- 自
- 查询 · 字符串(日期-时间) - 仅包括其
at不早于此 RFC 3339 时间戳(URL 编码)。 - 状态
- 查询 · QueryStatus - 仅包括处于此状态的条目。
- 200
- 匹配的条目,最新的在前。
- 400
bad_request:limit不是整数,since不是 RFC 3339 格式,status未知,或者某个值不是有效的百分号编码。- 401
unauthorized: 管理令牌缺失或有误。
200 响应示例
{
"enabled": true,
"total": 2,
"limit": 200,
"queries": [
{
"id": "q-7",
"sessionId": 12,
"kind": "query",
"at": "2026-10-14T15:04:09.120Z",
"user": "dana.analyst",
"profile": "analysts",
"profileName": "Analysts",
"connection": "Northwind",
"server": "sql01.internal",
"database": "Northwind",
"engine": "Microsoft SQL Server",
"sql": "SELECT TOP 100 * FROM Orders",
"sqlTruncated": false,
"status": "completed",
"durationMs": 184,
"error": null
},
{
"id": "q-6",
"sessionId": 12,
"kind": "query",
"at": "2026-10-14T15:03:51.004Z",
"user": "dana.analyst",
"profile": "analysts",
"profileName": "Analysts",
"connection": "Northwind",
"server": "sql01.internal",
"database": "Northwind",
"engine": "Microsoft SQL Server",
"sql": "SELECT * FROM Ordres",
"sqlTruncated": false,
"status": "failed",
"durationMs": 31,
"error": "Invalid object name 'Ordres'."
}
]
}
401 响应示例
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
关联
sqlly.app 端点(服务器 sqlly.app)是将安装与许可证关联起来的方法:先创建一个代码,所有者在自己的浏览器里批准,只需收集一次该安装自己的密钥,然后通过 PUT /manage/license 把它交给桥接器。
/api/embedded/links
sqlly.app
无令牌
开始关联安装 (sqlly.app)
匿名。创建链接请求后会返回一个短码、一个只有你的应用知道的密钥,以及许可证所有者批准该请求的 URL。展示代码并打开 linkUrl 供所有者使用,然后轮询 POST /api/embedded/links/token 每个 pollIntervalSeconds 直到它被批准。链接在 15 分钟后过期。
请求体(CreateLinkRequest)
{
"name": "SQLly Embedded on portal-01",
"hostname": "portal-01",
"appVersion": "1.4.0"
}
- 201
- 已建立关联。
- 429
- 请求次数受限。
- 503
link_unavailable: 无法分配关联码;请重试。
201 响应示例
{
"linkId": "eml_Y2h9u0bQ1sXk4tWm8pZr3vLa",
"code": "K7Q-4MX",
"secret": "pW0r7…",
"linkUrl": "https://sqlly.app/embedded/link?code=K7Q-4MX",
"expiresAt": "2026-10-14T15:17:11Z",
"pollIntervalSeconds": 3
}
/api/embedded/links/token
sqlly.app
无令牌
轮询已关联的密钥(sqlly.app)
匿名;链接密钥即凭证。在所有者尚未决定期间,返回 202 pending。批准后会为这个安装生成它自己的许可证密钥,且只返回这一次(链接随即作废)。把密钥直接交给桥接器 PUT /manage/license;请不要自行存储。
请求体(LinkTokenRequest)
- 200
- 已批准:密钥,仅一次。
- 202
- 仍在等待所有者。
- 401
wrong_secret.- 404
unknown_link.- 410
link_used,link_denied,link_expired或者license_revoked:这个链接永远无法完成。请重新发起一个。- 429
- 请求次数受限。
/api/embedded/public-key
sqlly.app
无令牌
许可证签名公钥(sqlly.app)
sqlly.app 用于签署许可证授权的 PEM 公钥,操作员可以将其与编译进桥接器的密钥进行比较。
- 200
- PEM 文本。
- 503
signing_not_configured.
模式
上述对象的定义见 swagger.json。一个 ? 在类型之后意味着它可以是 null.
错误
每一个错误回复。 error 是稳定的机器码; message 是一句可以直接拿给管理员看的话。
| 字段 | 类型 | 描述 |
|---|---|---|
error * |
string |
|
message * |
string |
|
problems |
string[] |
出现于 invalid_profile: 凭证解析器发现的所有问题。 |
LicenseState
ok 和 grace 处理查询;其他任何状态都会拒绝工作,并返回一条 SQLly 会向用户显示的消息。
以下之一: ok grace stale not_admitted expired revoked domain_mismatch unlicensed
StatusReport
| 字段 | 类型 | 描述 |
|---|---|---|
version |
string |
桥接版本。 |
instanceId |
string |
此桥接进程在 sqlly.app 眼中的 ID。 |
mode |
connected | offline |
|
license |
LicenseReport |
|
seatsUsed |
integer |
许可证下每个桥接正在使用的席位数。 |
activeSessions |
integer |
此桥接器上打开的 SQLly 会话。 |
proxyUrl |
string |
浏览器使用的 WebSocket URL(--public-url). |
allowLocalhostOrigins |
boolean |
|
storeUrl |
string |
|
allowFileEngines |
boolean |
配置文件是否可以使用基于文件的引擎 (--allow-file-engines). |
许可证报告
用量来自签名授权,从不来自未签名数据。
| 字段 | 类型 | 描述 |
|---|---|---|
state |
LicenseState |
|
source |
flag | file | linked | none |
flag: --license-key; file: --license-file; linked: 由 PUT /manage/license 存储; none:未授权。 |
licenseId |
string? |
|
plan |
string? |
计划 ID,或者 custom 用于按其自身条款签发的许可证。 |
planName |
string? |
|
status |
string? |
sqlly.app 上次签到的状态:active、grace、expired、revoked、domain_mismatch。 |
seats |
integer |
许可证允许的并发用户数。 |
sessionsPerSeat |
integer |
单个用户可同时打开的 SQLly 标签页数。 |
instances |
integer |
可同时运行的桥接数量(联网许可证;离线为 0)。 |
domain |
string? |
绑定的域名;浏览器必须来自此域名或其子域。 |
periodEnd |
string? |
付费期结束时间(ISO 8601 格式)。 |
graceEnd |
string? |
宽限期内的设定值:桥接器停止服务的时间。 |
daysRemaining |
integer? |
距离桥接停止服务还有多少个整天。 |
lastCheckinAt |
string (date-time)? |
|
staleAt |
string (date-time)? |
如果没有一次签到成功,桥接就会失效(最后一次有效授权 + 40 分钟)。 |
licenseFile |
string? |
离线:正在使用的许可证文件。 |
message |
string? |
用户在出现错误时看到的句子(也包括宽限倒计时)。 |
fromCache |
boolean |
当桥接因 sqlly.app 无法访问而基于缓存的授权启动时,此值为 True。 |
features |
string[] |
LinkLicenseRequest
| 字段 | 类型 | 描述 |
|---|---|---|
licenseKey * |
string |
一个以下列内容开头的键 sqe_. |
EngineInfo
| 字段 | 类型 | 描述 |
|---|---|---|
id |
string |
这 engine 值,用于凭据文档。 |
name |
string |
|
defaultPort |
integer |
|
fileBased |
boolean |
server 是文件路径,无需登录。 |
authentication |
string[] |
已接受 authentication.type 数值。 |
ProfileSummary
| 字段 | 类型 | 描述 |
|---|---|---|
id |
string |
|
name |
string |
|
connections |
integer |
文档中的连接数量。 |
updatedAt |
string (date-time) |
StoredProfile
| 字段 | 类型 | 描述 |
|---|---|---|
id |
string |
|
name |
string |
|
credentials |
CredentialDocument |
|
updatedAt |
string (date-time) |
PutProfileRequest
| 字段 | 类型 | 描述 |
|---|---|---|
name * |
string |
显示名称,在 SQLly 中向用户展示。 |
credentials * |
CredentialDocument |
CredentialDocument
一个 SQLly 凭证文档(与 SQLly 的 文件 → 导入连接 相同的格式)。未知的键会报错,因此拼写错误会被报告而不是忽略。完整参考: sqlly.app/docs (凭证文件格式)。
| 字段 | 类型 | 描述 |
|---|---|---|
format * |
sqlly-credentials |
|
version * |
1 |
|
clients |
Label[] |
|
projects |
Label[] |
|
environments |
Label[] |
|
sql_auth_accounts |
SharedLogin[] |
|
tunnel_profiles |
object[] |
|
connections |
Connection[] |
标签
| 字段 | 类型 | 描述 |
|---|---|---|
name * |
string |
|
color |
string |
#RGB、#RRGGBB 或 #RRGGBBAA。 |
image |
string |
图标,使用 data: URI 或纯 base64(PNG、JPEG、GIF、WebP、BMP、ICO、SVG;最大 1 MB)。 |
safety |
object |
只有你列出的标志会发生更改。 |
SharedLogin
| 字段 | 类型 | 描述 |
|---|---|---|
name * |
string |
|
username * |
string |
|
password |
string |
连接
| 字段 | 类型 | 描述 |
|---|---|---|
name * |
string |
|
engine * |
string |
来自 GET /manage/engines 的 ID。 |
server * |
string |
主机、IP、host\instance 或 SQLite/DuckDB 的文件路径。 |
port |
integer |
|
database |
string |
|
environment |
string |
local、dev、test、staging、production 或未设置。 |
client |
string |
客户标签名称。 |
project |
string |
项目标签名称。 |
authentication |
Authentication |
|
tls |
object |
|
timeout_seconds |
integer |
|
statement_timeout_seconds |
integer |
|
application_name |
string |
|
safety |
object |
|
favorite |
boolean |
|
startup_sql |
string |
|
tunnel_profile |
string |
|
transport |
object |
内联的代理、ssh 和 kube 逐级跳转。 |
masking |
object |
{ include: [...], exclude: [...] } 列脱敏规则。 |
身份验证
| 字段 | 类型 | 描述 |
|---|---|---|
type * |
sql-login | integrated | entra-browser | entra-device-code | aws-rds-iam | gcp-cloud-sql-iam | auth-token | none |
|
username |
string |
|
password |
string |
|
account |
string |
sql_auth_accounts 中共享登录的名称。 |
region |
string |
|
profile |
string |
|
token |
string |
MintTokenRequest
| 字段 | 类型 | 描述 |
|---|---|---|
user * |
string |
用户的稳定 ID(无空白字符)。席位按不同用户计算。 |
profile * |
string |
配置文件 ID。 |
ttlSeconds |
integer |
令牌有效期;默认值为 --token-ttl-seconds (600),并被限定在 10 秒到 24 小时之间。 |
open |
LaunchTab | LaunchTab[] |
启动上下文:会话开始时 SQLly 会打开一个查询标签页,最多 8 个。令牌准入的第一个会话会收到它们;刷新和后续会话则不会。签发时会对照配置文件进行验证(400 invalid_open)。用户按下“运行”之前,什么都不会执行。指南: sqlly.app/docs/embedded/launch-context |
启动标签页
每次启动提供一个查询标签页。需要 script、 connection,或者两者都有。
| 字段 | 类型 | 描述 |
|---|---|---|
connection |
string |
令牌配置文件中的连接,通过名称(不区分大小写,必须唯一)或 ID 指定。当配置文件只有一个连接时可选;有多个连接但未指定名称时,标签页将以未绑定状态打开。 |
database |
string |
要切换到的数据库,而不是连接的默认数据库。 |
title |
string |
选项卡标题。 |
script |
string |
要加载的 SQL,原样提供(最多 256 KiB;CRLF 会折叠为 LF)。 |
parameters |
object |
用于脚本 @name 参数,以名称为键(带或不带 @)。裸值的类型会被推断出来(整数推断为 int,其他数字推断为 decimal,布尔推断为 bool,字符串推断为 text,null 推断为空);用 { type, value } 可供选择。脚本未声明的参数会得到一个 -- sqlly param: 行;值会出现在 SQLly 的参数栏中,永远不会由你的应用拼接进去。 |
cursor |
LaunchCursor |
LaunchParameterValue
| 字段 | 类型 | 描述 |
|---|---|---|
type |
text | int | decimal | bool | date | datetime | time | uuid | json | binary |
|
value |
string | number | boolean |
LaunchCursor
光标位于 script,从 1 起算;列按字符计数,可能指向行尾之后再一个位置。
| 字段 | 类型 | 描述 |
|---|---|---|
line |
integer |
|
column |
integer |
MintedToken
| 字段 | 类型 | 描述 |
|---|---|---|
token |
string |
|
expiresAt |
string (date-time) |
|
proxyUrl |
string |
|
user |
string |
|
profile |
string |
|
seatsUsed |
integer |
包括该用户在内的使用中席位数。 |
seats |
integer |
|
openTabs |
integer |
会话将打开的标签页数量(无启动上下文时为 0)。 |
SeatsReport
| 字段 | 类型 | 描述 |
|---|---|---|
seats |
integer |
|
seatsUsed |
integer |
|
users |
UserSeat[] |
用户席位
| 字段 | 类型 | 描述 |
|---|---|---|
user |
string |
|
activeSessions |
integer |
|
tokens |
integer |
未过期的启动令牌。 |
since |
string (date-time) |
测试连接请求
| 字段 | 类型 | 描述 |
|---|---|---|
credentials * |
CredentialDocument |
测试结果
| 字段 | 类型 | 描述 |
|---|---|---|
ok |
boolean |
|
elapsedMs |
integer |
|
message |
string |
引擎自身的消息,成功或失败。 |
查询状态
running 直到引擎响应;然后 completed, failed (参见 error)或 cancelled (由用户,或 session closed).
以下之一: running completed failed cancelled
查询条目
每条请求都有审计记录。
| 字段 | 类型 | 描述 |
|---|---|---|
id |
string |
引擎请求 ID,在其会话内唯一。 |
sessionId |
integer |
桥接器在该浏览器会话中的 ID。 |
kind |
query | row-edit |
|
at |
string (date-time) |
请求到达桥接的时间。 |
user |
string |
启动令牌的用户 ID。 |
profile |
string |
启动令牌的配置文件 ID。 |
profileName |
string |
|
connection |
string |
配置文件中连接的名称。 |
server |
string |
|
database |
string? |
如果该配置固定了数据库,就是它;否则是请求指定的数据库。 |
engine |
string |
引擎的显示名称。 |
sql |
string |
SQL 文本,或 row edit: <op> 用于行编辑。截断到 64 KiB。 |
sqlTruncated |
boolean |
|
status |
QueryStatus |
|
durationMs |
integer? |
运行时为 Null。 |
error |
string? |
引擎的错误提示 failed; session closed 用于因会话结束而被截断的请求。 |
查询列表
| 字段 | 类型 | 描述 |
|---|---|---|
enabled |
boolean |
当桥接以 --query-log false;然后 queries 始终为空。 |
queries |
QueryEntry[] |
最新的在前。 |
total |
integer |
早于以下时间且匹配筛选条件的条目 limit 之前的匹配条目。 |
limit |
integer |
已应用的分页大小(1-1000)。 |
CreateLinkRequest
| 字段 | 类型 | 描述 |
|---|---|---|
name |
string |
在审批页面及其 Embedded 页面上向所有者显示。 |
hostname |
string |
|
appVersion |
string |
CreateLinkResponse
| 字段 | 类型 | 描述 |
|---|---|---|
linkId |
string |
|
code |
string |
将此显示给所有者,以便他们检查是否匹配。 |
secret |
string |
保持在服务器端;它会收集密钥。 |
linkUrl |
string |
打开此项,交由所有者批准。 |
expiresAt |
string (date-time) |
|
pollIntervalSeconds |
integer |
LinkTokenRequest
| 字段 | 类型 | 描述 |
|---|---|---|
linkId * |
string |
|
secret * |
string |
LinkPending
| 字段 | 类型 | 描述 |
|---|---|---|
status |
pending |
|
expiresAt |
string (date-time) |
LinkApproved
| 字段 | 类型 | 描述 |
|---|---|---|
status |
approved |
|
licenseKey |
string |
仅返回一次。将它传递给 PUT /manage/license。 |
keyId |
string |
|
licenseId |
string |
|
plan |
string |
计划 ID,或者 custom. |
planName |
string |
|
accountEmail |
string |
* 必填