Справочник API

Все конечные точки API управления мостом SQLly Embedded, сгенерированные из его документа OpenAPI (swagger.json), плюс конечные точки привязки sqlly.app.

Скачать swagger.json OpenAPI 3.0 версия 1.0.0 базовый http://127.0.0.1:8445

Мост 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-8 400 bad_request.
  • Имена полей записаны в camelCase в собственных полезных нагрузках API. Внутри документа учётных данных они следуют формату учётных данных (sql_auth_accounts, trust_server_certificate).

Конечные точки

Состояние

Liveness, токен не требуется.

GET /healthz токен не требуется

Проверка активности

Отвечает, как только слушатель управления запущен. Токен не требуется; используйте его из стартовых скриптов и для проверки состояния сервиса.

200
API управления слушает.
Пример ответа 200
{
  "ok": true
}

Лицензия

Лицензия, под которой работает мост: состояние, регистрация, привязка и отвязка.

GET /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"
}
POST /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"
}
PUT /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"
}
DELETE /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 нигде не зашивает список жёстко.

GET /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: подключения (и метки), которые видит одна группа пользователей. Хранилище-первоисточник — сам мост; секреты никогда не попадают в браузер.

GET /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"
}
GET /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"
}
PUT /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"
}
DELETE /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 для одного пользователя с одним профилем. Места — это одновременные пользователи.

POST /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"
}
GET /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"
}
DELETE /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"
}

Подключения

Убедитесь, что подключение работает, прежде чем им начнут пользоваться.

POST /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.

GET /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.

GET /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

* обязательно