Référence de l’API

Chaque point de terminaison de l'API de gestion du pont SQLly Embedded, généré à partir de son document OpenAPI (swagger.json), plus les points de terminaison de liaison sqlly.app.

Télécharger swagger.json OpenAPI 3.0 version 1.0.0 base http://127.0.0.1:8445

Le pont SQLly en mode embarqué expose cette API sur son écouteur de gestion (--manage-bind, par défaut 127.0.0.1:8445). Votre application web l'appelle depuis son côté serveur pour stocker des profils de connexion, tester des connexions, créer des jetons de lancement pour les utilisateurs connectés, suivre les postes attribués et lire ou modifier l'état de la licence.

Chaque /manage/... appel nécessite Authorization: Bearer <manage token> (le --manage-token, au moins 16 caractères). Les corps sont en JSON en entrée et sortie, au maximum 8 Mo (refusé avec 413 too_large dès que la limite est dépassée). Les segments de chemin et les valeurs de la chaîne de requête sont décodés en pourcentage ; une séquence d'échappement invalide est 400 bad_request. Les erreurs sont toujours { "error": "<code>", "message": "<sentence>" }, ainsi que problems lorsqu'un document d'identification est invalide. L'API n'envoie aucun en-tête CORS : gardez-la sur la boucle locale ou un réseau privé et ne l'exposez jamais aux navigateurs, car les profils contiennent les mots de passe des bases de données.

Le Linking les opérations ne sont pas sur le pont : ce sont les points de terminaison publics de sqlly.app qu'une application d'administration utilise pour lier une installation à une licence sans copier de clé. Leur serveur est sqlly.app.

Guide : sqlly.app/docs/embedded

Conventions

  • Authentification : Authorization: Bearer <manage token> à chaque fois /manage/… appel. Un jeton manquant ou incorrect est 401 unauthorized. /healthz et les points de liaison de sqlly.app n'en nécessitent aucun.
  • Erreurs sont { "error": "<code>", "message": "<sentence>" }. Branchez sur error; affichez message. Les documents d'identifiants invalides ajoutent problems, une chaîne par erreur.
  • Corps sont du JSON, au maximum 8 Mo. La limite est appliquée pendant la réception du corps : le pont répond 413 too_large dès qu'il est transmis, sans jamais rien mettre de plus en mémoire tampon. Un corps qui met plus de 30 secondes à arriver est 408 timeout. Tout ce qui ne peut pas être analysé est 400 bad_json, et une route inconnue est 404 not_found.
  • Segments de chemin et valeurs de requête sont décodés à partir de l'encodage pourcentage, donc encodez en URL les identifiants d'utilisateur et les horodatages (DELETE /manage/seats/a%2Fb libère l'utilisateur a/b). Une séquence d'échappement invalide ou un résultat qui n'est pas en UTF-8 est 400 bad_request.
  • Noms de champs sont en camelCase dans les charges utiles de l'API. Dans un document d'identifiants, ils suivent le format des identifiants (sql_auth_accounts, trust_server_certificate).

Points de terminaison

Santé

Vérification de disponibilité, pas de jeton nécessaire.

GET /healthz pas de jeton

Sonde de disponibilité

Répond dès que l'écouteur de gestion est actif. Aucun jeton n'est nécessaire ; utilisez-le à partir des scripts de démarrage et des contrôles de santé des services.

200
L’API de gestion est en écoute.
Exemple de réponse 200
{
  "ok": true
}

Licence

La licence sous laquelle le pont fonctionne : état, enregistrement, liaison et dissociation.

GET /manage/status

Statut du pont et de la licence

Tout ce dont un écran d'administration a besoin : l'état de la licence et son origine, les droits que porte l'attribution signée, les sièges en cours d'utilisation, les sessions ouvertes et l'URL du proxy utilisée par les navigateurs.

200
Statut actuel.
401
unauthorized: le jeton de gestion est manquant ou incorrect.
Exemple de réponse 200
{
  "version": "1.1.0",
  "instanceId": "b5e1c0f2-7d3a-4c8e-9a61-0f2d4b7e9c13",
  "mode": "connected",
  "license": {
    "state": "ok",
    "source": "linked",
    "licenseId": "emb_Q2x0b3VkU3FsbHkxMjM0NTY3",
    "plan": "embedded-25",
    "planName": "SQLly Embedded 25",
    "status": "active",
    "seats": 25,
    "sessionsPerSeat": 4,
    "instances": 1,
    "domain": "portal.example.com",
    "periodEnd": "2027-10-14T00:00:00+00:00",
    "graceEnd": null,
    "daysRemaining": 365,
    "lastCheckinAt": "2026-10-14T15:00:02Z",
    "staleAt": "2026-10-14T15:40:02Z",
    "licenseFile": null,
    "message": null,
    "fromCache": false,
    "features": [
      "embedded",
      "unlimited-connections",
      "all-engines",
      "test-connection"
    ]
  },
  "seatsUsed": 3,
  "activeSessions": 4,
  "proxyUrl": "wss://portal.example.com/sqlly/proxy",
  "allowLocalhostOrigins": false,
  "storeUrl": "https://sqlly.app",
  "allowFileEngines": false
}
Exemple de réponse 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}
POST /manage/license/checkin

Contactez sqlly.app maintenant

Licences connectées et liées : effectue immédiatement un contrôle auprès du serveur au lieu d'attendre la boucle de 20 minutes. Licences hors ligne : relit le fichier de licence et ne touche jamais au réseau. Dans tous les cas, la réponse est le statut après la tentative ; un échec laisse l'état inchangé.

200
Statut après l'enregistrement.
401
unauthorized: le jeton de gestion est manquant ou incorrect.
409
not_linked: le pont est sans licence, il n'y a rien à signaler au serveur.
422
license_file_invalid (hors ligne) : le fichier est manquant, endommagé ou signé pour une autre clé.
502
store_unreachable ou grant_invalid: sqlly.app n'a pas pu être atteint, ou sa réponse n'a pas été vérifiée.
Exemple de réponse 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}
Exemple de réponse 409
{
  "error": "not_linked",
  "message": "this bridge is not linked to a license yet"
}
PUT /manage/license

Installer une clé de licence liée

Donne à un pont démarré sans --license-key / --license-file sa clé à l'exécution (normalement la clé que votre application d'admin vient de récupérer auprès de sqlly.app via le flux de liaison). Le pont s'enregistre d'abord avec elle et la stocke (<state-dir>/license-key, mode 0600) seulement si sqlly.app répond avec une autorisation vérifiée ; à partir de ce moment-là, il fonctionne comme un pont connecté, et la clé est réutilisée après les redémarrages. Rien ne change en cas d'échec : la clé utilisée continue de servir jusqu'à ce que la nouvelle soit vérifiée. Remplacer une clé liée par une autre d'une autre licence libère l'emplacement d'instance de l'ancienne licence après que la nouvelle clé soit vérifiée ; une clé régénérée de la même licence réutilise la ligne d'instance du magasin.

Corps de la requête (LinkLicenseRequest)
{
  "licenseKey": "sqe_2xH7c0VqHk9LmZr1aPq4tN8bW6yD3sJfUe5o"
}
200
Lié. Le statut affiche maintenant license.source: linked.
400
invalid_license_key: clé vide, mal formée, inconnue ou révoquée.
401
unauthorized: le jeton de gestion est manquant ou incorrect.
409
license_from_flag: le pont a été démarré avec --license-key ou --license-file, donc sa licence n'est pas gérée via cette API.
502
store_unreachable: sqlly.app n'a pas pu être atteint ou sa réponse n'a pas été vérifiée.
Exemple de réponse 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}
DELETE /manage/license

Dissocier cette installation

Libère l'emplacement d'instance de ce pont, révoque sa clé sur sqlly.app (dans la mesure du possible), supprime la clé stockée, ferme toutes les sessions ouvertes et renvoie le pont à unlicensed.

204
Dissocié.
401
unauthorized: le jeton de gestion est manquant ou incorrect.
404
not_linked: aucune clé liée n'est enregistrée.
409
license_from_flag: le pont a été démarré avec --license-key ou --license-file, donc sa licence n'est pas gérée via cette API.
Exemple de réponse 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}

Moteurs

Les moteurs de base de données acceptés par le format d'identifiants, donc votre interface utilisateur ne code jamais en dur la liste.

GET /manage/engines

Moteurs acceptés par le format d'identifiants

Chaque moteur de base de données pris en charge par SQLly, avec le engine id à écrire dans un document d'identification, son port par défaut, si server est un chemin de fichier, et les authentication.type valeurs qu'il accepte.

200
Les moteurs.
401
unauthorized: le jeton de gestion est manquant ou incorrect.
Exemple de réponse 200
[
  {
    "id": "sql-server",
    "name": "Microsoft SQL Server",
    "defaultPort": 1433,
    "fileBased": false,
    "authentication": [
      "sql-login",
      "integrated",
      "entra-browser",
      "entra-device-code"
    ]
  },
  {
    "id": "postgres",
    "name": "PostgreSQL",
    "defaultPort": 5432,
    "fileBased": false,
    "authentication": [
      "sql-login"
    ]
  },
  {
    "id": "sqlite",
    "name": "SQLite",
    "defaultPort": 0,
    "fileBased": true,
    "authentication": [
      "none"
    ]
  }
]
Exemple de réponse 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}

Profils

Un profil est un document d'identifiants SQLly nommé : les connexions (et étiquettes) que voit un groupe d'utilisateurs. Le pont est le magasin de référence ; les secrets n'atteignent jamais le navigateur.

GET /manage/profiles

Lister les profils

Chaque profil stocké sans ses identifiants.

200
Les profils.
401
unauthorized: le jeton de gestion est manquant ou incorrect.
Exemple de réponse 200
[
  {
    "id": "analysts",
    "name": "Analysts",
    "connections": 2,
    "updatedAt": "2026-10-14T15:02:11Z"
  }
]
Exemple de réponse 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}
GET /manage/profiles/{id}

Lire un profil

Le profil avec son document d'identification complet, secrets inclus : l'appelant est votre application serveur de confiance.

id
chemin · chaîne correspondant à ^[A-Za-z0-9_-]{1,64}$ · obligatoire - Votre identifiant pour le profil.
200
Le profil.
400
invalid_profile_id: les identifiants sont de 1 à 64 de A-Z a-z 0-9 _ -.
401
unauthorized: le jeton de gestion est manquant ou incorrect.
404
unknown_profile: aucun profil n'a cet identifiant.
Exemple de réponse 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}
Exemple de réponse 404
{
  "error": "unknown_profile",
  "message": "no profile with id analysts"
}
PUT /manage/profiles/{id}

Créer ou remplacer un profil

Stocke le profil sous id (créer ou remplacer). Le document d'identification est entièrement validé avant toute écriture : chaque problème trouvé par le parseur est renvoyé dans problems, et un document invalide ne change rien. Un document contenant un moteur basé sur un fichier (SQLite, DuckDB) est refusé de la même manière sauf si le pont fonctionne avec --allow-file-engines true, parce qu'une telle connexion offre à ses utilisateurs un accès aux fichiers sur l'hôte du pont. Les sessions déjà ouvertes conservent le catalogue avec lequel elles ont commencé ; les modifications s'appliquent au prochain lancement.

id
chemin · chaîne correspondant à ^[A-Za-z0-9_-]{1,64}$ · obligatoire - Votre identifiant pour le profil.
Corps de la requête (PutProfileRequest)
{
  "name": "Analysts",
  "credentials": {
    "format": "sqlly-credentials",
    "version": 1,
    "clients": [
      {
        "name": "Northwind Traders",
        "color": "#1E88E5"
      }
    ],
    "environments": [
      {
        "name": "Production",
        "color": "#C62828",
        "safety": {
          "only_allow_select": true
        }
      }
    ],
    "sql_auth_accounts": [
      {
        "name": "Reader",
        "username": "reader",
        "password": "…"
      }
    ],
    "connections": [
      {
        "name": "Northwind",
        "engine": "sql-server",
        "server": "sql01.internal",
        "database": "Northwind",
        "environment": "production",
        "client": "Northwind Traders",
        "authentication": {
          "type": "sql-login",
          "account": "Reader"
        },
        "tls": {
          "encrypt": true,
          "trust_server_certificate": true
        }
      },
      {
        "name": "Warehouse",
        "engine": "postgres",
        "server": "dw.internal",
        "database": "dw",
        "environment": "production",
        "client": "Northwind Traders",
        "authentication": {
          "type": "sql-login",
          "account": "Reader"
        },
        "tls": {
          "mode": "verify-full"
        }
      }
    ]
  }
}
200
Enregistré.
400
invalid_profile (avec problems: problèmes de l'analyseur, ou chaque moteur basé sur des fichiers pendant --allow-file-engines est désactivé), ou invalid_profile_id.
401
unauthorized: le jeton de gestion est manquant ou incorrect.
500
storage: le répertoire d'état n'a pas pu être écrit.
Exemple de réponse 400
{
  "error": "invalid_profile",
  "message": "the credential document has 2 problems",
  "problems": [
    "connections[0].engine: unknown engine \"postgress\"",
    "connections[1].authentication.pasword: unknown key"
  ]
}
Exemple de réponse 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}
DELETE /manage/profiles/{id}

Supprimer un profil

Supprime le profil. Les sessions ouvertes conservent le catalogue avec lequel elles ont démarré ; les nouveaux jetons de lancement pour ce profil sont refusés avec unknown_profile.

id
chemin · chaîne correspondant à ^[A-Za-z0-9_-]{1,64}$ · obligatoire - Votre identifiant pour le profil.
204
Supprimé.
400
invalid_profile_id: les identifiants sont de 1 à 64 de A-Z a-z 0-9 _ -.
401
unauthorized: le jeton de gestion est manquant ou incorrect.
404
unknown_profile: aucun profil n'a cet identifiant.
Exemple de réponse 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}
Exemple de réponse 404
{
  "error": "unknown_profile",
  "message": "no profile with id analysts"
}

Lancer

Les jetons de lancement ouvrent SQLly pour un utilisateur avec un profil. Un siège correspond à un utilisateur simultané.

POST /manage/tokens

Créer un jeton de lancement

Crée un jeton de courte durée qui ouvre SQLly pour user avec profile, éventuellement directement dans les onglets de requêtes (open, le contexte de lancement). Mettez le proxyUrl et token renvoyé dans la page qui charge SQLly (globalThis.SQLLY_PROXY_URL / globalThis.SQLLY_PROXY_TOKEN). Le jeton peut être réutilisé jusqu'à ce qu'il expire (rechargement de la page), et le profil est enregistré au moment de la création.

Un utilisateur occupe un siège tant qu'il a une session ouverte ou un jeton non expiré. Générer un jeton pour un utilisateur qui occupe déjà un siège n'échoue jamais à cause du nombre de sièges ; en générer un pour un nouvel utilisateur échoue avec seat_limit lorsque toutes les places de la licence sont utilisées, en comptant les utilisateurs sur chacun des ponts de la licence.

Corps de la requête (MintTokenRequest)
{
  "user": "dana.analyst",
  "profile": "analysts",
  "open": {
    "connection": "Shop",
    "database": "sales",
    "title": "Big orders",
    "script": "SELECT *\nFROM orders\nWHERE total > @min_total",
    "parameters": {
      "min_total": 500
    },
    "cursor": {
      "line": 3,
      "column": 7
    }
  }
}
201
Le jeton.
400
invalid_user (vide ou contient des espaces, au maximum 128 caractères), invalid_profile (le profil stocké n’est plus valide, ou contient un moteur basé sur un fichier tandis que --allow-file-engines est désactivé), ou invalid_open (le contexte de lancement mentionne une connexion inconnue, un champ ou type inconnu, un mauvais nom ou valeur de paramètre, un curseur hors limites, ou dépasse une limite; problems liste chaque erreur avec son chemin, par exemple open[1].cursor: …).
401
unauthorized: le jeton de gestion est manquant ou incorrect.
404
unknown_profile: aucun profil n'a cet identifiant.
409
seat_limit: chaque siège est utilisé. Libérez-en un (DELETE /manage/seats/{user}) ou achetez un plan plus grand.
503
license_not_ok: la licence n’est pas ok ou grace (périmé, expiré, révoqué, non admis, domaine non correspondant ou sans licence). Le message indique lequel.
Exemple de réponse 201
{
  "token": "elt_q3J0n8w2Zx5rVb1kTq9yLs4dHf7cMa6p",
  "expiresAt": "2026-10-14T15:12:11Z",
  "proxyUrl": "wss://portal.example.com/sqlly/proxy",
  "user": "dana.analyst",
  "profile": "analysts",
  "seatsUsed": 3,
  "seats": 25,
  "openTabs": 0
}
Exemple de réponse 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}
GET /manage/seats

Sièges utilisés

Utilisateurs occupant un siège sur ce pont, avec leurs sessions ouvertes et leurs jetons actifs. seatsUsed compte également les utilisateurs signalés par sqlly.app sur d’autres ponts de la même licence.

200
Utilisation des sièges.
401
unauthorized: le jeton de gestion est manquant ou incorrect.
Exemple de réponse 200
{
  "seats": 25,
  "seatsUsed": 2,
  "users": [
    {
      "user": "dana.analyst",
      "activeSessions": 1,
      "tokens": 1,
      "since": "2026-10-14T15:02:11Z"
    },
    {
      "user": "sam.support",
      "activeSessions": 2,
      "tokens": 1,
      "since": "2026-10-14T14:40:03Z"
    }
  ]
}
Exemple de réponse 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}
DELETE /manage/seats/{user}

Libérer le siège d'un utilisateur

Révoque les jetons de l'utilisateur et ferme ses sessions, libérant ainsi immédiatement le siège. Appelez cette fonction lorsqu'un utilisateur se déconnecte de votre application ou perd l'accès. Libérer un utilisateur qui ne détient aucun siège n'est pas une erreur. Le segment de chemin est décodé (décodage pourcent, comme dans une URL) : a%2Fb libère l'utilisateur a/b.

utilisateur
chemin · chaîne · obligatoire - L'identifiant utilisateur pour lequel vous avez émis des jetons (codé en URL).
204
Publié.
400
bad_request: le segment n'est pas un encodage de pourcentage valide.
401
unauthorized: le jeton de gestion est manquant ou incorrect.
Exemple de réponse 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}

Connexions

Vérifiez qu'une connexion fonctionne avant que quiconque ne l'utilise.

POST /manage/test-connection

Tester une connexion

Exécute un moteur éphémère sur un document d'identifiants ne contenant qu'une seule connexion et exécute une requête triviale. Les échecs de connexion sont signalés comme ok: false avec le message du moteur lui-même (HTTP 200) ; seul un document inutilisable est une erreur HTTP.

Corps de la requête (TestConnectionRequest)
{
  "credentials": {
    "format": "sqlly-credentials",
    "version": 1,
    "connections": [
      {
        "name": "Northwind",
        "engine": "sql-server",
        "server": "sql01.internal",
        "database": "Northwind",
        "authentication": {
          "type": "sql-login",
          "username": "reader",
          "password": "…"
        },
        "tls": {
          "encrypt": true,
          "trust_server_certificate": true
        }
      }
    ]
  }
}
200
Le résultat, succès ou échec.
400
invalid_profile: le document est invalide, ne contient pas exactement une connexion, ou contient un moteur basé sur un fichier alors que --allow-file-engines est désactivé (voir problems).
401
unauthorized: le jeton de gestion est manquant ou incorrect.
Exemple de réponse 200
{
  "ok": true,
  "elapsedMs": 212,
  "message": "Connected: SQL Server 17.0"
}
Exemple de réponse 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}

Audit

La piste d'audit des requêtes : chaque requête et modification de ligne qu'une session a exécutée, qui l'a exécutée, contre quelle connexion, et comment cela s'est terminé. Conservé en mémoire et dans <state-dir>/queries.jsonl (texte SQL inclus) à moins que le pont ne fonctionne avec --query-log false.

GET /manage/queries

Piste d'audit des requêtes

Chaque requête et modification de ligne que les sessions du pont ont exécutée, la plus récente en premier : l'utilisateur et le profil du jeton de lancement, la connexion qu'il a nommée (nom, serveur, moteur, base de données), le texte SQL (limité à 64 KiB, voir sqlTruncated), quand il a commencé, son statut et sa durée, et l'erreur du moteur lorsqu'il a échoué. Les requêtes encore en cours sont listées avec leur statut running; une requête refusée parce que la licence n'était pas en règle est failed avec le message de licence ; tout ce qui tournait au moment où la session s'est fermée est cancelled avec l'erreur session closed.

Le pont conserve les entrées les plus récentes --query-log-max-entries (20 000 par défaut) en mémoire et dans <state-dir>/queries.jsonl, donc la trace survit à un redémarrage. Avec --query-log false rien n'est enregistré et la réponse est { "enabled": false, "queries": [] }.

limite
requête · entier - Entrées à renvoyer, plafonnées à 1-1000.
utilisateur
requête · chaîne - Uniquement cet identifiant d'utilisateur (correspondance exacte, encodé pour l'URL).
profil
requête · chaîne - Uniquement cet identifiant de profil (correspondance exacte).
depuis
requête · chaîne (date-heure) - Uniquement les entrées dont at est à ou après ce timestamp RFC 3339 (encodé dans l'URL).
statut
requête · QueryStatus - Uniquement les entrées ayant ce statut.
200
Les entrées correspondantes, les plus récentes d'abord.
400
bad_request: limit n'est pas un nombre entier, since n'est pas RFC 3339, status est inconnu, ou une valeur n'est pas un encodage de pourcentage valide.
401
unauthorized: le jeton de gestion est manquant ou incorrect.
Exemple de réponse 200
{
  "enabled": true,
  "total": 2,
  "limit": 200,
  "queries": [
    {
      "id": "q-7",
      "sessionId": 12,
      "kind": "query",
      "at": "2026-10-14T15:04:09.120Z",
      "user": "dana.analyst",
      "profile": "analysts",
      "profileName": "Analysts",
      "connection": "Northwind",
      "server": "sql01.internal",
      "database": "Northwind",
      "engine": "Microsoft SQL Server",
      "sql": "SELECT TOP 100 * FROM Orders",
      "sqlTruncated": false,
      "status": "completed",
      "durationMs": 184,
      "error": null
    },
    {
      "id": "q-6",
      "sessionId": 12,
      "kind": "query",
      "at": "2026-10-14T15:03:51.004Z",
      "user": "dana.analyst",
      "profile": "analysts",
      "profileName": "Analysts",
      "connection": "Northwind",
      "server": "sql01.internal",
      "database": "Northwind",
      "engine": "Microsoft SQL Server",
      "sql": "SELECT * FROM Ordres",
      "sqlTruncated": false,
      "status": "failed",
      "durationMs": 31,
      "error": "Invalid object name 'Ordres'."
    }
  ]
}
Exemple de réponse 401
{
  "error": "unauthorized",
  "message": "management token missing or wrong"
}

Liaison

points de terminaison sqlly.app (serveur sqlly.app) pour lier une installation à une licence : créez un code, le propriétaire l'approuve dans son navigateur, récupérez la clé de l'installation une seule fois, puis transmettez-la au pont avec PUT /manage/license.

GET /api/embedded/public-key sqlly.app pas de jeton

Clé publique de signature de licence (sqlly.app)

La clé publique PEM que sqlly.app utilise pour signer les licences, afin qu'un opérateur puisse la comparer avec la clé compilée dans le bridge.

200
Texte PEM.
503
signing_not_configured.

Schémas

Les objets ci-dessus, tels que définis dans swagger.json. Une ? après un type signifie qu’il peut être null.

Erreur

Chaque réponse d'erreur. error est un code machine stable ; message est une phrase que vous pouvez montrer à un administrateur.

ChampTypeDescription
error * string
message * string
problems string[] Présent pour invalid_profile: chaque problème que l'analyseur d'identifiants a trouvé.

LicenseState

ok et grace servir les requêtes ; tout autre état refuse de traiter la demande avec un message que SQLly affiche à ses utilisateurs.

Un parmi : ok grace stale not_admitted expired revoked domain_mismatch unlicensed

StatusReport

ChampTypeDescription
version string Version du pont.
instanceId string L'identifiant de ce processus de pont, tel que sqlly.app le voit.
mode connected | offline
license LicenseReport
seatsUsed integer Sièges utilisés sur tous les ponts de la licence.
activeSessions integer Sessions SQLly ouvertes sur ce pont.
proxyUrl string L'URL WebSocket utilisée par les navigateurs (--public-url).
allowLocalhostOrigins boolean
storeUrl string
allowFileEngines boolean Si les profils peuvent contenir des moteurs basés sur des fichiers (--allow-file-engines).

Rapport de licence

Les droits viennent de l'octroi signé, jamais de données non signées.

ChampTypeDescription
state LicenseState
source flag | file | linked | none flag: --license-key; file: --license-file; linked: stocké par PUT /manage/license; none: sans licence.
licenseId string?
plan string? Identifiant du plan, ou custom pour une licence délivrée avec ses propres conditions.
planName string?
status string? Statut de sqlly.app depuis le dernier enregistrement : actif, période de grâce, expiré, révoqué, incompatibilité de domaine.
seats integer Utilisateurs concurrents autorisés par la licence.
sessionsPerSeat integer Onglets SQLly ouverts qu’un même utilisateur peut avoir.
instances integer Ponts pouvant fonctionner simultanément (licences connectées ; 0 hors ligne).
domain string? Domaine lié ; les navigateurs doivent provenir de celui-ci ou d’un sous-domaine.
periodEnd string? Fin de la période payante (ISO 8601).
graceEnd string? Défini pendant la période de grâce : le moment où le pont cesse de répondre.
daysRemaining integer? Nombre de jours entiers avant que le pont ne cesse de servir.
lastCheckinAt string (date-time)?
staleAt string (date-time)? Quand le pont est considéré comme périmé si aucun check-in ne réussit (dernière autorisation valide + 40 minutes).
licenseFile string? Hors ligne : le fichier de licence en cours d’utilisation.
message string? La phrase que les utilisateurs voient lorsqu'il y a un problème (y compris les délais de grâce).
fromCache boolean Vrai lorsque le pont a démarré avec l’autorisation qu’il avait en cache, parce que sqlly.app était injoignable.
features string[]

LinkLicenseRequest

ChampTypeDescription
licenseKey * string Une clé commençant sqe_.

EngineInfo

ChampTypeDescription
id string Le engine valeur pour un document d'identification.
name string
defaultPort integer
fileBased boolean server est un chemin de fichier et aucune authentification ne s'applique.
authentication string[] Accepté authentication.type valeurs.

ProfileSummary

ChampTypeDescription
id string
name string
connections integer Nombre de connexions dans le document.
updatedAt string (date-time)

StoredProfile

ChampTypeDescription
id string
name string
credentials CredentialDocument
updatedAt string (date-time)

PutProfileRequest

ChampTypeDescription
name * string Nom d’affichage, visible par les utilisateurs dans SQLly.
credentials * CredentialDocument

CredentialDocument

Un document d'identifiants SQLly (le même format que Fichier → Importer les connexions de SQLly). Les clés inconnues sont des erreurs, donc les fautes de frappe sont signalées au lieu d'être ignorées. Référence complète : sqlly.app/docs (Format du fichier d'identifiants).

ChampTypeDescription
format * sqlly-credentials
version * 1
clients Label[]
projects Label[]
environments Label[]
sql_auth_accounts SharedLogin[]
tunnel_profiles object[]
connections Connection[]

Étiquette

ChampTypeDescription
name * string
color string #RGB, #RRGGBB ou #RRGGBBAA.
image string Icône sous forme d'URI data: ou de base64 brut (PNG, JPEG, GIF, WebP, BMP, ICO, SVG ; jusqu'à 1 Mo).
safety object Seuls les indicateurs que vous listez changent.

SharedLogin

ChampTypeDescription
name * string
username * string
password string

Connexion

ChampTypeDescription
name * string
engine * string Un identifiant provenant de GET /manage/engines.
server * string Hôte, IP, hôte\instance ou un chemin de fichier pour SQLite/DuckDB.
port integer
database string
environment string local, dev, test, staging, production ou non défini.
client string Un nom d'étiquette client.
project string Un nom d'étiquette de projet.
authentication Authentication
tls object
timeout_seconds integer
statement_timeout_seconds integer
application_name string
safety object
favorite boolean
startup_sql string
tunnel_profile string
transport object Proxy intégré, sauts SSH et kube.
masking object { include: [...], exclude: [...] } Règles de masquage des colonnes.

Authentification

ChampTypeDescription
type * sql-login | integrated | entra-browser | entra-device-code | aws-rds-iam | gcp-cloud-sql-iam | auth-token | none
username string
password string
account string Nom d'une connexion partagée dans sql_auth_accounts.
region string
profile string
token string

MintTokenRequest

ChampTypeDescription
user * string Votre identifiant stable pour l’utilisateur (pas d’espace). Les sièges sont comptés par utilisateur distinct.
profile * string Un identifiant de profil.
ttlSeconds integer Durée de vie du jeton ; par défaut --token-ttl-seconds (600) et est limitée de 10 s à 24 h.
open LaunchTab | LaunchTab[] Contexte de lancement : un onglet de requête, ou jusqu'à 8, que SQLly ouvre au démarrage de la session. La première session admise par le jeton les reçoit ; les rechargements et les sessions suivantes, non. Validé par rapport au profil au moment de l'émission (400 invalid_open). Rien ne s'exécute tant que l'utilisateur n'appuie pas sur Exécuter. Guide : sqlly.app/docs/embedded/launch-context

Onglet de lancement

Un onglet de requête par lancement. Nécessite un script, un connection, ou les deux.

ChampTypeDescription
connection string Une connexion du profil du jeton, par nom (insensible à la casse, doit être unique) ou par identifiant. Facultatif quand le profil n'a qu'une seule connexion ; avec plusieurs et aucune nommée, l'onglet s'ouvre sans liaison.
database string Base de données à utiliser au lieu de la valeur par défaut de la connexion.
title string Le titre de l'onglet.
script string Le SQL à charger, tel quel (au maximum 256 KiB ; CRLF est transformé en LF).
parameters object Valeurs pour les @name paramètres, indexés par nom (avec ou sans @). Le type d'une valeur brute est inféré (nombre entier int, autre nombre decimal, booléen bool, chaîne text, null empty) ; utilisez { type, value } pour choisir. Les paramètres que le script ne déclare pas obtiennent une ligne -- sqlly param: ligne ; les valeurs apparaissent dans la bande de paramètres de SQLly et ne sont jamais insérées par votre application.
cursor LaunchCursor

LaunchParameterValue

ChampTypeDescription
type text | int | decimal | bool | date | datetime | time | uuid | json | binary
value string | number | boolean

LaunchCursor

Position du caret dans script, indexée à partir de 1 ; la colonne compte les caractères et peut se trouver juste après la fin de la ligne.

ChampTypeDescription
line integer
column integer

MintedToken

ChampTypeDescription
token string
expiresAt string (date-time)
proxyUrl string
user string
profile string
seatsUsed integer Sièges utilisés incluant cet utilisateur.
seats integer
openTabs integer Nombre d'onglets que la session ouvrira (0 sans contexte de lancement).

SeatsReport

ChampTypeDescription
seats integer
seatsUsed integer
users UserSeat[]

UserSeat

ChampTypeDescription
user string
activeSessions integer
tokens integer Jetons de lancement non expirés.
since string (date-time)

TestConnectionRequest

ChampTypeDescription
credentials * CredentialDocument

TestOutcome

ChampTypeDescription
ok boolean
elapsedMs integer
message string Le message du moteur lui-même, succès ou échec.

QueryStatus

running jusqu'à ce que le moteur réponde ; puis completed, failed (voir error) ou cancelled (par l'utilisateur, ou session closed).

Un parmi : running completed failed cancelled

QueryEntry

Une seule requête auditée.

ChampTypeDescription
id string L'identifiant de requête du moteur, unique au sein de sa session.
sessionId integer L'identifiant du pont pour la session du navigateur.
kind query | row-edit
at string (date-time) Quand la demande a atteint le pont.
user string L'identifiant utilisateur du jeton de lancement.
profile string L'identifiant du profil du jeton de lancement.
profileName string
connection string Le nom de la connexion dans le profil.
server string
database string? La base de données du profil quand il en épingle une, sinon celle que nomme la requête.
engine string Le nom d'affichage du moteur.
sql string Le texte SQL, ou row edit: <op> pour une édition de ligne. Limité à 64 KiB.
sqlTruncated boolean
status QueryStatus
durationMs integer? Null pendant l'exécution.
error string? L'erreur du moteur pour failed; session closed pour une requête interrompue par la fin de sa session.

QueryListing

ChampTypeDescription
enabled boolean Faux lorsque le pont fonctionne avec --query-log false; puis queries est toujours vide.
queries QueryEntry[] Le plus récent d'abord.
total integer Entrées correspondant aux filtres avant limit a été appliqué.
limit integer La taille de page appliquée (1-1000).

CreateLinkRequest

ChampTypeDescription
name string Affiché au propriétaire sur la page d'approbation et sur sa page Embedded.
hostname string
appVersion string

CreateLinkResponse

ChampTypeDescription
linkId string
code string Montrez cela au propriétaire afin qu'il puisse vérifier que cela correspond.
secret string À conserver côté serveur ; c'est lui qui collecte la clé.
linkUrl string Ouvrez cela pour que le propriétaire puisse approuver.
expiresAt string (date-time)
pollIntervalSeconds integer

LinkTokenRequest

ChampTypeDescription
linkId * string
secret * string

LinkPending

ChampTypeDescription
status pending
expiresAt string (date-time)

LinkApproved

ChampTypeDescription
status approved
licenseKey string Renvoyé exactement une fois. Passez-le à PUT /manage/license.
keyId string
licenseId string
plan string Identifiant du plan, ou custom.
planName string
accountEmail string

* obligatoire