Créer votre propre application
Étape par étape : pilotez le pont SQLly Embedded depuis votre propre application web - stockez les profils, créez des jetons de lancement, servez la version navigateur, libérez des sièges et liez les installations.
L'application exemple est un substitut de votre produit. Tout ce qu'elle fait passe par le pont, via API de gestion, donc toute pile côté serveur peut le remplacer : Node, ASP.NET, Django, Rails, Go, PHP. Cette page parcourt chaque tâche que l'application exemple effectue et comment la réaliser dans votre propre application. Les exemples sont en JavaScript (Node 20+) et C# (ASP.NET Core), et les mêmes appels fonctionnent depuis tout ce qui utilise HTTP et JSON.
Générez un client au lieu d'en écrire un. swagger.json est une description OpenAPI 3.0 de toute l'API de gestion. Donnez-la à openapi-generator, NSwag, Kiota ou à l'outil HTTP de votre choix. Le sample-app/lib/bridge.js est aussi un client complet écrit à la main en environ 120 lignes.
Ce que votre application prend en charge
| Travail | Dans l'application exemple | Dans votre application |
|---|---|---|
| Connecter les utilisateurs | Son propre fichier d'utilisateurs avec des mots de passe scrypt (lib/auth.js) | Votre connexion existante, SSO, sessions |
| Décider qui voit quelles connexions | Chaque utilisateur se voit attribuer un profil | Vos rôles, équipes, locataires ou plans sélectionnent l’identifiant du profil |
| Définir les connexions | Éditeur de profil, onglet Étiquettes (lib/credentials.js construit le document) | Votre interface d’administration, un fichier de configuration ou le code qui construit des documents à partir des données de votre locataire |
| Ouvrir SQLly | GET /app/ crée un jeton et l'injecte dans index.html | Une route qui fait la même chose (étape 4) |
| Servir le bundle web | /app/* avec des en-têtes d'isolation | Votre serveur de fichiers statiques ou chemin CDN avec les mêmes en-têtes (étape 5) |
| Places gratuites | Page des utilisateurs, Libérer le siège | Appelez-le lors de la déconnexion et lorsque l'accès est supprimé (étape 6) |
| Afficher l'état de la licence | Page de statut | Une vérification de santé ou un widget d'administration (étape 7) |
| Lien vers une licence | Connectez-vous à sqlly.app | Optionnel : ou configurer une clé ou un fichier de licence (étape 8) |
1. Exécutez le pont à côté de votre application
Sans le script de démarrage, le pont se lance en une seule commande. Générez le token de gestion une fois et donnez la même valeur au pont et à votre application (une variable d'environnement ou un gestionnaire de secrets, jamais votre dépôt) :
export SQLLY_EMBEDDED_MANAGE_TOKEN="$(openssl rand -base64 24)"
export SQLLY_EMBEDDED_LICENSE_KEY=sqe_… # or SQLLY_EMBEDDED_LICENSE_FILE, or neither and link later
./bin/sqlly-bridge embedded \
--domain portal.example.com \
--public-url wss://portal.example.com/sqlly/proxy \
--manage-bind 127.0.0.1:8445 \
--state-dir /var/lib/sqlly-embedded
Votre application communique avec http://127.0.0.1:8445 avec Authorization: Bearer $SQLLY_EMBEDDED_MANAGE_TOKEN. Les navigateurs atteignent l'écouteur proxy (:8444) via votre proxy inverse. Détails de production.
2. Un petit client de gestion
javascript (node 20+)const BRIDGE = process.env.SQLLY_BRIDGE_URL ?? 'http://127.0.0.1:8445';
const TOKEN = process.env.SQLLY_EMBEDDED_MANAGE_TOKEN;
export async function bridge(method, path, body) {
const res = await fetch(BRIDGE + path, {
method,
headers: {
authorization: `Bearer ${TOKEN}`,
...(body ? { 'content-type': 'application/json' } : {}),
},
body: body ? JSON.stringify(body) : undefined,
});
if (res.status === 204) return null;
const json = await res.json().catch(() => null);
if (!res.ok) {
// Every error is { error, message } (+ problems for invalid documents).
throw Object.assign(new Error(json?.message ?? `bridge HTTP ${res.status}`),
{ code: json?.error, status: res.status, problems: json?.problems });
}
return json;
}
c# (asp.net core)
builder.Services.AddHttpClient("sqlly-bridge", c =>
{
c.BaseAddress = new Uri(builder.Configuration["Sqlly:BridgeUrl"] ?? "http://127.0.0.1:8445");
c.DefaultRequestHeaders.Authorization =
new("Bearer", builder.Configuration["Sqlly:ManageToken"]);
});
public sealed record BridgeError(string Error, string Message, string[]? Problems);
public sealed record MintedToken(string Token, DateTimeOffset ExpiresAt, string ProxyUrl,
string User, string Profile, int SeatsUsed, int Seats);
3. Stocker les profils
Un profil est un Document d'identifiants SQLly plus un nom d'affichage. Construisez-le comme vous voulez : à partir de lignes de votre base de données, d'un modèle par locataire, ou d'un formulaire d'administration. GET /manage/engines liste chaque identifiant de moteur, son port par défaut, et quels types de connexion il accepte, afin qu'un formulaire ne les code jamais en dur.
await bridge('PUT', '/manage/profiles/acme-analysts', {
name: 'Acme analysts',
credentials: {
format: 'sqlly-credentials',
version: 1,
clients: [{ name: 'Acme', color: '#1E88E5' }],
environments: [{ name: 'Production', safety: { only_allow_select: true } }],
sql_auth_accounts: [{ name: 'Reader', username: 'acme_ro', password: secrets.acmeReader }],
connections: [
{ name: 'Orders', engine: 'postgres', server: 'pg1.internal', database: 'orders',
environment: 'production', client: 'Acme',
authentication: { type: 'sql-login', account: 'Reader' }, tls: { mode: 'verify-full' } },
],
},
});
- Les identifiants de profil font de 1 à 64 caractères parmi
A-Z a-z 0-9 _ -. Utilisez votre propre clé stable (un identifiant de locataire, un nom de rôle). - Le pont valide l'ensemble du document avant de l'enregistrer. Un document défectueux revient sous la forme
400 invalid_profileavecproblemsen listant chaque erreur. Les clés inconnues sont des erreurs, donc une faute de frappe ne passe jamais inaperçue. - Le pont est le registre officiel pour les secrets. Gardez la source de vérité où vous voulez, mais re-
PUTprofil lorsque cela change. L'application exemple renvoie chaque profil au démarrage, donc un répertoire d'état neuf se réapprovisionne lui-même. - Utilisez des étiquettes et des indicateurs de sécurité.
only_allow_selectsur un environnement de production, ouconfirm_data_changessur une connexion, sont appliqués par SQLly à tous ceux qui ouvrent ce profil.
Avant de sauvegarder, vous pouvez vérifier qu'une connexion fonctionne avec POST /manage/test-connection et un document contenant uniquement cette connexion. Les échecs reviennent sous forme de { "ok": false, "message": "<the engine's own error>" } avec HTTP 200, prêt à s'afficher à côté du formulaire.
4. Lancez SQLly pour un utilisateur connecté
C'est la route dont chaque intégration a besoin. Lorsqu'un utilisateur connecté ouvre SQLly, générez un jeton pour lui et renvoyez le index.html avec deux variables globales définies avant les boot.js tag du module :
import { readFile } from 'node:fs/promises';
const ISOLATION = {
'Cross-Origin-Opener-Policy': 'same-origin',
'Cross-Origin-Embedder-Policy': 'require-corp',
};
const BOOT_TAG = '<script type="module" src="./boot.js"></script>';
// JSON for an inline script: never let a value close the tag.
const js = (v) => JSON.stringify(v).replace(/</g, '\\u003c');
app.get('/sqlly/', requireSignIn, async (req, res) => {
const profile = profileFor(req.user); // your rule: role, team, tenant…
let minted;
try {
minted = await bridge('POST', '/manage/tokens', { user: req.user.id, profile });
} catch (err) {
if (err.code === 'seat_limit') return res.status(409).send('All SQLly seats are in use right now.');
if (err.code === 'license_not_ok') return res.status(503).send(err.message);
throw err;
}
const html = (await readFile('web/index.html', 'utf8')).replace(BOOT_TAG,
`<script>globalThis.SQLLY_PROXY_URL=${js(minted.proxyUrl)};` +
`globalThis.SQLLY_PROXY_TOKEN=${js(minted.token)};</script>` + BOOT_TAG);
res.set(ISOLATION).set('Cache-Control', 'no-store').type('html').send(html);
});
c# (api minimale asp.net core)
app.MapGet("/sqlly/", async (HttpContext http, IHttpClientFactory clients, IWebHostEnvironment env) =>
{
var user = http.User.FindFirst("sub")!.Value;
var bridge = clients.CreateClient("sqlly-bridge");
var reply = await bridge.PostAsJsonAsync("/manage/tokens", new { user, profile = ProfileFor(http.User) });
if (!reply.IsSuccessStatusCode)
{
var error = await reply.Content.ReadFromJsonAsync<BridgeError>();
return Results.Text(error?.Message ?? "SQLly is unavailable.", statusCode: (int)reply.StatusCode);
}
var minted = (await reply.Content.ReadFromJsonAsync<MintedToken>())!;
const string bootTag = "<script type=\"module\" src=\"./boot.js\"></script>";
// JsonSerializer escapes < > & by default, so the values can't close the tag.
var globals = $"<script>globalThis.SQLLY_PROXY_URL={JsonSerializer.Serialize(minted.ProxyUrl)};" +
$"globalThis.SQLLY_PROXY_TOKEN={JsonSerializer.Serialize(minted.Token)};</script>";
var html = (await File.ReadAllTextAsync(Path.Combine(env.ContentRootPath, "sqlly-web", "index.html")))
.Replace(bootTag, globals + bootTag);
http.Response.Headers["Cross-Origin-Opener-Policy"] = "same-origin";
http.Response.Headers["Cross-Origin-Embedder-Policy"] = "require-corp";
http.Response.Headers.CacheControl = "no-store";
return Results.Content(html, "text/html");
}).RequireAuthorization();
- Générez sur le serveur, à chaque requête. Ne mettez jamais le jeton de gestion dans une page. Le jeton de lancement peut être donné en toute sécurité à l'utilisateur pour lequel il a été créé : il ouvre SQLly avec ce profil uniquement pour cet utilisateur, et expire (10 minutes par défaut ; passer
ttlSecondsentre 10 et 86 400). - La réutilisation est correcte. Un jeton reste valable jusqu'à son expiration, donc les rechargements de page n'exigent pas de nouveau jeton. L'application exemple met en cache le jeton de chaque utilisateur et en recrée un une minute avant l'expiration. Recréer le jeton d'un même utilisateur ne coûte jamais de siège supplémentaire.
- Ouvrez une requête, pas seulement l’environnement de travail. Ajouter
openà l'appel de création de jeton (mint) pour amener l'utilisateur dans un onglet de requête avec le script, la connexion, les valeurs de paramètres et le curseur déjà définis. Générez un nouveau jeton pour chacun de ces lancements : les onglets ne s'ouvrent que pour la première session qu'un jeton démarre. Ouvrir SQLly sur une requête. - L'identifiant de l'utilisateur est le vôtre. Passez un identifiant stable et opaque. Les sièges comptent les identifiants distincts, et les identifiants qui occupent des sièges sont signalés à sqlly.app lors du check-in.
- Si vous ne pouvez pas modifier le HTML, passez
?proxy=<url>&token=<token>sur l'URL de la page à la place. L'injection est mieux, car le jeton reste hors de l'historique et des journaux. - Servez la page à une URL se terminant par
/(ici/sqlly/) de sorte que le./boot.jsrelatif du bundle se résolve sur votre copie deweb/.
5. Servir le bundle web
Servez les fichiers dans web/ sous le même chemin que la page de lancement (/sqlly/boot.js, /sqlly/sqlly_browser_bg.wasm, …), avec :
Cross-Origin-Opener-Policy: same-originetCross-Origin-Embedder-Policy: require-corpsur la page et chaque fichier du bundle. SQLly nécessiteSharedArrayBuffer, que les navigateurs n'activent que sur des pages isolées.application/wasmcomme type pour.wasm. La compression aide beaucoup ici : le fichier wasm devient plusieurs fois plus petit avec Brotli ou gzip.- Si vos pages envoient une Content-Security-Policy :
'wasm-unsafe-eval'dansscript-src, l'origine du pontwss://origine dansconnect-src, and a nonce or hash on the inline globals script (or the query-parameter form above). Large results are kept in browser storage byspill-worker.js, a worker script, which nonces don't cover: allow it with'self'dansworker-src(or inscript-src, quiworker-srcfalls back to). If it is blocked, large results stay in memory. - L'isolation cross-origin s'applique à tout ce que la page charge, donc servez le bundle depuis votre propre origine plutôt que depuis un CDN tiers sans en-têtes CORP.
Les fichiers du bundle sont versionnés avec le package. Quand vous effectuez une mise à niveau, remplacez web/ et le pont ensemble.
6. Gérer les sièges
409 seat_limitsur mint signifie que chaque siège est utilisé. Dites-le clairement à l'utilisateur et, pour les administrateurs, proposez d'en libérer un.GET /manage/seatsliste qui occupe les sièges et depuis quand.- Libérer lors de la déconnexion:
DELETE /manage/seats/{user}révoque les jetons de l'utilisateur et ferme ses onglets SQLly. Faites de même lorsque vous retirez l'accès de quelqu'un. Sinon, son jeton continue de fonctionner jusqu'à son expiration. - Un onglet supplémentaire au-delà
sessionsPerSeatest refusé par le pont lui-même : la socket reçoit le message « <user> a déjà ouvert le nombre maximum de sessions SQLly » et est fermée avec le code 4429, et SQLly affiche cette phrase.
7. Afficher la santé de la licence
GET /manage/status a tout ce qu'il faut pour un widget d'administration ou un contrôle de santé :
const s = await bridge('GET', '/manage/status');
// s.license.state: ok | grace | stale | not_admitted | expired | revoked | domain_mismatch | unlicensed
// s.license.message: the sentence your users see when something is wrong
// s.license.daysRemaining, s.license.planName, s.seatsUsed / s.license.seats
const healthy = ['ok', 'grace'].includes(s.license.state);
Alerter sur tout sauf ok, et considérer grace comme « renouveler cette semaine ». POST /manage/license/checkin force une vérification (ou relit un fichier hors ligne), ce qui est utile pour un Contacter maintenant après avoir corrigé l’accès réseau. Ce que chaque état signifie.
8. Lier une licence depuis votre interface administrateur (optionnel)
Vous pouvez configurer le pont avec une clé ou un fichier de licence et ignorer ceci. La liaison est pour les produits qui installent SQLly Embedded pour de nombreux clients : l'administrateur de chaque client connecte son installation à sa propre licence sqlly.app en quelques clics, et aucune clé n'est jamais copiée. Démarrez le pont sans --license-key ni --license-file, puis :
POST https://sqlly.app/api/embedded/linksavec un nom d'affichage (par exemple"SQLly Embedded on " + hostname). Gardez lesecretretourné côté serveur. Montrez à l'administrateur lecodeet envoyez-les àlinkUrl.- L'administrateur se connecte à sqlly.app, vérifie que le code correspond, choisit une licence et approuve.
- Pendant ce temps, interrogez
POST https://sqlly.app/api/embedded/links/tokenavec{ linkId, secret }chaquepollIntervalSeconds. Il répond202pendant l'attente, puis200une fois aveclicenseKey.410signifie recommencer (refusé, expiré ou déjà utilisé). - Passez la clé directement au pont :
PUT /manage/license { "licenseKey": "…" }. Le pont la vérifie avec sqlly.app avant de la stocker, la conserve malgré les redémarrages, et le statut montrelicense.source: "linked". Ne stockez pas la clé vous-même. - Pour se déconnecter,
DELETE /manage/license: le pont libère son emplacement, révoque la clé sur sqlly.app et revient à l'état sans licence.
Dans l'application exemple, lib/sqllyapp.js et ses /admin/link implémentent exactement cela.
Avant de livrer
- Le jeton de gestion se trouve dans la configuration côté serveur et l'API de gestion est liée à loopback ou à un réseau privé.
- Chaque lancement est émis côté serveur pour un utilisateur authentifié, avec un profil choisi par vos règles d'autorisation.
- La page et le bundle SQLly transportent les en-têtes d'isolation, et votre CSP autorise ceux du pont
wss://origine. - La déconnexion et la suppression d'accès libèrent le siège de l'utilisateur.
seat_limitetlicense_not_okafficher un message humain, pas une trace de pile.- Quelque chose surveille
GET /manage/status. - Vous avez lu Passer en production.