Abrir SQLly en una consulta
Abre SQLly directamente en una pestaña de consulta: el script, su conexión y base de datos, los valores de los parámetros y el cursor se envían con el token de lanzamiento de los botones «Abrir en SQLly».
Un token de lanzamiento normalmente abre un entorno de trabajo vacío. Añade un open campo cuando lo crees y SQLly se abrirá directamente en una o más pestañas de consulta: el script cargado, la pestaña conectada al servidor y la base de datos correctos, tus valores de parámetros completados, el cursor donde lo colocaste. Eso te da botones de "Abrir en SQLly" en cualquier lugar donde tu aplicación muestre SQL: junto a un informe, en una consulta fallida, en un registro de auditoría.
Nada se ejecuta por sí solo. Un lanzamiento solo carga pestañas. Quien lo abre en el navegador revisa cada consulta y presiona Ejecutar: la misma regla que siguen los enlaces de consulta de la versión de escritorio de SQLly. No hay forma de hacer que un lanzamiento ejecute SQL.
Generar un token con contexto de lanzamiento
Es lo mismo POST /manage/tokens llamada que cualquier otro lanzamiento (paso 4 de construir tu propia aplicación), con un campo extra:
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 }
}
}'
La respuesta es el token habitual más openTabs, el número de pestañas que la sesión abrirá:
{ "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 }
Entrega el token a la página igual que en un lanzamiento normal. Cuando el usuario llegue, SQLly se conecta a Shop, cambia a sales, y muestra una pestaña llamada "Big orders" con la consulta cargada, la barra de parámetros con 500 y 2026-10-01, y el cursor en la tercera línea.
Qué puede contener una pestaña
open es un objeto, o una lista de hasta 8 para varias pestañas. La primera recibe el foco. Todos los campos son opcionales, pero cada entrada necesita al menos un script o una conexión.
| Campo | Tipo | Significado |
|---|---|---|
connection | cadena | Una conexión del perfil del token, por nombre (sin distinguir mayúsculas de minúsculas) o por su id. Omítelo cuando el perfil tenga una sola conexión. Si hay varias y no se indica ninguna, la pestaña se abre sin conexión. |
database | cadena | La base de datos a la que cambiar en lugar de la predeterminada de la conexión. Como máximo 128 caracteres. |
title | cadena | El título de la pestaña. Como máximo 120 caracteres. Si no, SQLly nombra la pestaña como siempre. |
script | cadena | El SQL a cargar, tal cual. Como máximo 256 KiB. Los finales de línea de Windows se convierten en \n. |
parameters | objeto | Valores para los @name parámetros del script, como máximo 64. Consulta parámetros. |
cursor | { line, column } | Dónde va el cursor; ambos valores se cuentan desde 1 y la columna se mide en caracteres. Debe apuntar dentro del script (se permite una columna más allá del final de una línea). |
Parámetros
SQLly tiene parámetros de consulta tipados: una -- sqlly param: @name <type> la línea declara uno, y una franja sobre los resultados contiene su valor. Los parámetros de lanzamiento usan esa misma franja, por lo que tus valores aparecen como entradas visibles y editables y las instrucciones mismas se cargan exactamente como las enviaste.
- Los nombres usan
@name, en cada motor. Envía la clave con o sin el@("min_total"y"@min_total"son lo mismo). Un nombre es una letra o_seguida de letras, dígitos o_, 64 caracteres como máximo, y puede aparecer solo una vez (da igual si es mayúscula o minúscula). Si tu aplicación escribe los parámetros de otra forma ($name,:name,?), reescríbelos como@namecuando generes el script. - Un valor simple toma su tipo de JSON: un número entero es
int, cualquier otro númerodecimal,true/falsebool, una cadenatext, ynulldeja la entrada vacía para que el usuario la complete. - Un valor escrito es
{ "type": "date", "value": "2026-10-01" }. Los tipos sontext,int,decimal,bool,date,datetime,time,uuid,jsonybinary. Envía documentos JSON como cadenas con"type": "json". - Las declaraciones se añaden automáticamente. Para cada parámetro que el script no declare, SQLly agrega un
-- sqlly param:línea sobre el script, y el cursor se mueve hacia abajo con el script. Un parámetro que el script ya declara mantiene la declaración y el tipo del script, y recibe tu valor. - Cómo llegan los valores a la base de datos. Cuando el usuario presiona Ejecutar, SQLly verifica cada valor contra su tipo y reemplaza cada
@namefuera de cadenas y comentarios con un literal escrito correctamente para ese motor, y luego envía la instrucción. Un valor que no encaja en su tipo detiene la ejecución y enfoca ese campo. Tu aplicación nunca inserta valores en el texto SQL.
Un lanzamiento, un token
- Las pestañas se abren una vez. El puente se los entrega a la primera sesión de SQLly que usa el token y luego los olvida. Recargar la página restaura el entorno de trabajo, que SQLly guarda en el navegador, por lo que las pestañas no se abren dos veces. El token en sí sigue funcionando hasta que expira.
- Genera un token nuevo por cada clic en «Abrir en SQLly». No reutilices un token en caché para un lanzamiento con contexto: no abriría nada. Un token nuevo para un usuario que ya tiene un asiento no cuesta ningún asiento adicional.
- Cada clic es una nueva pestaña. Cuenta contra el límite de sesiones por usuario
sessionsPerSeat(cuatro en los planes de pago, una en la prueba). En la prueba, el usuario tiene que cerrar antes su otra pestaña de SQLly, o la nueva se rechaza con «<user> ya tiene el número máximo de sesiones de SQLly abiertas». - El contexto se fija en el momento de la emisión del token - como el perfil. Las conexiones se resuelven según el perfil en ese momento.
Los errores se detectan al generar el token
El puente comprueba todo el open valor antes de crear el token, así que tu servidor lo nota de inmediato y no un usuario que se topa con una pestaña rota. Un valor incorrecto es 400 invalid_open con una entrada en problems por error, y cada uno dice dónde está. No se genera ningún token ni se ocupa ningún puesto:
{
"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)"
]
}
Los campos desconocidos se rechazan en lugar de ignorarse, así que un error tipográfico como sql para script falla de forma evidente. Los valores de tipo int, decimal y bool también se comprueban. Los demás tipos los comprueba la barra de parámetros de SQLly antes de ejecutar una consulta.
Recetas
Reabrir una consulta desde el historial de auditoría
La historial de auditoría de consultas registra cada consulta con su perfil, su conexión, su base de datos y su SQL, que es todo lo que necesita un lanzamiento. La página de Consultas de la aplicación de ejemplo tiene un Reabrir en SQLly botón en cada instrucción completa. Busca la fila nuevamente en el puente (el formulario nombra la fila y nada más), luego crea un lanzamiento de administrador con este contexto:
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 });
El SQL registrado es lo que de verdad se ejecutó, así que los valores de los parámetros ya figuran como literales y no hacen falta parámetros. Si una instrucción falla, la app de ejemplo también lee dónde dice el motor que falló (PostgreSQL POSITION: 53, el «at line 2» de MySQL) y lo envía como el cursor, así que el cursor queda en la columna problemática.
«Abrir en SQLly» en la página de error de tu aplicación
Si tu aplicación ejecuta SQL por su cuenta (un generador de informes, un framework de páginas basado en SQL, trabajos programados), en el momento en que falla una instrucción sabe cuál fue, qué valores tenía enlazados y contra qué base de datos se ejecutó. Pon un botón en la página de error que genere un lanzamiento con esa instrucción, sus valores como parámetros y el cursor en la línea de la que se quejó la base de datos. El desarrollador obtiene un banco de trabajo completo para esa consulta, con IntelliSense, el explorador de objetos y los planes de ejecución, sin copiar nada a mano:
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,
},
});
Ofrece esto solo a quien deba tener un entorno de trabajo en esa base de datos, por ejemplo en desarrollo o para administradores. El perfil decide a qué pueden acceder, igual que en cualquier otro lanzamiento.