Открыть 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. |
parameters | object | Значения для @name параметров скрипта, максимум 64. См. параметры. |
cursor | { line, column } | Где располагается каретка; обе координаты отсчитываются с 1, столбец — в символах. Она должна указывать внутрь скрипта (допустим столбец сразу за концом строки). |
Параметры
У SQLly есть типизированные параметры запроса: -- sqlly param: @name <type> строка объявляет параметр, и полоса над результатами хранит его значение. Параметры запуска используют ту же полосу, так что ваши значения видны как редактируемые поля, а сами операторы загружаются ровно так, как вы их отправили.
- Имена используют
@name, на каждом движке. Отправляйте ключ с или без@("min_total"и"@min_total"одинаковы). Имя — это буква или_за которой следуют буквы, цифры или_, максимум 64 символа, и может появляться только один раз (в любом регистре). Если ваше приложение записывает параметры другим способом ($name,:name,?), перепишите их на@nameпри создании скрипта. - Простое значение берёт тип из JSON: целое число — это
int, любое другое числоdecimal,true/falsebool, строка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-запуск с этим контекстом:
javascriptconst 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,
},
});
Предлагайте это только тем, кому нужна рабочая среда на этой базе данных, например в среде разработки или администраторам. Профиль решает, к чему у них будет доступ, точно так же, как и при любом другом запуске.