Справочник API
Все конечные точки API управления мостом SQLly Embedded, сгенерированные из его документа OpenAPI (swagger.json), плюс конечные точки привязки sqlly.app.
Мост SQLly во встроенном режиме открывает этот API на своем управляющем прослушивателе (--manage-bind, по умолчанию 127.0.0.1:8445). Ваше веб-приложение вызывает его на своей серверной стороне, чтобы хранить профили подключений, проверять подключения, выпускать токены запуска для авторизованных пользователей, следить за местами и читать или менять состояние лицензии.
Каждое /manage/... необходим вызов Authorization: Bearer <manage token> (мостового --manage-token, не менее 16 символов). Тела передаются и принимаются в формате JSON, максимальный размер 8 МБ (отклоняется с 413 too_large как только предел превышен). Сегменты пути и значения строки запроса декодируются из процентного кодирования; недопустимая escape-последовательность 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, по одной строке на ошибку. - Тела — это JSON, не более 8 МБ. Ограничение проверяется по мере поступления тела запроса: мост отвечает
413 too_largeв момент передачи и больше ничего не буферизует. Тело, которое добирается дольше 30 секунд, считается408 timeout. Всё, что не удаётся разобрать, —400 bad_json, а неизвестный маршрут —404 not_found. - Сегменты пути и значения запроса декодируются из процентного кодирования, поэтому применяйте URL-кодирование к идентификаторам пользователей и временным меткам (
DELETE /manage/seats/a%2Fbосвобождает место пользователяa/b). Некорректная escape-последовательность или результат не в UTF-8400 bad_request. - Имена полей записаны в camelCase в собственных полезных нагрузках API. Внутри документа учётных данных они следуют формату учётных данных (
sql_auth_accounts,trust_server_certificate).
Конечные точки
- GET
/healthz - GET
/manage/status - POST
/manage/license/checkin - PUT
/manage/license - DELETE
/manage/license - GET
/manage/engines - GET
/manage/profiles - GET
/manage/profiles/{id} - PUT
/manage/profiles/{id} - DELETE
/manage/profiles/{id} - POST
/manage/tokens - GET
/manage/seats - DELETE
/manage/seats/{user} - POST
/manage/test-connection - GET
/manage/queries - POST
/api/embedded/links - POST
/api/embedded/links/token - GET
/api/embedded/public-key
Состояние
Liveness, токен не требуется.
/healthz
токен не требуется
Проверка активности
Отвечает, как только слушатель управления запущен. Токен не требуется; используйте его из стартовых скриптов и для проверки состояния сервиса.
- 200
- API управления слушает.
Пример ответа 200
{
"ok": true
}
Лицензия
Лицензия, под которой работает мост: состояние, регистрация, привязка и отвязка.
/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
}
Пример ответа 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
/manage/license/checkin
Проверить связь с sqlly.app сейчас
Подключённые и привязанные лицензии: проверка выполняется сразу, без ожидания 20-минутного цикла. Офлайн-лицензии: файл лицензии перечитывается, сеть не затрагивается. В обоих случаях ответ — статус после попытки; при неудаче состояние не меняется.
- 200
- Статус после проверки.
- 401
unauthorized: токен управления отсутствует или неверен.- 409
not_linked: мост не лицензирован, и регистрировать нечего.- 422
license_file_invalid(офлайн): файл отсутствует, повреждён или подписан другим ключом.- 502
store_unreachableилиgrant_invalid: не удалось связаться с sqlly.app, или его ответ не прошёл проверку.
Пример ответа 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
Пример ответа 409
{
"error": "not_linked",
"message": "this bridge is not linked to a license yet"
}
/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 или его ответ не прошёл проверку.
Пример ответа 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
/manage/license
Отвязать эту установку
Освобождает слот экземпляра этого моста, отзывает его ключ на sqlly.app (по мере возможностей), удаляет сохранённый ключ, закрывает все открытые сессии и возвращает мост в unlicensed.
- 204
- Отвязано.
- 401
unauthorized: токен управления отсутствует или неверен.- 404
not_linked: связанный ключ не сохраняется.- 409
license_from_flag: мост был запущен с--license-keyили--license-file, поэтому его лицензия не управляется через этот API.
Пример ответа 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
Движки
Движки баз данных, которые принимает формат учётных данных, так что UI нигде не зашивает список жёстко.
/manage/engines
Движки, которые принимает формат учётных данных
Все СУБД, которые поддерживает SQLly, с engine идентификатор для записи в документ учетных данных, его порт по умолчанию, является ли 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"
]
}
]
Пример ответа 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
Профили
Профиль — это именованный документ учётных данных SQLly: подключения (и метки), которые видит одна группа пользователей. Хранилище-первоисточник — сам мост; секреты никогда не попадают в браузер.
/manage/profiles
Список профилей
Каждый сохраненный профиль — без учетных данных.
- 200
- Профили.
- 401
unauthorized: токен управления отсутствует или неверен.
Пример ответа 200
[
{
"id": "analysts",
"name": "Analysts",
"connections": 2,
"updatedAt": "2026-10-14T15:02:11Z"
}
]
Пример ответа 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
/manage/profiles/{id}
Прочитать один профиль
Профиль с полным документом учетных данных, включая секреты: вызывающая сторона — ваше доверенное серверное приложение.
- id
- path · строка, соответствующая ^[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: ни один профиль не имеет такого идентификатора.
Пример ответа 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
Пример ответа 404
{
"error": "unknown_profile",
"message": "no profile with id analysts"
}
/manage/profiles/{id}
Создать или заменить профиль
Сохраняет профиль под id (create or replace). Документ учётных данных полностью проверяется до того, как что-либо будет записано: каждая проблема, которую находит парсер, возвращается в problems, и недействительный документ ничего не меняет. Документ с движком на основе файла (SQLite, DuckDB) отклоняется аналогичным образом, если мост не запущен с --allow-file-engines true, потому что такое подключение даёт его пользователям доступ к файлам на хосте моста. Уже открытые сессии сохраняют каталог, с которым они начали; изменения применяются при следующем запуске.
- id
- path · строка, соответствующая ^[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: не удалось записать каталог состояния.
Пример ответа 400
{
"error": "invalid_profile",
"message": "the credential document has 2 problems",
"problems": [
"connections[0].engine: unknown engine \"postgress\"",
"connections[1].authentication.pasword: unknown key"
]
}
Пример ответа 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
/manage/profiles/{id}
Удалить профиль
Удаляет профиль. Открытые сессии сохраняют каталог, с которым были запущены; новые токены запуска для него отклоняются с unknown_profile.
- id
- path · строка, соответствующая ^[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: ни один профиль не имеет такого идентификатора.
Пример ответа 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
Пример ответа 404
{
"error": "unknown_profile",
"message": "no profile with id analysts"
}
Запустить
Токены запуска открывают SQLly для одного пользователя с одним профилем. Места — это одновременные пользователи.
/manage/tokens
Создать токен запуска
Создаёт токен с коротким сроком действия, который открывает SQLly для 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: ни один профиль не имеет такого идентификатора.- 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
}
Пример ответа 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
/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"
}
]
}
Пример ответа 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
/manage/seats/{user}
Освободить место пользователя
Отзывает токены пользователя и закрывает его сеансы, мгновенно освобождая место. Вызывайте его, когда пользователь выходит из вашего приложения или теряет доступ. Освобождение пользователя, который не занимает место, ошибкой не считается. Сегмент пути декодируется из URL-кодирования: a%2Fb освобождает место пользователя a/b.
- пользователь
- path · строка · обязательно - ID пользователя, для которого вы выпускали токены (URL-кодированный).
- 204
- Выпущено.
- 400
bad_request: сегмент не является корректным процентным кодированием.- 401
unauthorized: токен управления отсутствует или неверен.
Пример ответа 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
Подключения
Убедитесь, что подключение работает, прежде чем им начнут пользоваться.
/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"
}
Пример ответа 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
Аудит
Журнал аудита запросов: каждый запрос и правку строк, которые выполнил сеанс, кто их выполнял, на каком подключении и чем они закончились. Хранится в памяти и в <state-dir>/queries.jsonl (включая текст SQL), если мост не работает с --query-log false.
/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 · строка - Только этот идентификатор пользователя (точное совпадение, URL-кодировка).
- профиль
- query · строка - Только этот идентификатор профиля (точное совпадение).
- с
- 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'."
}
]
}
Пример ответа 401
{
"error": "unauthorized",
"message": "management token missing or wrong"
}
Связывание
конечные точки sqlly.app (сервер sqlly.app) для привязки установки к лицензии: создайте код, владелец одобрит его в своём браузере, один раз соберите собственный ключ установки и передайте его мосту с помощью PUT /manage/license.
/api/embedded/links
sqlly.app
токен не требуется
Начать привязку установки (sqlly.app)
Анонимно. Создает запрос на привязку и возвращает короткий код, секрет, известный только вашему приложению, и URL, где владелец лицензии одобряет его. Покажите код и откройте linkUrl для владельца, затем опрашивайте POST /api/embedded/links/token каждое pollIntervalSeconds до тех пор, пока он не будет одобрен. Ссылки действительны 15 минут.
Тело запроса (CreateLinkRequest)
{
"name": "SQLly Embedded on portal-01",
"hostname": "portal-01",
"appVersion": "1.4.0"
}
- 201
- Привязка выполнена.
- 429
- Превышен лимит запросов.
- 503
link_unavailable: не удалось выделить код; попробуйте снова.
Пример ответа 201
{
"linkId": "eml_Y2h9u0bQ1sXk4tWm8pZr3vLa",
"code": "K7Q-4MX",
"secret": "pW0r7…",
"linkUrl": "https://sqlly.app/embedded/link?code=K7Q-4MX",
"expiresAt": "2026-10-14T15:17:11Z",
"pollIntervalSeconds": 3
}
/api/embedded/links/token
sqlly.app
токен не требуется
Опрос связанного ключа (sqlly.app)
Анонимно; учётные данные — это секрет ссылки. Пока владелец не принял решение, ответы 202 pending. После одобрения создаётся собственный лицензионный ключ этой установки и возвращается ровно один раз (ссылка при этом сгорает). Передайте ключ напрямую мосту с PUT /manage/license; не храните его у себя.
Тело запроса (LinkTokenRequest)
- 200
- Одобрено: ключ, один раз.
- 202
- Всё ещё ждём владельца.
- 401
wrong_secret.- 404
unknown_link.- 410
link_used,link_denied,link_expiredилиlicense_revoked: эта ссылка уже не сработает. Начните новую.- 429
- Превышен лимит запросов.
/api/embedded/public-key
sqlly.app
токен не требуется
Публичный ключ для подписания лицензии (sqlly.app)
Открытый ключ в формате PEM, которым sqlly.app подписывает выдачу лицензий, чтобы оператор мог сверить его с ключом, встроенным в мост.
- 200
- Текст PEM.
- 503
signing_not_configured.
Схемы
Перечисленные выше объекты в том виде, как они определены в swagger.json. A ? после типа означает, что он может быть 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 |
URL WebSocket, который используют браузеры (--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_. |
Информация о движке
| Поле | Тип | Описание |
|---|---|---|
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) |
СохранённыйПрофиль
| Поле | Тип | Описание |
|---|---|---|
id |
string |
|
name |
string |
|
credentials |
CredentialDocument |
|
updatedAt |
string (date-time) |
PutProfileRequest
| Поле | Тип | Описание |
|---|---|---|
name * |
string |
Отображаемое имя, показываемое пользователям в SQLly. |
credentials * |
CredentialDocument |
CredentialDocument
Документ учетных данных SQLly (тот же формат, что и File → Import Connections в 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 МБ). |
safety |
object |
Меняются только перечисленные вами флаги. |
SharedLogin
| Поле | Тип | Описание |
|---|---|---|
name * |
string |
|
username * |
string |
|
password |
string |
Подключение
| Поле | Тип | Описание |
|---|---|---|
name * |
string |
|
engine * |
string |
ID из GET /manage/engines. |
server * |
string |
Хост, IP, host\instance или путь к файлу для SQLite/DuckDB. |
port |
integer |
|
database |
string |
|
environment |
string |
local, dev, test, staging, production или unset. |
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 |
Встроенная поддержка прокси, 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 |
Ваш стабильный идентификатор пользователя (без пробелов). Места учитываются по каждому отдельному пользователю. |
profile * |
string |
Идентификатор профиля. |
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 КиБ; 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, нумерация с единицы; столбец считает символы и может указывать на один символ за концом строки.
| Поле | Тип | Описание |
|---|---|---|
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[] |
UserSeat
| Поле | Тип | Описание |
|---|---|---|
user |
string |
|
activeSessions |
integer |
|
tokens |
integer |
Действующие токены запуска. |
since |
string (date-time) |
TestConnectionRequest
| Поле | Тип | Описание |
|---|---|---|
credentials * |
CredentialDocument |
TestOutcome
| Поле | Тип | Описание |
|---|---|---|
ok |
boolean |
|
elapsedMs |
integer |
|
message |
string |
Сообщение самого движка, успех или неудача. |
QueryStatus
running до тех пор, пока движок не ответит; затем completed, failed (см. error) или cancelled (пользователем, или session closed).
Один из: running completed failed cancelled
QueryEntry
Один запрос, записанный в журнал аудита.
| Поле | Тип | Описание |
|---|---|---|
id |
string |
Идентификатор запроса движка, уникальный в рамках его сессии. |
sessionId |
integer |
Идентификатор моста для сессии браузера. |
kind |
query | row-edit |
|
at |
string (date-time) |
Когда запрос достиг моста. |
user |
string |
Идентификатор пользователя токена запуска. |
profile |
string |
Идентификатор профиля токена запуска. |
profileName |
string |
|
connection |
string |
Имя соединения в профиле. |
server |
string |
|
database |
string? |
База данных профиля, когда она закреплена, иначе база данных, указанная в запросе. |
engine |
string |
Отображаемое имя движка. |
sql |
string |
Текст SQL, или row edit: <op> для редактирования строки. Обрезано до 64 КиБ. |
sqlTruncated |
boolean |
|
status |
QueryStatus |
|
durationMs |
integer? |
Null во время выполнения. |
error |
string? |
Ошибка движка для failed; session closed для запроса, прерванного завершением его сеанса. |
QueryListing
| Поле | Тип | Описание |
|---|---|---|
enabled |
boolean |
Ложь, когда мост работает с --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 |
* обязательно