独自のアプリをビルド
手順どおりに進めるガイド: 自分のウェブアプリから 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、セッション |
| 誰がどの接続を見られるかを決める | 各ユーザーには 1 つのプロファイルが割り当てられます | ロール、チーム、テナント、プランがプロファイルIDを決めます |
| 接続を定義する | プロファイルエディター、ラベルタブ(lib/credentials.js ドキュメントを作成します) | 管理UI、設定ファイル、またはテナントデータからドキュメントを生成するコード |
| SQLly を開く | GET /app/ トークンを発行し、それを次に注入します index.html | 同じことを 1 つのルートで行う(ステップ4) |
| ウェブバンドルを配信 | /app/* 分離ヘッダーを使って | 同じヘッダーを付けた、静的ファイルサーバーまたはCDNのパス(ステップ5) |
| シートの解放 | ユーザーページ、 シートを解放 | サインアウト時とアクセス削除時に呼び出します (ステップ6) |
| ライセンスの状態を表示 | ステータスページ | ヘルスチェックや管理用ウィジェット(ステップ7) |
| ライセンスにリンク | sqlly.app に接続 | 省略可: キーまたはライセンスファイルを設定することもできます(ステップ8) |
1. お使いのアプリの横でブリッジを実行
起動スクリプトを使わない場合、ブリッジはコマンド 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。ブラウザーはプロキシリスナーに接続します(: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 そして、その接続1つだけを保持するドキュメント。失敗は次の形で返されます { "ok": false, "message": "<the engine's own error>" } HTTP 200 で、フォームの横にそのまま表示できる状態です。
4. サインイン済みユーザーで SQLly を起動する
これは、すべての連携に必要な唯一のルートです。サインイン済みのユーザーが SQLly を開いたら、そのユーザー向けにトークンを発行し、バンドルに含まれる次のものを返します index.html 2 つのグローバルを設定して の前に その boot.js モジュールタグ:
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 分。指定するには
ttlSeconds10~86,400 の間)。 - 再利用は問題ありません。 トークンは有効期限が切れるまで使えるため、ページを再読み込みしても新しいトークンは不要です。サンプルアプリは各ユーザーのトークンをキャッシュし、有効期限の 1 分前に再発行します。同じユーザーに対して再発行しても、別のシートを消費することはありません。
- ワークベンチだけでなく、クエリも開けます。 追加
openmint 呼び出しに渡すと、スクリプト、接続、パラメータ値、カーソルが設定済みの状態でユーザーをクエリタブに誘導します。こうした起動のたびに新しいトークンを発行してください。タブが開くのは、トークンが開始した最初のセッションだけです。 クエリを指定して SQLly を開く. - ユーザー ID は開発者側のものです。 安定していて内容を推測できない ID を渡してください。シート数はユニークな ID の数で数えられ、シートを占有した ID はチェックイン時に sqlly.app に報告されます。
- HTML を編集できない場合は、次を渡してください
?proxy=<url>&token=<token>代わりにページ URL に渡す方法もあります。ただし注入のほうが望ましく、トークンが履歴やログに残りません。 - ページは次の文字で終わる URL で配信します
/(ここ/sqlly/)にします。そうすれば、バンドルの相対的な./boot.js手元のコピーに解決されますweb/.
5. Web バンドルを配信する
次のファイルを配信します 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。ここでは圧縮が非常に有効です。wasm ファイルは Brotli や gzip で数分の1に縮みます。- ページが 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 byspill-worker.js, a worker script, which nonces don't cover: allow it with'self'内worker-src(or inscript-src、これはworker-srcfalls back to). If it is blocked, large results stay in memory. - クロスオリジン分離はページが読み込むすべてのものに適用されるため、CORP ヘッダーのないサードパーティの CDN ではなく、自分のオリジンからバンドルを配信してください。
バンドルのファイルはパッケージと同じバージョン番号を持ちます。アップグレード時には、次を置き換えます web/ とブリッジの組み合わせです。
6. シートを管理する
409 seat_limitが mint を返すとき、全席が使用中です。そのことをユーザーにはっきり伝え、管理者には 1 席を解放する選択肢を提示します。GET /manage/seatsは、誰がいつからシートを使用しているかを一覧表示します。- サインアウト時に解放:
DELETE /manage/seats/{user}ユーザーのトークンを無効にし、その SQLly タブを閉じます。誰かのアクセス権を削除するときも同じようにしてください。そうしないと、そのトークンは有効期限が切れるまで使えてしまいます。 - 次を超える余分なタブは
sessionsPerSeatはブリッジ自体によって拒否されます。ソケットには「<user> already has the maximum number of SQLly sessions open」と通知され、コード 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 「renew this week」のように。 POST /manage/license/checkin チェックインを強制し(またはオフラインファイルを再読み込みし)、次のような場合に便利です 今すぐチェックイン ネットワークアクセスを修正した後のボタン。 各状態の意味.
8. 管理者UIからライセンスへのリンク(オプション)
キーまたはライセンスファイルでブリッジを設定すれば、この手順は省略できます。リンクは、多くの顧客に SQLly Embedded をインストールする製品のための機能です。各顧客の管理者は、自分のインストールを次の接続先にリンクします それら自身の sqlly.app のライセンスは数回のクリックで紐づけられ、キーをコピーすることは一切ありません。次のどちらも指定せずにブリッジを起動します --license-key も、 --license-file、その後:
POST https://sqlly.app/api/embedded/links表示名を付けます (例:"SQLly Embedded on " + hostname)。返されたsecretサーバー側に保管しておきます。管理者には次のcode、そしてそれらを送信しますlinkUrl.- 管理者は sqlly.app にサインインし、コードが一致することを確認し、ライセンスを選んで承認します。
- その間は
POST https://sqlly.app/api/embedded/links/tokenを伴う{ linkId, secret }すべてpollIntervalSeconds。次に応答します202保留中は、その後2001 回、次のものでlicenseKey.410最初からやり直しを意味します(拒否、期限切れ、または使用済み)。 - キーをそのままブリッジに渡します:
PUT /manage/license { "licenseKey": "…" }。ブリッジは保存する前に sqlly.app でそれを検証し、再起動後も保持し、ステータスには次が表示されますlicense.source: "linked"。キーを自分で保存しないでください。 - 接続を解除するには、
DELETE /manage/license: ブリッジはスロットを解放し、sqlly.app 上のキーを失効させ、ライセンスなしの状態に戻ります。
サンプルアプリの lib/sqllyapp.js およびその /admin/link ルートはまさにこれを実装しています。
リリース前に
- 管理トークンはサーバー側の設定に置かれ、管理 API はループバックまたはプライベート ネットワークにバインドされます。
- 起動はすべて、認証済みユーザーに対してサーバー側で発行され、承認ルールが選択したプロファイルが適用されます。
- SQLly のページとバンドルが分離用ヘッダーを返し、CSP がブリッジの
wss://オリジン。 - サインアウトとアクセス削除により、そのユーザーのシートが解放されます。
seat_limitそしてlicense_not_okスタックトレースではなく、人が読めるメッセージを表示します。- 監視が必要なのは
GET /manage/status. - 次のドキュメントを読んでいること: 本番運用へ.