打开 SQLly 并定位到查询
启动 SQLly 并直接进入查询标签页:脚本、对应的连接和数据库、参数值和光标位置,随“在 SQLly 中打开”按钮的启动令牌一起发送。
并发游标数量确实很高,而上限设得太低。 open 字段,SQLly 就会直接打开一个或多个查询标签页:脚本已加载,标签页已连接到正确的服务器和数据库,你的参数值已填好,光标放在你指定的位置。这样可以在应用显示 SQL 的任何地方提供“在 SQLly 中打开”按钮:在报表旁边、在失败的查询上、在审计日志中。
没有任何东西会自动运行。 启动令牌只会加载标签页。浏览器中的用户会检查每个查询并按下运行按钮,这与 SQLly 桌面查询链接的规则相同。无法通过启动令牌执行 SQL。
签发带启动上下文的令牌
是一样的 POST /manage/tokens 调用与任意启动相同(构建你自己的应用的第 4 步),多了一个额外的字段:
curl -s -X POST -H "Authorization: Bearer $SQLLY_EMBEDDED_MANAGE_TOKEN" \
-H 'content-type: application/json' http://127.0.0.1:8445/manage/tokens -d '{
"user": "dana.analyst",
"profile": "analysts",
"open": {
"connection": "Shop",
"database": "sales",
"title": "Big orders",
"script": "SELECT *\nFROM orders\nWHERE total > @min_total AND placed_at >= @since",
"parameters": { "min_total": 500, "since": { "type": "date", "value": "2026-10-01" } },
"cursor": { "line": 3, "column": 7 }
}
}'
回复是常规的令牌加上 openTabs,即该会话将打开的标签页数量:
{ "token": "…", "expiresAt": "2026-10-18T15:12:11Z", "proxyUrl": "wss://portal.example.com/sqlly/proxy",
"user": "dana.analyst", "profile": "analysts", "seatsUsed": 3, "seats": 25, "openTabs": 1 }
像普通启动一样把令牌交给页面。用户到达时,SQLly 会连接到 Shop,然后切换到 sales,并显示一个名为“Big orders”的标签页,里面的查询已加载,参数条填着 500 和 2026-10-01,光标停在第三行。
标签页可以承载的内容
open 是一个对象,要开多个标签页时则是一个最多 8 个对象的列表。第一个对象会获得焦点。所有字段都是可选的,但每个条目至少要有脚本或连接之一。
| 字段 | 类型 | 含义 |
|---|---|---|
connection | 字符串 | 令牌配置文件中的一个连接,可以按名称(不区分大小写)或按其 ID 指定。当配置文件只有一个连接时可忽略此项。如果有多个连接且都未命名,标签页会在未选择连接的情况下打开。 |
database | 字符串 | 要切换到的数据库,而不是连接的默认数据库。最多 128 个字符。 |
title | 字符串 | 选项卡的标题。最多 120 个字符。不提供时,SQLly 会按通常方式为选项卡命名。 |
script | 字符串 | 要加载的 SQL,原样提供。最多 256 KiB。Windows 换行符会被折叠为 \n. |
parameters | 对象 | 用于脚本 @name 参数,最多 64 个。请参见 参数. |
cursor | { line, column } | 光标的目标位置,行和列都从 1 开始计数,列以字符计。必须落在脚本内部(允许指向一行末尾之后的下一列)。 |
参数
SQLly 有带类型的查询参数:一个 -- sqlly param: @name <type> 行会声明一个参数,结果上方的一条栏会保存它的值。启动参数用的也是同一条栏,所以你的值会显示为可见、可编辑的输入框,而语句本身则按你发送的原样加载。
- 名称使用
@name,在每个引擎上都适用。发送密钥时,可以带或不带@("min_total"和"@min_total"都是一样的。名称是一个字母或_后跟字母、数字或_,最多 64 个字符,而且只能出现一次(不区分大小写)。如果你的应用用另一种方式写参数($name,:name,?),并将它们重写为@name当你生成脚本时。 - 一个普通值 会从 JSON 判断其类型:整数是
int,其他数字为decimal,true/falsebool,字符串text,以及null留空供用户填写。 - 输入的值 是
{ "type": "date", "value": "2026-10-01" }。类型为text,int,decimal,bool,date,datetime,time,uuid,json和binary。以字符串形式发送 JSON 文档,使用"type": "json". - 声明会自动帮你加上。 对于每个脚本未声明的参数,SQLly 会添加一个
-- sqlly param:行会插到脚本上方,光标会随脚本一起下移。脚本已声明的参数会保留脚本里的声明和类型,并采用你填入的值。 - 值如何进入数据库。 当用户按下运行时,SQLly 会按类型检查每个值,并把每个
@name在字符串和注释之外的位置替换为按该引擎语法正确书写的字面值,然后发送语句。值不符合其类型时,运行会停止并聚焦到对应的输入框。你的应用从不把值直接拼接进 SQL 文本。
一次启动,一个令牌
- 选项卡只打开一次。 桥接器会把它们交给第一个使用该令牌的 SQLly 会话,然后就把它们忘掉。重新加载页面会恢复 SQLly 保存在浏览器中的工作台,因此标签页不会被打开两次。令牌本身在过期前一直有效。
- 每次点击“在 SQLly 中打开”都会签发一个全新的令牌。 不要为带上下文的启动复用缓存的令牌:那样将什么都打不开。已持有席位的用户生成新令牌不会额外占用席位。
- 每次点击都会打开一个新标签页。 它会占用用户的
sessionsPerSeat(付费版四个,试用版一个)。试用版下,用户必须先关掉自己其他的 SQLly 标签页,否则新会话会被拒绝,提示“<user> 已经打开了最大数量的 SQLly 会话”。 - 上下文在令牌签发时固定 - 与配置文件相同。连接按配置文件当时的状态解析。
错误会在签发时被拦下
桥接器会检查整个 open 值之后才会创建令牌,这样你的服务器能立即发现问题,而不是让用户碰上一个坏掉的标签页。糟糕的值会得到 400 invalid_open 为每处错误在 problems 每个错误各有一条消息,并指出其位置。不会签发任何令牌,也不会占用任何席位:
{
"error": "invalid_open",
"message": "the launch context has 3 problems",
"problems": [
"open[0].connection: no connection \"Shopp\" in this profile (it has: Shop, Warehouse)",
"open[0]: unknown field \"sql\" (allowed: connection, database, title, script, parameters, cursor)",
"open[1].cursor: line 9 is past the end of the script (3 lines)"
]
}
未知字段会被拒绝而不是被忽略,因此像 sql 用于 script 会直接报错。类型为 int, decimal 和 bool 也会被检查。其他类型则由 SQLly 的参数栏在查询运行前检查。
配方
从审计轨迹重新打开查询
这 查询审计跟踪 记录每个查询及其配置文件、连接、数据库和 SQL,这正是启动所需的全部信息。示例应用的 Queries 页面有一个 在 SQLly 中重新打开 按钮会出现在每条完整语句上。它会再次在桥上查询该行(表单只提供该行的名字,别的什么都不带),然后用这个上下文签发一个管理员启动:
javascriptconst entry = (await bridge('GET', '/manage/queries?limit=1000')).queries
.find((q) => String(q.sessionId) === form.session && q.id === form.id);
if (!entry || entry.kind === 'row-edit' || entry.sqlTruncated) return refuse();
const open = {
connection: entry.connection,
title: `${entry.status === 'failed' ? 'Failed' : 'Query'} from ${entry.user}`,
script: entry.sql,
};
if (entry.database) open.database = entry.database;
const minted = await bridge('POST', '/manage/tokens', { user: `admin:${admin.id}`, profile: entry.profile, open });
记录下来的 SQL 就是实际执行的语句,因此参数值已经以字面量的形式写在其中,不再需要参数。对于执行失败的语句,示例应用还会读取引擎指出的出错位置(PostgreSQL 的 POSITION: 53,MySQL 的“在第 2 行”)然后把它作为 cursor,所以光标会落在出问题的列上。
你应用错误页面上的“在 SQLly 中打开”
如果你的应用程序自己会运行 SQL(报表生成器、SQL 驱动的页面框架、计划任务),那么在语句失败的那一刻,它就知道那是哪条语句、绑定了哪些值、跑在哪个数据库上。在错误页面上放一个按钮,用它生成一次启动:带上这条语句、以参数形式带入它的值,并把光标停到数据库报错的那一行。开发者会得到一个针对这条查询的完整工作台,配有 IntelliSense、对象资源管理器和执行计划,无需手动复制任何内容:
javascript// failure = { sql: 'SELECT … WHERE id = $id', params: { id: 42 }, line: 3 }
const script = failure.sql.replace(/\$([A-Za-z_]\w*)/g, '@$1'); // $id → @id
const minted = await bridge('POST', '/manage/tokens', {
user: req.user.id,
profile: 'app-database', // a profile pointing at the app's own database
open: {
title: 'Failed statement',
script,
parameters: failure.params,
cursor: failure.line ? { line: failure.line, column: 1 } : undefined,
},
});
只把它提供给应该能在该数据库上使用工作台的人,例如开发环境成员或管理员。他们能访问什么由配置文件决定,和其他任何启动方式完全一样。