API 参考

SQLly Embedded 桥接管理 API 的每个端点,由它的 OpenAPI(swagger.json)文档生成,外加 sqlly.app 的关联端点。

下载 swagger.json OpenAPI 3.0 版本 1.0.0 基础地址 http://127.0.0.1:8445

嵌入模式下的 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.

指南: sqlly.app/docs/embedded

约定

  • 身份验证: 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 无令牌

存活探针

管理监听器一启动即可响应。无需令牌;可从启动脚本和服务健康检查中调用。

200
管理 API 正在监听。
200 响应示例
{
  "ok": true
}

许可证

桥接所运行的许可证:状态、签到、关联与解除关联。

GET /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"
}
POST /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"
}
PUT /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"
}
删除(DELETE) /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"
}

引擎

凭据格式所接受的数据库引擎,这样你的界面就永远不用硬编码这份列表。

GET /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 凭证文档:某一组用户能看到的连接(和标签)。桥接器是记录的权威存储;机密信息永远不会到达浏览器。

GET /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"
}
GET /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"
}
PUT /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"
}
删除(DELETE) /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。席位即并发用户数。

POST /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"
}
GET /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"
}
删除(DELETE) /manage/seats/{user}

释放用户的席位

撤销该用户的令牌并关闭其会话,立即释放席位。当用户在你的应用中登出或失去访问权限时调用。释放未持有席位的用户并不会报错。路径段会进行百分号解码: a%2Fb 会释放用户 a/b.

用户
路径 · 字符串 · 必填 - 你为其签发令牌的用户 ID(URL 编码)。
204
已发布。
400
bad_request:该段不是有效的百分号编码。
401
unauthorized: 管理令牌缺失或有误。
401 响应示例
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}

连接

在任何人使用之前,先验证连接可用。

POST /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.

GET /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 把它交给桥接器。

GET /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

* 必填