Passer en production

TLS, les proxies inverses, le domaine licencié, les gestionnaires de services, les sauvegardes, la Content-Security-Policy et les en-têtes d'isolation, et une checklist de production pour SQLly Embedded.

Sur localhost, les valeurs par défaut fonctionnent telles quelles. En production, placez le pont derrière TLS, liez votre licence à votre domaine, gardez l’API de gestion privée et faites tourner le tout en tant que services. Cette page rassemble les réglages, les configurations et la checklist pour y parvenir.

Disposition recommandée

  • Un hôte ou un réseau privé pour votre application et le pont. L'API de gestion (127.0.0.1:8445) ne doit être accessible que par votre application.
  • Un proxy inverse (nginx, Caddy, IIS, un équilibrage de charge cloud) termine le TLS et transfère les mises à niveau WebSocket sur un chemin tel que /sqlly/proxy vers le --bind écouteur du pont.
  • Le même proxy sert votre application, y compris la page SQLly et web/ le bundle, de sorte que tout est servi en même origine sous votre domaine sous licence.
  • Le pont a besoin de du HTTPS sortant vers sqlly.app (licences connectées uniquement) et un accès réseau à vos bases de données. Les navigateurs n'accèdent jamais à vos bases de données ni au moteur.

Proxy inverse

nginx
location /sqlly/proxy {
    proxy_pass http://127.0.0.1:8444/proxy;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header Origin $http_origin;      # the bridge checks it against your licensed domain
    proxy_read_timeout 1h;                     # long-running queries and idle editors
    proxy_send_timeout 1h;
}
caddy
portal.example.com {
    handle /sqlly/proxy {
        rewrite * /proxy
        reverse_proxy 127.0.0.1:8444
    }
    reverse_proxy 127.0.0.1:3000   # your app
}

Puis démarrez le pont avec --public-url wss://portal.example.com/sqlly/proxy pour que chaque jeton de lancement indique à SQLly où se connecter. Pour passer outre le proxy, donnez au pont --tls-cert et --tls-key et il sert wss:// lui-même.

Exécutez-le en tant que service

systemd : /etc/systemd/system/sqlly-embedded.service
[Unit]
Description=SQLly Embedded bridge
After=network-online.target
Wants=network-online.target

[Service]
User=sqlly
EnvironmentFile=/etc/sqlly-embedded.env
ExecStart=/opt/sqlly-embedded/bin/sqlly-bridge embedded
Restart=on-failure
RestartSec=10
# systemd's default SIGTERM is a clean shutdown: the bridge releases its
# instance slot on sqlly.app at once.
TimeoutStopSec=30

[Install]
WantedBy=multi-user.target
/etc/sqlly-embedded.env (chmod 600)
SQLLY_EMBEDDED_LICENSE_KEY=sqe_…
SQLLY_EMBEDDED_MANAGE_TOKEN=…
SQLLY_EMBEDDED_DOMAIN=portal.example.com
SQLLY_EMBEDDED_PUBLIC_URL=wss://portal.example.com/sqlly/proxy
SQLLY_EMBEDDED_BIND=127.0.0.1:8444
SQLLY_EMBEDDED_MANAGE_BIND=127.0.0.1:8445
SQLLY_EMBEDDED_STATE_DIR=/var/lib/sqlly-embedded
SQLLY_EMBEDDED_ALLOW_LOCALHOST_ORIGINS=false

Sur macOS, utilisez un plist de launchd avec le même environnement. Sur Windows, exécutez sqlly-bridge.exe embedded sous un wrapper de service ou le Planificateur de tâches. Dans les conteneurs, montez le répertoire d'état en tant que volume. Le pont se termine avec un message clair si sa licence ne peut pas être vérifiée au démarrage, donc une politique de redémarrage continue de réessayer jusqu'à ce que sqlly.app soit accessible.

Arrêtez-le avec un signal d'arrêt normal. Le pont se ferme proprement sur SIGTERM (ce que systemd, launchd et docker stop envoient), SIGINT (Ctrl-C), SIGHUP (la fermeture de la fenêtre du terminal, une session ssh qui se déconnecte), ou la fermeture de la fenêtre de la console sur Windows : il ferme les sessions et libère immédiatement son emplacement d'instance sur sqlly.app, en réessayant pendant quelques secondes si sqlly.app ne répond pas. Un arrêt forcé (SIGKILL, un crash, une coupure de courant) laisse l'emplacement occupé jusqu'à ce qu'il devienne obsolète 40 minutes plus tard, et un pont de remplacement n'est pas admis avant cela. Les ponts d'avant ce changement ne libéraient l'emplacement que sur SIGINT ; si vous en exécutez un, ajoutez KillSignal=SIGINT à l'unité ou utilisez STOPSIGNAL SIGINT dans Docker.

Chaque paramètre du pont

Chaque option possède une variable d'environnement, donc une unité de service ou .env fichier peut contenir toute la configuration.

OptionEnvironnementPar défautSens
--license-keySQLLY_EMBEDDED_LICENSE_KEYaucunClé de licence connectée depuis votre page Embedded.
--license-fileSQLLY_EMBEDDED_LICENSE_FILEaucunFichier de licence hors ligne. Ne contacte jamais sqlly.app. Fournissez au plus l'un des deux : clé ou fichier ; sans aucun des deux, une clé liée est utilisée, sinon le pont démarre sans licence.
--domainSQLLY_EMBEDDED_DOMAINaucunLie une licence non liée lors du premier enregistrement ; refuse de démarrer si la licence est liée ailleurs.
--bindSQLLY_EMBEDDED_BIND0.0.0.0:8444Écouteur WebSocket pour navigateur (chemin /proxy). Utilisez le loopback derrière un reverse proxy.
--public-urlSQLLY_EMBEDDED_PUBLIC_URLws://localhost:<port>/proxyL'URL utilisée par les navigateurs, renvoyée avec chaque jeton de lancement.
--manage-bindSQLLY_EMBEDDED_MANAGE_BIND127.0.0.1:8445Point d'écoute de l'API de gestion. Gardez-le privé : il contient des identifiants.
--manage-tokenSQLLY_EMBEDDED_MANAGE_TOKENrequisJeton Bearer pour l'API de gestion, au moins 16 caractères.
--tls-cert, --tls-keySQLLY_EMBEDDED_TLS_CERT, SQLLY_EMBEDDED_TLS_KEYaucunServir wss:// directement. Fournissez les deux ou aucun des deux.
--state-dirSQLLY_EMBEDDED_STATE_DIR./sqlly-embedded-stateProfils, autorisation en cache, clé liée, fichiers d'identifiants par session. Créés avec des permissions limitées au propriétaire.
--engine-binarySQLLY_CLI_BINà côté du pont, puis PATHLe sqlly-cli le pont fonctionne par session.
--max-sessionsSQLLY_EMBEDDED_MAX_SESSIONS64Plafond strict de moteurs simultanés sur cet hôte.
--allow-localhost-originsSQLLY_EMBEDDED_ALLOW_LOCALHOST_ORIGINStrueAccepter les origines localhost en plus du domaine sous licence. Définir false en production.
--token-ttl-secondsSQLLY_EMBEDDED_TOKEN_TTL_SECONDS600Durée de vie par défaut du jeton de lancement.
--store-urlSQLLY_STORE_URLhttps://sqlly.appOù vont les check-ins. Ne pas y toucher en dehors du développement.
--allow-file-enginesSQLLY_EMBEDDED_ALLOW_FILE_ENGINESfalseAccepter les profils avec moteurs basés sur fichiers (SQLite, DuckDB). Désactivé, ils sont refusés avec 400 invalid_profile. Voir Moteurs basés sur les fichiers.
--query-logSQLLY_EMBEDDED_QUERY_LOGtrueConserver la piste d'audit des requêtes (GET /manage/queries, <state-dir>/queries.jsonl). false ne consigne rien. Voir Piste d'audit des requêtes.
--query-log-max-entriesSQLLY_EMBEDDED_QUERY_LOG_MAX_ENTRIES20000Les requêtes terminées les plus récentes sont conservées, en mémoire et sur disque (minimum 100).

Le répertoire d'état et l'hôte

Le répertoire d'état contient chaque profil avec ses mots de passe, la licence accordée en cache, la clé d'une installation liée, les fichiers d'identification par session remis aux moteurs et la piste d'audit des requêtes. Sur Linux et macOS, le pont le crée pour le propriétaire seulement (0700, fichiers 0600).

Sous Windows, le pont ne peut pas renforcer les permissions. Le répertoire d'état hérite de l'ACL de son dossier parent, et le pont enregistre un avertissement au démarrage pour le signaler. Placez-le sous un dossier que seul le compte de service peut lire, par exemple un répertoire dédié sous %ProgramData% avec l'héritage supprimé et une ACL accordant uniquement au compte de service, et jamais sous un chemin partagé, synchronisé ou accessible aux utilisateurs.

Moteurs basés sur les fichiers

Les moteurs basés sur des fichiers sont désactivés par défaut. Une connexion SQLite ou DuckDB dans un profil désigne un fichier sur l'hôte du pont. Ses utilisateurs peuvent alors lire ce fichier, en créer de nouveaux et, via les fonctions de fichiers du moteur, atteindre d'autres fichiers que le compte de service peut lire. Le pont refuse donc les profils, les tests de connexion et les jetons de lancement qui impliquent un moteur basé sur des fichiers avec 400 invalid_profile et un problems[] entrée expliquant pourquoi, à moins qu'il ne s'exécute avec --allow-file-engines true. Activez-le uniquement pour un compte de service dédié et verrouillé, et pour un répertoire que les utilisateurs doivent pouvoir atteindre. En mode proxy, le moteur interdit en outre le téléchargement d'extensions DuckDB et l'accès externe (lecture de fichiers, COPY, ATTACH) pour chaque instance DuckDB qu'il ouvre.

Piste d'audit des requêtes

Le pont enregistre chaque requête et modification de ligne exécutée par ses sessions : l'utilisateur et le profil du jeton de lancement, la connexion (nom, serveur, moteur, base de données), le texte SQL, le moment où elle a commencé, comment elle s'est terminée et combien de temps cela a pris. Les requêtes refusées en raison d'un problème de licence sont enregistrées comme échouées avec le message de licence ; tout ce qui était en cours d'exécution lorsque la session s'est fermée est enregistré comme annulé. Votre application le lit avec GET /manage/queries, les plus récents en premier, filtrés par utilisateur, profil, statut ou date.

Les plus récentes des --query-log-max-entries entrées vivent en mémoire et dans <state-dir>/queries.jsonl (un objet JSON par ligne, écrit uniquement pour le propriétaire, compacté automatiquement), donc la trace survit aux redémarrages. Le texte SQL est stocké sur l'hôte pont en clair. Gardez le répertoire d'état aussi privé que les profils qu'il contient déjà, et définissez --query-log false si votre politique interdit tout simplement de conserver le texte des requêtes.

Le journal du moteur lui-même

Chaque sqlly-cli le moteur écrit un journal de corrélation requête/réponse, incluant le texte SQL complet de chaque requête, dans son répertoire de données : ~/.local/share/sqlly/sqlly-engine.log (ou $XDG_DATA_HOME/sqlly/sqlly-engine.log) sur Linux, ~/Library/Application Support/SQLLY/sqlly-engine.log sur macOS, %APPDATA%\SQLLY\sqlly-engine.log sur Windows, créé uniquement pour le propriétaire. Les mots de passe, tokens et références secrètes sont effacés avant qu'une ligne soit écrite ; les identifiants, serveurs, noms d'utilisateur et SQL sont conservés. Définissez SQLLY_ENGINE_LOG=<path> dans l'environnement du pont (ses moteurs en héritent) pour déplacer le journal quelque part que vous contrôlez, ou SQLLY_ENGINE_LOG=/dev/null (NUL sur Windows) pour ne rien conserver. Le journal est réduit à ses dernières lignes seulement lorsqu'un moteur se ferme correctement.

Paramètres du fournisseur IA

Le moteur récupère la configuration du fournisseur IA depuis son environnement (SQLLY_LLM_PROVIDER, SQLLY_EMBEDDING_PROVIDER et les variables de modèle et de clé associées). Ne les définissez pas sur l'hôte du pont, sauf si vous voulez que l'IntelliSense et les fonctions d'IA de vos utilisateurs finaux consomment le quota de ce compte.

Flags de sécurité

Le only_allow_select (sur un client, un projet ou une étiquette d'environnement) et le safety.block_all_but_select sont appliqués par le moteur sur l'hôte du pont : une instruction qui n'est pas uniquement SELECT pour le moteur de la connexion, et chaque modification de ligne, sont refusées avec « cette connexion est en lecture seule par politique » avant d'atteindre la base de données, quoi qu'en prétende le navigateur. Les autres options de sécurité (boîtes de dialogue de confirmation, encapsulation de rollback, protection contre les UPDATE/DELETE illimités) sont un comportement du client SQLly dans le navigateur de l'utilisateur, pas un contrôle côté serveur. Les permissions de la base de données restent le véritable contrôle : n'accordez aux connexions relayées que ce que leurs utilisateurs doivent pouvoir faire.

Dimensionnement

Chaque onglet SQLly ouvert exécute un seul sqlly-cli processus du moteur avec ses propres connexions à la base de données. La mémoire suit ce que font les gens : les jeux de résultats sont transmis en continu puis déversés sur le disque au lieu d'être gardés en entier, mais les exports volumineux et les nombreux onglets simultanés s'additionnent. Dimensionnez l'hôte pour votre pic d'onglets simultanés (sièges × onglets par siège au maximum), et utilisez --max-sessions comme filet de sécurité. Les moteurs sont démarrés à la demande et se ferment lorsque leur onglet se ferme.

Opérations

  • Sauvegardez le répertoire d'état. Il contient chaque profil avec ses identifiants et la clé d'une installation liée. Traitez les sauvegardes comme des secrets.
  • Surveillez le journal pour embedded license state: chaque transition de licence est enregistrée avec le nom de son état. Interrogez GET /manage/status depuis votre surveillance, et utilisez GET /healthz (pas de jeton) pour vérifier la disponibilité.
  • Gardez l'horloge à l'heure. Les autorisations doivent être émises à moins de 5 minutes d'écart avec l'horloge du pont, d'où l'importance d'exécuter NTP.
  • Mettez à jour les deux ensemble. Remplacer bin/ et web/ à partir de la même version du package. Redémarrer le pont ferme les onglets ouverts, et les utilisateurs se reconnectent en rechargeant.
  • Renouvelez le jeton de gestion en redémarrant le pont et votre application avec la nouvelle valeur. Les jetons de lancement déjà émis continuent de fonctionner jusqu'à leur expiration.
  • Vous déplacez des domaines ? Changez-le sur votre page Embedded et redémarrez le pont avec le nouveau --domain. Les licences hors ligne nécessitent un nouveau fichier, car le domaine y est inclus.

Liste de contrôle pour la production

  • TLS devant l'écouteur de navigateur, et --public-url réglé sur le wss:// adresse.
  • SQLLY_EMBEDDED_DOMAIN l'ensemble et de la licence qui y est liée ; --allow-localhost-origins=false.
  • API de gestion sur loopback ou réseau privé ; jeton de gestion uniquement dans les secrets côté serveur.
  • Jetons de lancement transmis à la page par le SQLLY_PROXY_URL / SQLLY_PROXY_TOKEN globals, jamais dans une URL de page (?token= se retrouve dans l'historique, les référents et les journaux du serveur web).
  • --allow-file-engines laissé de côté, sauf si un compte de service verrouillé et un annuaire avaient été configurés pour lui.
  • Répertoire d'état lisible uniquement par le compte de service (propriétaire seul sur Linux/macOS ; une ACL explicite sur Windows) ; --query-log et SQLLY_ENGINE_LOG défini selon votre politique de conservation du texte des requêtes.
  • Non SQLLY_LLM_PROVIDER / SQLLY_EMBEDDING_PROVIDER dans l'environnement du pont sauf si les utilisateurs finaux doivent piloter cette dépense.
  • Pont et application exécutés comme services sous un utilisateur non privilégié, redémarrage en cas d'échec, arrêt en douceur.
  • Répertoire d'état sur stockage persistant, réservé au propriétaire, sauvegardé.
  • La page SQLly et web/ servie avec COOP/COEP, application/wasm, et un CSP qui autorise l'origine du pont.
  • HTTPS sortant vers sqlly.app autorisé (licences connectées), NTP activé.
  • Surveillance activée /manage/status: alerte lorsque license.state n'est pas ok.
  • Le mot de passe administrateur par défaut de l'application exemple a changé, si vous déployez l'application exemple. Elle refuse de se lier au-delà de la boucle locale tant que vous ne le faites pas.