Создание собственного приложения
Шаг за шагом: управляйте мостом 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, сессии |
| Решите, кто какие подключения видит | Каждому пользователю назначается один профиль | Ваши роли, команды, тенанты или тарифы задают идентификатор профиля |
| Определение подключений | Редактор профилей, вкладка Метки (lib/credentials.js создает документ) | Ваш интерфейс администратора, конфигурационный файл или код, создающий документы из данных вашего тенанта |
| Открыть 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. Крошечный клиент для управления
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 содержит все идентификаторы движков, их стандартные порты и какие типы входа они принимают, чтобы форма никогда не хардкодила их.
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' } },
],
},
});
- Идентификаторы профилей – 1-64 из
A-Z a-z 0-9 _ -. Используйте свой собственный стабильный ключ (идентификатор арендатора, имя роли). - Мост проверяет весь документ перед сохранением. Некорректный документ возвращается как
400 invalid_profileсproblemsсо списком всех ошибок. Неизвестные ключи считаются ошибками, поэтому опечатки никогда не проходят. - Мост является основным хранилищем секретов. Держите источник истины там, где хотите, но повторно
PUTпрофили при их изменении. Пример приложения при запуске заново отправляет все профили, так что свежий каталог состояния сам себя восстанавливает. - Используйте метки и флаги безопасности.
only_allow_selectв рабочей среде (Production), или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 минимальный 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, чтобы пользователь попал на вкладку запроса, где уже заданы скрипт, соединение, значения параметров и курсор. Для каждого такого запуска выпускайте свежий токен: вкладки открываются только для первой сессии, начатой токеном. Открыть SQLly с готовым запросом. - Идентификатор пользователя — ваш. Передавайте стабильный непрозрачный идентификатор. Места считаются по уникальным идентификаторам, а идентификаторы, занимающие места, передаются на sqlly.app при check-in.
- Если вы не можете редактировать 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'вscript-src, источник мостаwss://origin в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. - Изоляция между источниками применяется ко всему, что загружает страница, поэтому отдавайте пакет с вашего собственного источника, а не со стороннего CDN без заголовков CORP.
Файлы пакета версионируются вместе с пакетом. При обновлении заменяйте web/ и мост вместе.
6. Управление местами
409 seat_limitпри выпуске токена означает, что все места заняты. Скажите об этом пользователю прямо, а администратору предложите освободить одно.GET /manage/seatsперечисляет, кто занимает места и с какого времени.- Освобождать место при выходе из аккаунта:
DELETE /manage/seats/{user}отзывает токены пользователя и закрывает его вкладки SQLly. Делайте то же самое, когда отзываете кому-то доступ, — иначе токен продолжит работать, пока не истечёт срок его действия. - Дополнительная вкладка сверх
sessionsPerSeatотклоняется самим мостом: сокету сообщают «<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, затем:
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 управления привязан к loopback или частной сети.
- Каждый запуск выпускается на стороне сервера для аутентифицированного пользователя, с профилем, который выбрали ваши правила авторизации.
- Страница SQLly и пакет содержат заголовки изоляции, и ваш CSP разрешает использование моста
wss://происхождение. - Выход из системы и отзыв доступа освобождают лицензионное место пользователя.
seat_limitиlicense_not_okпоказывать сообщение для человека, а не трассировку стека.- Что-то следит за
GET /manage/status. - Вы прочитали Выход в продакшн.