직접 앱 만들기
단계별 안내: 자체 웹 앱에서 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 가 문서를 생성합니다) | 관리자 UI, 구성 파일, 또는 테넌트 데이터로 문서를 만드는 코드 |
| SQLly 열기 | GET /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. 브라우저는 프록시 리스너(:8444) 리버스 프록시를 통해 전달됩니다. 프로덕션 세부 정보.
2. 작은 관리 클라이언트
자바스크립트 (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 모듈 태그:
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분 전에 다시 발급합니다. 동일한 사용자에게 다시 발급하더라도 추가 좌석 비용은 들지 않습니다.
- 워크벤치만이 아니라 쿼리를 바로 엽니다. 추가
open를 민트 호출에 넘기면 사용자가 스크립트, 연결, 매개변수 값, 커서가 이미 설정된 쿼리 탭으로 열립니다. 그런 실행마다 새 토큰을 발급하세요. 탭은 토큰이 시작한 첫 세션에서만 열립니다. 쿼리와 함께 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의 타입으로 설정합니다. 압축이 여기서 큰 도움이 됩니다: wasm 파일은 Brotli나 gzip으로 몇 배나 줄어듭니다.- 페이지가 Content-Security-Policy를 전송하는 경우:
'wasm-unsafe-eval'inscript-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'inworker-src(or inscript-src, 이는worker-srcfalls back to). If it is blocked, large results stay in memory. - 크로스 오리진 격리는 페이지가 로드하는 모든 것에 적용되므로, CORP 헤더가 없는 서드파티 CDN 대신 번들을 자체 오리진에서 제공하세요.
번들의 파일은 패키지에 맞춰 버전이 관리됩니다. 업그레이드할 때 교체할 것은 web/ 그리고 브리지까지 함께 설치합니다.
6. 좌석 처리하기
409 seat_limit표시가 민트색이면 모든 좌석이 사용 중이라는 뜻입니다. 사용자에게는 솔직하게 알려주고, 관리자에게는 좌석을 비울 방법을 제안하세요.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 “이번 주 갱신”으로 표시됩니다. 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대기 중일 때, 그런 다음200한 번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. - 읽어 두어야 할 문서는 프로덕션에 배포하기.