API 參考
SQLly Embedded 橋接管理 API 的每個端點,由其 OpenAPI(swagger.json)文件產生,外加 sqlly.app 連結端點。
嵌入模式下的 SQLly 橋接器在其管理監聽器(--manage-bind,預設 127.0.0.1:8445。你的網頁應用程式會從伺服器端呼叫它,用來儲存連線設定檔、測試連線、為登入的使用者簽發啟動權杖、監看席位使用情況,以及讀取或變更授權狀態。
每一個 /manage/... 呼叫需要 Authorization: Bearer <manage token> (橋接器的 --manage-token,至少 16 個字元)。內容進出都是 JSON,最多 8 MB(超過就以 413 too_large 一超過上限就會被斷開)。路徑區段與查詢字串的值會做百分號解碼;無效的跳脫序列會 400 bad_request。錯誤一律是 { "error": "<code>", "message": "<sentence>" },另外還支援 problems 當憑證文件無效時。API 不會傳送任何 CORS 標頭:請將它保留在 loopback 或私人網路中,切勿暴露給瀏覽器,因為設定檔內含資料庫密碼。
這 Linking 操作不在橋接器上:它們是 sqlly.app 的公共端點,管理員應用程式用來將安裝與授權連線,而無需複製金鑰。他們的伺服器是 sqlly.app.
慣例
- 驗證:
Authorization: Bearer <manage token>在每次/manage/…呼叫。缺少或錯誤的權杖會被401 unauthorized./healthz,而 sqlly.app 連結端點則不需要。 - 錯誤 是
{ "error": "<code>", "message": "<sentence>" }。請依據error;顯示message。無效的憑證文件會新增problems,可開啟含圖表儲存格的 Azure Data Studio 筆記本。 - 主體 為 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 本身的負載中是 camelCase。在認證資料文件裡,它們遵循認證資料格式(
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
}
203 回應範例
{
"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,或其回覆未能驗證。
203 回應範例
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
205 回應範例
{
"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 或其回應未通過驗證。
203 回應範例
{
"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 管理。
203 回應範例
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
引擎
憑證格式會宣告它接受的資料庫引擎,因此你的 UI 不必把清單寫死在程式裡。
/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"
]
}
]
203 回應範例
{
"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"
}
]
203 回應範例
{
"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。
203 回應範例
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
204 回應範例
{
"error": "unknown_profile",
"message": "no profile with id analysts"
}
/manage/profiles/{id}
建立或取代設定檔
將設定檔儲存於 id (create or replace)。憑證文件會在寫入任何內容之前完整驗證:解析器找到的每個問題都會出現在 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:無法寫入狀態目錄。
202 回應範例
{
"error": "invalid_profile",
"message": "the credential document has 2 problems",
"problems": [
"connections[0].engine: unknown engine \"postgress\"",
"connections[1].authentication.pasword: unknown key"
]
}
203 回應範例
{
"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。
203 回應範例
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
204 回應範例
{
"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
}
203 回應範例
{
"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"
}
]
}
203 回應範例
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
/manage/seats/{user}
釋放使用者的席位
撤銷使用者的權杖並關閉其工作階段,立即釋放該席位。當使用者登出你的應用程式或失去存取權限時呼叫此端點。釋放未持有席位的使用者不算錯誤。路徑區段已進行百分比解碼: a%2Fb 釋放使用者 a/b.
- 使用者
- 路徑 · 字串 · 必填 - 你為其簽發權杖的使用者 ID(URL 編碼)。
- 204
- 已發行。
- 400
bad_request:此段不是有效的百分比編碼。- 401
unauthorized:管理權杖遺失或錯誤。
203 回應範例
{
"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"
}
203 回應範例
{
"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": [] }.
- 限制
- query · 整數 - 要傳回的項目數,限制在 1-1000 之間。
- 使用者
- query · 字串 - 僅限此使用者 ID(完全相符,URL 編碼)。
- 設定檔
- query · 字串 - 僅限此設定檔 ID(完全相符)。
- 自
- query · 字串(日期時間)- 僅限其
at在此 RFC 3339 時間戳記或之後(以 URL 編碼)。 - 狀態
- query · 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'."
}
]
}
203 回應範例
{
"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
狀態報告
| 欄位 | 類型 | 描述 |
|---|---|---|
version |
string |
橋接版本。 |
instanceId |
string |
此橋接器處理程序的 ID,以 sqlly.app 所見為準。 |
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). |
LicenseReport
用量來自經簽署的授權,絕不來自未簽署的資料。
| 欄位 | 類型 | 描述 |
|---|---|---|
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 而改用快取的授權啟動時,此值為真。 |
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 |
可串接 proxy、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[] |
啟動內容:一個查詢分頁,或最多 8 個,是 SQLly 在工作階段開始時開啟的分頁。權杖核可的第一個工作階段會收到它們;重新載入與後續的工作階段則不會。簽發時會對設定檔驗證(400 invalid_open。在使用者按下執行按鈕之前,什麼都不會執行。指南: sqlly.app/docs/embedded/launch-context |
LaunchTab
一次啟動的一個查詢分頁。需要一個 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 由其工作階段結束而中斷的請求。 |
QueryListing
| 欄位 | 類型 | 描述 |
|---|---|---|
enabled |
boolean |
當橋接執行時若為 False,表示帶有 --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 |
* 必填