建立你自己的應用程式

逐步教學:從你自己的網頁應用程式操控 SQLly Embedded 橋接器——儲存設定檔、簽發啟動權杖、代管瀏覽器版、釋放席位並綁定安裝。

範例應用程式是你產品的替身。它做的每一件事都會經過橋接程式的 管理 API,所以任何伺服器端堆疊都能取代它:Node、ASP.NET、Django、Rails、Go、PHP。本頁會逐步走過範例應用程式做的每一項工作,以及如何在你自己的應用程式裡完成。範例以 JavaScript (Node 20+) 和 C# (ASP.NET Core) 撰寫,同樣的呼叫在任何說得出 HTTP 和 JSON 的環境都適用。

直接產生用戶端,不必自己手寫。 swagger.json 是整個管理 API 的 OpenAPI 3.0 描述。把它交給 openapi-generator、NSwag、Kiota 或你順手的 HTTP 工具。範例應用程式的 sample-app/lib/bridge.js 也是一個完整的手寫客戶端,大約 120 行。

你的應用程式接管的部分

作業在範例應用程式中在你的應用程式中
讓使用者登入它自己的使用者檔案,使用 scrypt 密碼 (lib/auth.js)你現有的登入、SSO、工作階段
決定誰可以看到哪些連線每個使用者都會被指派一個設定檔你的角色、團隊、租用戶或方案決定設定檔 ID
定義連線設定檔編輯器,「標籤」分頁(lib/credentials.js 建立這份文件)你的管理介面、設定檔,或是以你的租用戶資料建立文件的程式碼
開啟 SQLlyGET /app/ 會簽發一個權杖並把它注入 index.html一個路由即可做到同樣的事(步驟 4)
提供網頁封裝/app/* 使用隔離標頭你的靜態檔案伺服器或具備相同標頭的 CDN 路徑 (步驟 5)
免費席位使用者頁面, 釋放席位在登出時以及移除存取時呼叫它(步驟 6)
顯示授權狀態狀態頁面健康檢查或管理小工具(步驟 7)
連結到授權連線到 sqlly.app可選:或者設定金鑰或授權檔案(步驟 8)

1. 在你的應用程式旁邊執行橋接程式

沒有啟動腳本的話,橋接器只要一個命令。管理權杖產生一次,把同一個值交給橋接器和你的應用程式(環境變數或機密存放庫,絕不放進你的儲存庫):

export SQLLY_EMBEDDED_MANAGE_TOKEN="$(openssl rand -base64 24)"
export SQLLY_EMBEDDED_LICENSE_KEY=sqe_…        # or SQLLY_EMBEDDED_LICENSE_FILE, or neither and link later

./bin/sqlly-bridge embedded \
  --domain portal.example.com \
  --public-url wss://portal.example.com/sqlly/proxy \
  --manage-bind 127.0.0.1:8445 \
  --state-dir /var/lib/sqlly-embedded

你的應用程式會與 http://127.0.0.1:8445 與 Authorization: Bearer $SQLLY_EMBEDDED_MANAGE_TOKEN。瀏覽器會連到 Proxy 監聽器(:8444)透過你的反向代理。 正式環境詳細資料.

2. 一個小型管理用戶端

javascript (node 20+)
const BRIDGE = process.env.SQLLY_BRIDGE_URL ?? 'http://127.0.0.1:8445';
const TOKEN = process.env.SQLLY_EMBEDDED_MANAGE_TOKEN;

export async function bridge(method, path, body) {
  const res = await fetch(BRIDGE + path, {
    method,
    headers: {
      authorization: `Bearer ${TOKEN}`,
      ...(body ? { 'content-type': 'application/json' } : {}),
    },
    body: body ? JSON.stringify(body) : undefined,
  });
  if (res.status === 204) return null;
  const json = await res.json().catch(() => null);
  if (!res.ok) {
    // Every error is { error, message } (+ problems for invalid documents).
    throw Object.assign(new Error(json?.message ?? `bridge HTTP ${res.status}`),
      { code: json?.error, status: res.status, problems: json?.problems });
  }
  return json;
}
c# (asp.net core)
builder.Services.AddHttpClient("sqlly-bridge", c =>
{
    c.BaseAddress = new Uri(builder.Configuration["Sqlly:BridgeUrl"] ?? "http://127.0.0.1:8445");
    c.DefaultRequestHeaders.Authorization =
        new("Bearer", builder.Configuration["Sqlly:ManageToken"]);
});

public sealed record BridgeError(string Error, string Message, string[]? Problems);
public sealed record MintedToken(string Token, DateTimeOffset ExpiresAt, string ProxyUrl,
    string User, string Profile, int SeatsUsed, int Seats);

3. 儲存設定檔

設定檔是一個 SQLly 憑證文件 外加一個顯示名稱。要怎麼建立都行:從你資料庫裡的資料列、從各租戶專屬的範本,或從管理表單。 GET /manage/engines 列出每個引擎 ID、其預設連接埠以及接受的登入類型,這樣表單就不會寫死它們。

await bridge('PUT', '/manage/profiles/acme-analysts', {
  name: 'Acme analysts',
  credentials: {
    format: 'sqlly-credentials',
    version: 1,
    clients: [{ name: 'Acme', color: '#1E88E5' }],
    environments: [{ name: 'Production', safety: { only_allow_select: true } }],
    sql_auth_accounts: [{ name: 'Reader', username: 'acme_ro', password: secrets.acmeReader }],
    connections: [
      { name: 'Orders', engine: 'postgres', server: 'pg1.internal', database: 'orders',
        environment: 'production', client: 'Acme',
        authentication: { type: 'sql-login', account: 'Reader' }, tls: { mode: 'verify-full' } },
    ],
  },
});
  • 設定檔 ID 範圍為 1-64 的 A-Z a-z 0-9 _ -。使用你自己的穩定識別碼(租用戶 ID、角色名稱)。
  • 橋接器會在儲存前驗證整份文件。格式錯誤的文件會傳回 400 invalid_profile 與 problems 會列出每一個錯誤。未知鍵一律算錯誤,所以打錯字也逃不掉。
  • 橋接器是機密資料的權威儲存庫。真實來源你想放哪裡都行,但每次變更都要重新PUT 設定檔。範例應用程式在啟動時會重新傳送每個設定檔,因此新的狀態目錄會自行重新填入。
  • 使用標籤與安全旗標。 only_allow_select 在生產環境中,或者 confirm_data_changes 在連線上設定的內容,SQLly 會對所有開啟該設定檔的人強制執行。

在儲存之前,你可以使用 POST /manage/test-connection 以及一份只含該連線的文件。失敗會回傳為 { "ok": false, "message": "<the engine's own error>" } 並附帶 HTTP 200,準備顯示在表單旁。

4. 為已登入的使用者啟動 SQLly

這是每個整合都必備的路由:當已登入的使用者開啟 SQLly 時,替他們簽發權杖,並回傳套件的 index.html 在兩個全域變數都設定的情況下 在 這 boot.js 模組標籤:

javascript(express-style)
import { readFile } from 'node:fs/promises';

const ISOLATION = {
  'Cross-Origin-Opener-Policy': 'same-origin',
  'Cross-Origin-Embedder-Policy': 'require-corp',
};
const BOOT_TAG = '<script type="module" src="./boot.js"></script>';
// JSON for an inline script: never let a value close the tag.
const js = (v) => JSON.stringify(v).replace(/</g, '\\u003c');

app.get('/sqlly/', requireSignIn, async (req, res) => {
  const profile = profileFor(req.user);              // your rule: role, team, tenant…
  let minted;
  try {
    minted = await bridge('POST', '/manage/tokens', { user: req.user.id, profile });
  } catch (err) {
    if (err.code === 'seat_limit') return res.status(409).send('All SQLly seats are in use right now.');
    if (err.code === 'license_not_ok') return res.status(503).send(err.message);
    throw err;
  }
  const html = (await readFile('web/index.html', 'utf8')).replace(BOOT_TAG,
    `<script>globalThis.SQLLY_PROXY_URL=${js(minted.proxyUrl)};` +
    `globalThis.SQLLY_PROXY_TOKEN=${js(minted.token)};</script>` + BOOT_TAG);
  res.set(ISOLATION).set('Cache-Control', 'no-store').type('html').send(html);
});
c#(asp.net core minimal api)
app.MapGet("/sqlly/", async (HttpContext http, IHttpClientFactory clients, IWebHostEnvironment env) =>
{
    var user = http.User.FindFirst("sub")!.Value;
    var bridge = clients.CreateClient("sqlly-bridge");
    var reply = await bridge.PostAsJsonAsync("/manage/tokens", new { user, profile = ProfileFor(http.User) });
    if (!reply.IsSuccessStatusCode)
    {
        var error = await reply.Content.ReadFromJsonAsync<BridgeError>();
        return Results.Text(error?.Message ?? "SQLly is unavailable.", statusCode: (int)reply.StatusCode);
    }

    var minted = (await reply.Content.ReadFromJsonAsync<MintedToken>())!;
    const string bootTag = "<script type=\"module\" src=\"./boot.js\"></script>";
    // JsonSerializer escapes < > & by default, so the values can't close the tag.
    var globals = $"<script>globalThis.SQLLY_PROXY_URL={JsonSerializer.Serialize(minted.ProxyUrl)};" +
                  $"globalThis.SQLLY_PROXY_TOKEN={JsonSerializer.Serialize(minted.Token)};</script>";
    var html = (await File.ReadAllTextAsync(Path.Combine(env.ContentRootPath, "sqlly-web", "index.html")))
        .Replace(bootTag, globals + bootTag);

    http.Response.Headers["Cross-Origin-Opener-Policy"] = "same-origin";
    http.Response.Headers["Cross-Origin-Embedder-Policy"] = "require-corp";
    http.Response.Headers.CacheControl = "no-store";
    return Results.Content(html, "text/html");
}).RequireAuthorization();
  • 在伺服器端依每次請求簽發。 永遠不要將管理權杖放在頁面中。啟動權杖可以安全地交給它所簽發對象的使用者:它只會以該使用者的設定檔開啟 SQLly,並且會過期(預設為 10 分鐘;傳入 ttlSeconds 在 10 到 86,400 之間)。
  • 重複使用沒問題。 權杖在到期前都有效,所以重新載入頁面不需要新的權杖。範例應用程式會快取每個使用者的權杖,並在到期前一分鐘重新簽發。為同一位使用者重新簽發權杖,絕不會多佔一個席位。
  • 直接開到查詢,而不只是工作臺。 新增 open 傳給 mint 呼叫,使用者就會直接進入已設定好腳本、連線、參數值與游標的查詢分頁。這些啟動每一次都要 mint 一個全新的權杖:分頁只會在該權杖啟動的第一個工作階段開啟。 在查詢上開啟 SQLly.
  • 使用者 ID 由你決定。 請傳遞穩定且不含個資的 ID。席位以不重複的 ID 計算,持有席位的 ID 會在簽入時回報給 sqlly.app。
  • 如果你無法編輯 HTML,請傳遞 ?proxy=<url>&token=<token> 在頁面 URL 上。注入會比較好,因為權杖不會留在歷史記錄和記錄檔中。
  • 在結尾如下的 URL 提供頁面 / (此處 /sqlly/),這樣套件的相對 ./boot.js 就會解析到你自己的副本 web/.

5. 提供網頁套件

提供下列目錄中的檔案 web/ 在與啟動頁相同的路徑下(/sqlly/boot.js, /sqlly/sqlly_browser_bg.wasm,…),包括:

  • Cross-Origin-Opener-Policy: same-origin 和 Cross-Origin-Embedder-Policy: require-corp 要加在頁面和每個套件檔案中。SQLly 需要 SharedArrayBuffer,而瀏覽器只會在隔離的頁面上才啟用它。
  • application/wasm 作為型別,用於 .wasm。壓縮在這裡幫助很大:用 Brotli 或 gzip 一壓,wasm 檔案能縮小好幾倍。
  • 如果你的頁面傳送 Content-Security-Policy: 'wasm-unsafe-eval' 在 script-src,橋接器的 wss:// 來源在 connect-src, and a nonce or hash on the inline globals script (or the query-parameter form above). Large results are kept in browser storage by spill-worker.js, a worker script, which nonces don't cover: allow it with 'self' 在 worker-src (or in script-src,該 worker-src falls back to). If it is blocked, large results stay in memory.
  • 跨來源隔離適用於頁面載入的所有內容,因此請從你自己的來源提供套件,而不是使用沒有 CORP 標頭的第三方 CDN。

套件組合中的檔案版本與套件本身一致。升級時,請替換 web/ 以及橋接器一併設定。

6. 處理席次

  • 409 seat_limit 在 mint 上表示每個席位都已被使用。明確告訴使用者,並為管理員提供釋放其中一個的選項。 GET /manage/seats 會列出誰佔用了席次,以及從什麼時候開始。
  • 登出時釋放: DELETE /manage/seats/{user} 會撤銷使用者的權杖並關閉其 SQLly 分頁。當你移除某人的存取權時,也請照做。否則對方的權杖會持續有效,直到到期為止。
  • 超過 sessionsPerSeat 會被橋接本身拒絕:socket 收到「<user> 已經開啟了最大數量的 SQLly 工作階段」的訊息並以代碼 4429 關閉,SQLly 會顯示這句話。

7. 顯示授權健康狀態

GET /manage/status 擁有管理小工具或健康檢查所需的一切:

const s = await bridge('GET', '/manage/status');
// s.license.state: ok | grace | stale | not_admitted | expired | revoked | domain_mismatch | unlicensed
// s.license.message: the sentence your users see when something is wrong
// s.license.daysRemaining, s.license.planName, s.seatsUsed / s.license.seats
const healthy = ['ok', 'grace'].includes(s.license.state);

發出警示,除非狀態為 ok,並把 grace 為「本週續約」。 POST /manage/license/checkin 會強制簽入(或重新讀取離線檔案),適合 立即簽到 按鈕,在修好網路存取之後。 每個狀態代表什麼.

8. 從你的管理介面連結至授權(可選)

你可以用金鑰或授權檔設定橋接器,跳過這個步驟。綁定是給為多個客戶安裝 SQLly Embedded 的產品用的:每位客戶的管理員會把自己安裝的執行個體連到 他們自己的 sqlly.app 授權只要幾下點擊就能啟用,而且金鑰永遠不會被複製。啟動橋接器時,兩個旗標都不要加 --license-key 也不 --license-file,然後:

  1. POST https://sqlly.app/api/embedded/links 使用顯示名稱(例如 "SQLly Embedded on " + hostname。保留傳回的 secret 儲存在伺服器端。向管理員顯示 code ,並傳送到 linkUrl.
  2. 管理員登入 sqlly.app,確認配對碼相符,選擇授權並核准。
  3. 在此期間,持續輪詢 POST https://sqlly.app/api/embedded/links/token 與 { linkId, secret } 每個 pollIntervalSeconds。它會回應 202 當待處理時,然後 200 一次,用 licenseKey. 410 表示重新開始(被拒、已過期或已使用)。
  4. 把金鑰直接交給橋接器: PUT /manage/license { "licenseKey": "…" }。橋接程式會先用 sqlly.app 驗證它,儲存起來,並跨重新啟動保留,狀態頁會顯示 license.source: "linked"。不要自己儲存金鑰。
  5. 要中斷連線, DELETE /manage/license:橋接器會釋放它的席次、撤銷 sqlly.app 上的金鑰,並回到未授權狀態。

範例應用程式的 lib/sqllyapp.js 及其 /admin/link 路由正是實現了這一點。

在發布之前

  • 管理權杖存放在伺服器端設定中,而管理 API 只繫結到 loopback 或私人網路。
  • 每次啟動都是在伺服器端為已驗證的使用者簽發,使用你的授權規則所選擇的設定檔。
  • SQLly 頁面和套件攜帶隔離標頭,而你的 CSP 允許橋接器的 wss:// 來源。
  • 登出與存取移除會釋放使用者的席位。
  • seat_limit 和 license_not_ok 顯示給人看的訊息,而不是堆疊追蹤。
  • 有東西在監看 GET /manage/status.
  • 你已經讀過 正式上線.