Открыть SQLly с готовым запросом

Запускайте SQLly сразу с открытой вкладкой запроса: скрипт, его подключение и база данных, значения параметров и курсор передаются вместе с токеном запуска для кнопок «Открыть в SQLly».

Токен запуска обычно открывает пустую рабочую среду. Добавьте поле open при его выпуске, и SQLly вместо этого сразу открывает одну или несколько вкладок запросов: скрипт загружен, вкладка подключена к нужному серверу и базе данных, значения параметров подставлены, курсор находится там, куда вы его поставили. Это даёт вам кнопки «Открыть в SQLly» везде, где ваше приложение показывает SQL: рядом с отчётом, у невыполненного запроса, в журнале аудита.

Ничто не выполняется самостоятельно. Запуск только загружает вкладки. Человек в браузере просматривает каждый запрос и нажимает «Выполнить» — то же правило, которому следуют ссылки на запросы в десктопной версии SQLly. Заставить запуск выполнить SQL невозможно.

Создать токен с контекстом запуска

Это то же самое POST /manage/tokens вызовите как любой запуск (шаг 4 создания собственного приложения), с одним дополнительным полем:

оболочка
curl -s -X POST -H "Authorization: Bearer $SQLLY_EMBEDDED_MANAGE_TOKEN" \
  -H 'content-type: application/json' http://127.0.0.1:8445/manage/tokens -d '{
  "user": "dana.analyst",
  "profile": "analysts",
  "open": {
    "connection": "Shop",
    "database": "sales",
    "title": "Big orders",
    "script": "SELECT *\nFROM orders\nWHERE total > @min_total AND placed_at >= @since",
    "parameters": { "min_total": 500, "since": { "type": "date", "value": "2026-10-01" } },
    "cursor": { "line": 3, "column": 7 }
  }
}'

Ответ — это обычный токен плюс openTabs, количество вкладок, которые откроет сессия:

{ "token": "…", "expiresAt": "2026-10-18T15:12:11Z", "proxyUrl": "wss://portal.example.com/sqlly/proxy",
  "user": "dana.analyst", "profile": "analysts", "seatsUsed": 3, "seats": 25, "openTabs": 1 }

Передайте токен на страницу точно так же, как для обычного запуска. Когда пользователь приходит, SQLly подключается к Shop, переключается на sales, и показывает вкладку "Большие заказы" с загруженным запросом, со значениями 500 и 2026-10-01 на панели параметров и кареткой на третьей строке.

Что может содержать вкладка

open — это один объект или список до 8 объектов, если вкладок несколько. Первая получает фокус. Каждое поле необязательно, но записи нужен хотя бы скрипт или подключение.

ПолеТипЗначение
connectionстрокаПодключение в профиле токена, по имени (любой регистр букв) или по его идентификатору. Пропустите, если в профиле только одно подключение. Если несколько подключений и ни одно не названо, вкладка откроется без подключения.
databaseстрокаБаза данных для переключения вместо базы по умолчанию из подключения. Не более 128 символов.
titleстрокаЗаголовок вкладки. Максимум 120 символов. Если отсутствует, SQLly именует вкладку как обычно.
scriptстрокаSQL для загрузки, дословно. Максимум 256 КиБ. Концы строк Windows преобразуются в \n.
parametersobjectЗначения для @name параметров скрипта, максимум 64. См. параметры.
cursor{ line, column }Где располагается каретка; обе координаты отсчитываются с 1, столбец — в символах. Она должна указывать внутрь скрипта (допустим столбец сразу за концом строки).

Параметры

У SQLly есть типизированные параметры запроса: -- sqlly param: @name <type> строка объявляет параметр, и полоса над результатами хранит его значение. Параметры запуска используют ту же полосу, так что ваши значения видны как редактируемые поля, а сами операторы загружаются ровно так, как вы их отправили.

  • Имена используют @name, на каждом движке. Отправляйте ключ с или без @ ("min_total" и "@min_total" одинаковы). Имя — это буква или _ за которой следуют буквы, цифры или _, максимум 64 символа, и может появляться только один раз (в любом регистре). Если ваше приложение записывает параметры другим способом ($name, :name, ?), перепишите их на @name при создании скрипта.
  • Простое значение берёт тип из JSON: целое число — это int, любое другое число decimal, true/false bool, строка text, и null оставляет поле ввода пустым, чтобы его заполнил пользователь.
  • Введённое значение является { "type": "date", "value": "2026-10-01" }. Типы следующие text, int, decimal, bool, date, datetime, time, uuid, json и binary. Отправляйте документы JSON как строки с "type": "json".
  • Объявления добавляются автоматически. Для каждого параметра, который скрипт не объявляет, SQLly добавляет -- sqlly param: строка выше скрипта, и курсор перемещается вниз вместе со скриптом. Параметр, который скрипт уже объявляет, сохраняет объявление и тип скрипта и получает ваше значение.
  • Как значения попадают в базу данных. Когда пользователь нажимает Выполнить, SQLly проверяет каждое значение на соответствие его типу и заменяет каждое @name за пределами строк и комментариев литералом, записанным по правилам конкретного движка, и только потом отправляет оператор. Значение, которое не подходит к своему типу, останавливает выполнение и ставит фокус на этот ввод. Ваше приложение никогда не вклеивает значения в текст SQL.

Один запуск, один токен

  • Вкладки открываются один раз. Мост передает их первой сессии SQLly, которая использует токен, и потом забывает о них. Перезагрузка страницы восстанавливает рабочую область, которую SQLly сохраняет в браузере, поэтому вкладки не открываются дважды. Сам токен работает до истечения срока.
  • Создавайте новый токен для каждого клика «Открыть в SQLly». Не используйте повторно кэшированный токен для запуска с контекстом: он ничего не откроет. Новый токен для пользователя, который уже занимает место, не требует дополнительного места.
  • Каждый клик — новая вкладка. Это засчитывается в лимит пользователя sessionsPerSeat (на платных тарифах — четыре, на пробной — одна). В пробной версии пользователю сначала придётся закрыть другую вкладку SQLly, иначе новую отклонят с сообщением «<user> уже открыл максимально допустимое число сессий SQLly».
  • Контекст фиксируется в момент выпуска токена - как профиль. Подключения разрешаются по профилю в том состоянии, в каком он находится на тот момент.

Ошибки перехватываются при выпуске токена

Мост проверяет всё open значение перед созданием токена, поэтому ваш сервер узнаёт об этом сразу, а не пользователь, обнаруживший сломанную вкладку. Некорректное значение 400 invalid_open с одной записью в problems на каждую ошибку, каждая указывает, где она находится. Токен не создаётся и место не занимается:

{
  "error": "invalid_open",
  "message": "the launch context has 3 problems",
  "problems": [
    "open[0].connection: no connection \"Shopp\" in this profile (it has: Shop, Warehouse)",
    "open[0]: unknown field \"sql\" (allowed: connection, database, title, script, parameters, cursor)",
    "open[1].cursor: line 9 is past the end of the script (3 lines)"
  ]
}

Неизвестные поля отклоняются, а не игнорируются, поэтому опечатка вроде sql для script выдаёт ошибку. Значения типа int, decimal и bool тоже проверяются. Остальные типы SQLly проверяет на панели параметров перед запуском запроса.

Рецепты

Повторно открыть запрос из журнала аудита

Этот журнал аудита запросов записывает каждый запрос вместе с его профилем, подключением, базой данных и SQL — этого достаточно для запуска. На странице «Запросы» примера приложения есть Повторно открыть в SQLly кнопку для каждого полного оператора. Она снова находит строку на мосту (форма называет только строку и ничего больше), а затем создаёт admin-запуск с этим контекстом:

javascript
const entry = (await bridge('GET', '/manage/queries?limit=1000')).queries
  .find((q) => String(q.sessionId) === form.session && q.id === form.id);
if (!entry || entry.kind === 'row-edit' || entry.sqlTruncated) return refuse();

const open = {
  connection: entry.connection,
  title: `${entry.status === 'failed' ? 'Failed' : 'Query'} from ${entry.user}`,
  script: entry.sql,
};
if (entry.database) open.database = entry.database;
const minted = await bridge('POST', '/manage/tokens', { user: `admin:${admin.id}`, profile: entry.profile, open });

Залогированный SQL — это то, что реально выполнилось, поэтому значения параметров в нём уже литералы и параметры не нужны. Для упавшего оператора демо-приложение также считывает место, где движок сообщил о сбое (у PostgreSQL POSITION: 53, в MySQL — «на строке 2») и отправляет это как cursor, чтобы курсор оказывался на проблемном столбце.

«Открыть в SQLly» на странице ошибки вашего приложения

Если ваше приложение само выполняет SQL (конструктор отчётов, фреймворк страниц на SQL, задания по расписанию), в момент сбоя оператора оно знает, какой оператор не сработал, какие значения были к нему привязаны и в какой базе данных он выполнялся. Добавьте на страницу ошибки кнопку, которая создаёт запуск с этим оператором, его значениями в качестве параметров и курсором на строке, на которую пожаловалась база данных. Разработчик получает полноценную рабочую среду для этого запроса — с IntelliSense, обозревателем объектов и планами выполнения, — и ему не нужно ничего копировать вручную:

javascript
// failure = { sql: 'SELECT … WHERE id = $id', params: { id: 42 }, line: 3 }
const script = failure.sql.replace(/\$([A-Za-z_]\w*)/g, '@$1');   // $id → @id
const minted = await bridge('POST', '/manage/tokens', {
  user: req.user.id,
  profile: 'app-database',            // a profile pointing at the app's own database
  open: {
    title: 'Failed statement',
    script,
    parameters: failure.params,
    cursor: failure.line ? { line: failure.line, column: 1 } : undefined,
  },
});

Предлагайте это только тем, кому нужна рабочая среда на этой базе данных, например в среде разработки или администраторам. Профиль решает, к чему у них будет доступ, точно так же, как и при любом другом запуске.