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

TravailDans l'application exempleDans votre application
Connecter les utilisateursSon propre fichier d'utilisateurs avec des mots de passe scrypt (lib/auth.js)Votre connexion existante, SSO, sessions
Décider qui voit quelles connexionsChaque utilisateur se voit attribuer un profilVos 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 SQLlyGET /app/ crée un jeton et l'injecte dans index.htmlUne route qui fait la même chose (étape 4)
Servir le bundle web/app/* avec des en-têtes d'isolationVotre serveur de fichiers statiques ou chemin CDN avec les mêmes en-têtes (étape 5)
Places gratuitesPage des utilisateurs, Libérer le siègeAppelez-le lors de la déconnexion et lorsque l'accès est supprimé (étape 6)
Afficher l'état de la licencePage de statutUne vérification de santé ou un widget d'administration (étape 7)
Lien vers une licenceConnectez-vous à sqlly.appOptionnel : 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_profile avec problems en 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-PUT profil 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_select sur un environnement de production, ou confirm_data_changes sur 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 :

javascript (style express)
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 ttlSeconds entre 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.js relatif du bundle se résolve sur votre copie de web/.

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-origin et Cross-Origin-Embedder-Policy: require-corp sur la page et chaque fichier du bundle. SQLly nécessite SharedArrayBuffer, que les navigateurs n'activent que sur des pages isolées.
  • application/wasm comme 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' dans script-src, l'origine du pont wss:// origine dans connect-src, and a nonce or hash on the inline globals script (or the query-parameter form above). Large results are kept in browser storage by spill-worker.js, a worker script, which nonces don't cover: allow it with 'self' dans worker-src (or in script-src, qui worker-src falls 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_limit sur 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/seats liste 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à sessionsPerSeat est 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 :

  1. POST https://sqlly.app/api/embedded/links avec un nom d'affichage (par exemple "SQLly Embedded on " + hostname). Gardez le secret retourné côté serveur. Montrez à l'administrateur le code et envoyez-les à linkUrl.
  2. L'administrateur se connecte à sqlly.app, vérifie que le code correspond, choisit une licence et approuve.
  3. Pendant ce temps, interrogez POST https://sqlly.app/api/embedded/links/token avec { linkId, secret } chaque pollIntervalSeconds. Il répond 202 pendant l'attente, puis 200 une fois avec licenseKey. 410 signifie recommencer (refusé, expiré ou déjà utilisé).
  4. 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 montre license.source: "linked". Ne stockez pas la clé vous-même.
  5. 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_limit et license_not_ok afficher un message humain, pas une trace de pile.
  • Quelque chose surveille GET /manage/status.
  • Vous avez lu Passer en production.