Ouvrir SQLly sur une requête

Lancez SQLly directement dans un onglet de requête : le script, sa connexion et sa base de données, les valeurs des paramètres et le curseur, envoyés avec le jeton de lancement pour les boutons « Ouvrir dans SQLly ».

Un jeton de lancement ouvre normalement un atelier vide. Ajoutez un open champ lorsque vous le créez et SQLly s'ouvre directement dans un ou plusieurs onglets de requête : le script chargé, l'onglet connecté au bon serveur et à la bonne base de données, vos valeurs de paramètres remplies, le curseur là où vous l'avez placé. Cela vous donne des boutons « Ouvrir dans SQLly » partout où votre application affiche du SQL : à côté d'un rapport, sur une requête échouée, dans une trace d'audit.

Rien ne s'exécute de son propre chef. Un lancement ne charge que des onglets. La personne dans le navigateur examine chaque requête et appuie sur Exécuter, la même règle que suivent les liens de requête de l’application de bureau de SQLly. Il n’y a aucun moyen de faire exécuter du SQL à un lancement.

Créer un jeton avec le contexte de lancement

C'est la même chose POST /manage/tokens appelez comme n'importe quel lancement (étape 4 de la création de votre propre application), avec un champ supplémentaire :

shell
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 réponse est le jeton habituel plus openTabs, le nombre d’onglets que la session ouvrira :

{ "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 }

Transmettez le jeton à la page exactement comme pour un lancement normal. Quand l'utilisateur arrive, SQLly se connecte à Shop, bascule vers sales, et affiche un onglet appelé « Grandes commandes » avec la requête chargée, la bande de paramètres contenant 500 et 2026-10-01, et le curseur sur la troisième ligne.

Ce qu’un onglet peut contenir

open est un objet, ou une liste allant jusqu'à 8 pour plusieurs onglets. Le premier reçoit le focus. Chaque champ est optionnel, mais une entrée nécessite au moins un script ou une connexion.

ChampTypeSens
connectionchaîneUne connexion du profil du jeton, par nom (casse libre) ou par identifiant. À omettre quand le profil n'a qu'une seule connexion. S'il y en a plusieurs et qu'aucune n'est nommée, l'onglet s'ouvre sans.
databasechaîneLa base de données à utiliser à la place de celle par défaut de la connexion. Au maximum 128 caractères.
titlechaîneLe titre de l'onglet. Au maximum 120 caractères. Sans cela, SQLly nomme l'onglet comme d'habitude.
scriptchaîneLe SQL à charger, tel quel. Au maximum 256 KiB. Les fins de ligne Windows sont converties en \n.
parametersobjectValeurs pour les @name paramètres du script, au maximum 64. Voir paramètres.
cursor{ line, column }Où placer le curseur, ligne et colonne comptées à partir de 1, la colonne en caractères. Il doit pointer à l'intérieur du script (une colonne juste après la fin d'une ligne est autorisée).

Paramètres

SQLly a des paramètres de requête typés : une -- sqlly param: @name <type> ligne en déclare un, et une bande au-dessus des résultats en conserve la valeur. Les paramètres de lancement utilisent cette même bande, donc vos valeurs s'affichent sous forme de champs visibles et modifiables, et les instructions elles-mêmes sont chargées exactement comme vous les avez envoyées.

  • Les noms utilisent @name, sur chaque moteur. Envoyez la clé avec ou sans le @ ("min_total" et "@min_total" sont les mêmes). Un nom est une lettre ou _ suivie de lettres, chiffres ou _, au maximum 64 caractères, et peut apparaître une seule fois (indépendamment de la casse). Si votre application écrit les paramètres d'une autre manière ($name, :name, ?), réécrivez-les en @name lorsque vous générez le script.
  • Une valeur simple déduit son type du JSON : un nombre entier est int, tout autre nombre decimal, true/false bool, une chaîne text, et null laisse le champ vide pour que l'utilisateur le remplisse.
  • Une valeur typée est { "type": "date", "value": "2026-10-01" }. Les types sont text, int, decimal, bool, date, datetime, time, uuid, json et binary. Envoyez les documents JSON sous forme de chaînes avec "type": "json".
  • Les déclarations sont ajoutées automatiquement. Pour chaque paramètre que le script ne déclare pas, SQLly ajoute un -- sqlly param: ligne au-dessus du script, et le curseur descend avec le script. Un paramètre que le script déclare déjà conserve la déclaration et le type du script, et reçoit votre valeur.
  • Comment les valeurs atteignent la base de données. Lorsque l'utilisateur appuie sur Exécuter, SQLly vérifie chaque valeur par rapport à son type et remplace chaque @name en dehors des chaînes et des commentaires par un littéral correctement écrit pour ce moteur, puis envoie l'instruction. Une valeur qui ne correspond pas à son type arrête l'exécution et met le focus sur cette entrée. Votre application n'insère jamais de valeurs directement dans le texte SQL.

Un lancement, un jeton

  • Les onglets s'ouvrent une seule fois. Le pont les transmet à la première session SQLly qui utilise le jeton, puis les oublie. Le rechargement de la page restaure le poste de travail, que SQLly enregistre dans le navigateur, donc les onglets ne sont pas ouverts deux fois. Le jeton lui-même fonctionne toujours jusqu'à son expiration.
  • Générez un nouveau jeton à chaque clic sur « Ouvrir dans SQLly ». Ne réutilisez pas un jeton mis en cache pour un lancement avec contexte : cela n'ouvrirait rien. Un nouveau jeton pour un utilisateur qui détient déjà un siège ne coûte aucun siège.
  • Chaque clic ouvre un nouvel onglet. Cela est décompté du sessionsPerSeat (quatre pour les forfaits payants, un pour l'essai). En essai, l'utilisateur doit d'abord fermer son autre onglet SQLly, sinon le nouveau est refusé avec "<user> a déjà atteint le nombre maximum de sessions SQLly ouvertes".
  • Le contexte est figé au moment de la création - comme le profil. Les connexions sont résolues par rapport au profil tel qu'il est à ce moment-là.

Les erreurs sont détectées au moment de la création

Le pont vérifie l'ensemble open de la valeur avant de créer le jeton, votre serveur le détecte donc tout de suite au lieu qu'un utilisateur tombe sur un onglet cassé. Une mauvaise valeur est 400 invalid_open avec une entrée dans problems par erreur, chacune indiquant où elle se trouve. Aucun jeton n'est émis et aucun siège n'est consommé :

{
  "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)"
  ]
}

Les champs inconnus sont refusés plutôt qu’ignorés, donc une faute de frappe comme sql pour script échoue bruyamment. Les valeurs de type int, decimal et bool sont également vérifiés. D'autres types sont vérifiés par la barre de paramètres de SQLly avant l'exécution d'une requête.

Recettes

Rouvrir une requête depuis la piste d'audit

Le piste d'audit des requêtes enregistre chaque requête avec son profil, sa connexion, sa base de données et son SQL, ce qui est tout ce dont un lancement a besoin. La page des Requêtes de l'application exemple a un Rouvrir dans SQLly bouton sur chaque instruction complète. Il recherche de nouveau la ligne sur le pont (le formulaire nomme la ligne et rien d'autre), puis crée un lancement administrateur avec ce contexte :

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 });

Le SQL enregistré est ce qui a réellement été exécuté, donc les valeurs des paramètres y sont déjà des littéraux et aucun paramètre n’est nécessaire. Pour une instruction qui échoue, l’application exemple lit aussi où le moteur indique l’échec (le POSITION: 53, « à la ligne 2 » de MySQL) et l'envoie en tant que cursor, de sorte que le curseur se place sur la colonne problématique.

« Ouvrir dans SQLly » sur la page d’erreur de votre application

Si votre application exécute ses propres requêtes SQL (un générateur de rapports, un framework de pages piloté par SQL, des tâches programmées), elle sait au moment où une instruction échoue quelle était l'instruction, les valeurs qui y étaient liées et sur quelle base de données elle s'est exécutée. Mettez un bouton sur la page d'erreur qui génère un lancement avec cette instruction, ses valeurs comme paramètres et le curseur placé sur la ligne que la base de données a signalée. Le développeur obtient un environnement de travail complet sur cette requête, avec IntelliSense, l'explorateur d'objets et les plans d'exécution, sans rien copier à la main :

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,
  },
});

Ne proposez cela qu'aux personnes qui doivent avoir un atelier sur cette base de données, par exemple dans un environnement de développement ou pour les administrateurs. Le profil décide de ce qu'elles peuvent atteindre, exactement comme pour tout autre lancement.