Skip to main content
View as Markdown

Infrastructure de base de données

Sovrium fonctionne sur une base de données SQLite embarquée avec zéro configuration et passe à PostgreSQL en définissant une seule variable d'environnement. L'intégralité du runtime — migrations, bundles client, le moteur CSS, les configurations d'exemple — est regroupée dans un seul binaire autonome, et un cache de rendu de page statique maintient le CPU du serveur frugal. Cette page documente la couche de persistance et de distribution qui rend possible « lancer le binaire, ouvrir l'URL ».

Valeur par défaut SQLite sans configuration

Lorsqu'aucune DATABASE_URL n'est définie, Sovrium résout le dialecte sqlite, crée ./.sovrium/database.db, applique automatiquement l'ensemble de migrations SQLite au premier démarrage et sert toute la surface de base — schéma, authentification, CRUD d'enregistrements, migrations et formulaires. La bannière de démarrage affiche Database: SQLite (<absolute path>).

Cela reflète la philosophie frugale-par-défaut de la plateforme (jumeau de STORAGE_PROVIDER et de la famille ECO_*) : l'opérateur opte pour PostgreSQL en définissant DATABASE_URL, jamais l'inverse.

PostgreSQL lorsqu'il est configuré

Définissez DATABASE_URL sur une URL postgresql:// et Sovrium résout le dialecte postgres, se connecte, applique l'ensemble de migrations PostgreSQL et affiche Database: PostgreSQL. Aucun fichier SQLite n'est créé. Ce chemin est identique octet pour octet aux déploiements PostgreSQL préexistants.

Une source unique de vérité — parseDatabaseDialectConfig() — discrimine par schéma l'unique variable DATABASE_URL :

Valeur de DATABASE_URL Se résout en
postgres://… / postgresql://… PostgreSQL à cette URL.
non définie / vide SQLite à ./.sovrium/database.db (la valeur par défaut sans configuration).
file:./x.db / file:/abs.db SQLite au chemin résolu.
sqlite:./x.db / sqlite:///abs.db Alias SQLite pour le même fichier sur disque.
:memory: SQLite éphémère (niveau dialecte uniquement — pas une cible de déploiement complète).
tout le reste (chemin nu, mysql://, …) Lève Unsupported DATABASE_URL scheme: … au démarrage (échec bruyant).

Le dialecte sélectionné pilote le client Drizzle (bun:sqlite ou bun:sql), l'ensemble de migrations, le fournisseur d'adaptateur Better Auth et l'étiquette runtime destinée à l'opérateur de GET /api/admin/config/version (sqlite-aio sur SQLite, postgres sur PostgreSQL).

Dégradation gracieuse

Le mode SQLite prend en charge le sous-ensemble de base. Les fonctionnalités avancées réservées à PostgreSQL — notamment la recherche sémantique RAG pgvector — renvoient un 501 { error: 'requires-postgres' } typé plutôt que de planter. Passez à PostgreSQL pour les débloquer ; aucune modification de code requise.

Répertoire de données embarqué

Tout l'état local vit sous un seul répertoire de données relocalisable.

Variable env Par défaut Description
DATABASE_URL non définie → SQLite Sélecteur de moteur + emplacement de base de données.
SOVRIUM_DATA_DIR ./.sovrium Racine du fichier de base de données SQLite, des fichiers de verrou et du stockage local. Relocalisez tout le répertoire de données avec une seule variable.

Le ./.sovrium/database.db par défaut se trouve sous ce répertoire de données ; le répertoire parent est créé automatiquement au premier démarrage.

Cache de rendu de page statique

Sovrium rend les pages côté serveur à chaque requête. Pour une page dont le HTML ne dépend pas de l'état par requête (une page marketing, à propos ou tarification), c'est du CPU gaspillé. Le cache de rendu en mémoire rend une telle page une fois et la sert depuis la mémoire lors des requêtes anonymes suivantes, en sautant entièrement renderToString — un gain d'écoconception et de latence.

Variable env Par défaut Options Description
ECO_PAGE_CACHE on on | off Cache en mémoire du HTML de page invariant par requête. Les opérateurs opèrent un opt-out ; ils n'opèrent jamais d'opt-in.

Comment cela fonctionne :

  • La mise en cache est dérivée, jamais déclarée. Une page n'est cachable que lorsque son HTML rendu ne peut pas varier selon la requête — elle est exclue si elle a un access non public, une collection, un dataSource de page/composant, un contentDir, une source de fichier, un corps markdown, une presence, une barre latérale liée aux données ou un segment de route dynamique :param.
  • Modèle de sécurité. Le cache n'est consulté que pour les requêtes anonymes, hors aperçu ; le filtrage dépendant de la session est déterministe lorsqu'aucune session n'existe, de sorte que la vue d'un utilisateur ne peut jamais fuiter vers un autre.
  • Invalidation par somme de contrôle. Chaque entrée est indexée par ${appRenderChecksum}:${path}:${language}. La somme de contrôle est un SHA-256 de la tranche de schéma affectant le rendu (pages, components, theme, languages, analytics) ; toute édition de schéma change chaque clé, de sorte que les entrées périmées deviennent inaccessibles. Aucune durée de vie, aucune logique de purge.
  • Observabilité. Chaque réponse de page porte X-Render-Cache: hit | miss | bypass et un en-tête Cache-Control (public, max-age=300 pour cachable, private, no-cache pour contourné). Les variantes de langue (/ vs /fr/) sont isolées par clé.

Voir Écoconception pour le contrat complet des variables env ECO_*.

Distribution en binaire autonome

Le canal de distribution principal de Sovrium est un binaire autonome (bun build --compile) qui s'exécute sans Bun ni Node.js sur l'hôte cible. Le binaire embarque l'intégralité du runtime dans un seul exécutable :

  • Surface de commandes CLI (--version, validate, build, schema, init, agents list)
  • Ensembles de migrations (les deux dialectes)
  • Bundles client et chunks d'îlots
  • Modèles d'agents et configurations d'exemple
  • Le moteur CSS thématisé sans dépendance native

En mode compilé, le binaire lit ses assets embarqués, jamais les arborescences dist//src//specs/ du dépôt sur disque — de sorte qu'il se comporte de façon identique lorsqu'il est lancé depuis n'importe quel répertoire de travail sur une machine cliente. Les bundles client embarqués, les chunks d'îlots et le script de changement de langue sont servis via HTTP depuis un serveur lancé par le binaire (GET /assets/output.css, GET /assets/client.js, GET /assets/islands/*).

Pages connexes