在查詢上開啟 SQLly

直接啟動 SQLly 進入查詢分頁:腳本、其連線與資料庫、參數值與游標位置,會隨「在 SQLly 中開啟」按鈕的啟動權杖一併送出。

啟動權杖通常會開啟空白的工作台。簽發時加入 open 欄位,SQLly 就會直接開啟一或多個查詢分頁:腳本已載入、分頁已連上正確的伺服器與資料庫、你的參數值已填好、游標停在你放的位置。這樣一來,你的應用程式裡任何顯示 SQL 的地方都能放「在 SQLly 開啟」按鈕:報表旁邊、失敗的查詢上、稽核軌跡裡。

不會自動執行任何東西。 啟動只會載入分頁。瀏覽器端的人要逐條檢查查詢並按下執行,和 SQLly 桌面查詢連結遵循同一條規則。沒有任何辦法讓啟動直接執行 SQL。

簽發帶啟動內容的權杖

這是一樣的 POST /manage/tokens 呼叫,就像任何啟動一樣(建立你自己的應用程式的第 4 步),並多一個欄位:

shell
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/false bool,字串 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 中重新開啟 按鈕,每個完整陳述式上都有。它會再次向橋接器查找該資料列(表單只給資料列名稱,沒有別的),然後用這個上下文簽發一個管理員啟動:

javascript
const 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,
  },
});

只提供給應該能在該資料庫上使用工作臺的人,例如開發環境中的成員或管理員。設定檔會決定他們能碰到的範圍,就跟任何其他啟動方式一樣。