API 參考

SQLly Embedded 橋接管理 API 的每個端點,由其 OpenAPI(swagger.json)文件產生,外加 sqlly.app 連結端點。

下載 swagger.json OpenAPI 3.0 版本 1.0.0 基礎 http://127.0.0.1:8445

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

指南: sqlly.app/docs/embedded

慣例

  • 驗證: 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 無權杖

存活探針

管理監聽器一啟動就會回應。不需要權杖;可從啟動腳本和服務健康檢查中使用。

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
}
203 回應範例
{
  "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,或其回覆未能驗證。
203 回應範例
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}
205 回應範例
{
  "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 或其回應未通過驗證。
203 回應範例
{
  "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 管理。
203 回應範例
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}

引擎

憑證格式會宣告它接受的資料庫引擎,因此你的 UI 不必把清單寫死在程式裡。

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"
    ]
  }
]
203 回應範例
{
  "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"
  }
]
203 回應範例
{
  "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。
203 回應範例
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}
204 回應範例
{
  "error": "unknown_profile",
  "message": "no profile with id analysts"
}
PUT /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"
}
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。
203 回應範例
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}
204 回應範例
{
  "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
}
203 回應範例
{
  "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"
    }
  ]
}
203 回應範例
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}
DELETE /manage/seats/{user}

釋放使用者的席位

撤銷使用者的權杖並關閉其工作階段,立即釋放該席位。當使用者登出你的應用程式或失去存取權限時呼叫此端點。釋放未持有席位的使用者不算錯誤。路徑區段已進行百分比解碼: a%2Fb 釋放使用者 a/b.

使用者
路徑 · 字串 · 必填 - 你為其簽發權杖的使用者 ID(URL 編碼)。
204
已發行。
400
bad_request:此段不是有效的百分比編碼。
401
unauthorized:管理權杖遺失或錯誤。
203 回應範例
{
  "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"
}
203 回應範例
{
  "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": [] }.

限制
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 交給橋接器。

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

狀態報告

欄位類型描述
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

* 必填