在查詢上開啟 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,這正是啟動所需的一切。範例應用程式的「查詢」頁面有一個 在 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,
},
});
只提供給應該能在該資料庫上使用工作臺的人,例如開發環境中的成員或管理員。設定檔會決定他們能碰到的範圍,就跟任何其他啟動方式一樣。