veilletech.fr
19 sept. Feed du jour
#07 DUCKDB Article

DuckDB-Wasm garde enfin sa base dans le navigateur

Une base dans le navigateur, oui. Une base que le navigateur peut effacer, aussi.

DuckDB-Wasm peut ouvrir une base persistante dans l'Origin Private File System du navigateur : un vrai fichier .duckdb, avec journal d'écriture et checkpoints, qui survit aux rechargements. L'équipe DuckDB en détaille l'usage, un piège de version sur npm, et les règles de durabilité propres à un onglet qu'on ferme sans prévenir.

3 min de lectureintermédiairevidéo 1:23
Partager
Sommaire5 sections
  1. Ce qui se passe
  2. Comment s'y prendre
  3. Le piège de version
  4. La durabilité, version onglet
  5. À retenir

Ce qui se passe

Depuis son lancement en 2021, DuckDB-Wasm travaillait en mémoire : fermer l'onglet effaçait tout. Garder des données supposait de sérialiser les tables en Parquet, de ranger les octets dans IndexedDB et de tout réenregistrer au chargement suivant, à la main.

L'équipe DuckDB documente désormais la persistance par l'Origin Private File System (OPFS), un système de fichiers privé à chaque origine, disponible dans les navigateurs depuis mars 2023, avec lecture et écriture à accès aléatoire. Testé avec les versions 1.32.0 et 1.33.1-dev64.0.

Comment s'y prendre

L'installation est celle de toute application DuckDB-Wasm ; seul l'appel open change :

JavaScript
await db.open({
  path: 'opfs://analytics.duckdb',
  accessMode: duckdb.DuckDBAccessMode.READ_WRITE,
  opfs: { fileHandling: 'auto' },
});

On obtient un fichier .duckdb ordinaire, avec son .wal : il survit aux rechargements et aux redémarrages, et s'ouvre tel quel avec la ligne de commande ou le client Python une fois extrait.

L'option fileHandling: 'auto' permet d'utiliser des chemins opfs:// dans le SQL : DuckDB repère les littéraux entre apostrophes, enregistre les fichiers avant la requête et crée les dossiers manquants. Sans elle, chaque fichier s'enregistre avec db.registerOPFSFileName() et se libère avec db.dropFile() — plus verbeux, mais plus rapide pour beaucoup de petites requêtes. Exemple de cache d'agrégat :

SQL
COPY (
  SELECT o_orderpriority AS priority,
         date_trunc('month', o_orderdate) AS month,
         sum(o_totalprice) AS total
  FROM orders
  GROUP BY ALL
) TO 'opfs://cache/monthly_totals.parquet';

Un CREATE TABLE IF NOT EXISTS … AS SELECT * FROM 'https://…parquet' ne télécharge le fichier distant qu'au premier chargement ; les suivants lisent OPFS.

Le piège de version

Au moment de l'article, la version que npm sert en latest, 1.33.1-dev57.0, crée les fichiers dans OPFS mais n'y écrit jamais : elle normalise le chemin en opfs:/ avec une seule barre, qui ne correspond plus au fichier ouvert. Il faut fixer @duckdb/duckdb-wasm@1.32.0 ou prendre @next (1.33.1-dev64.0 et après).

La durabilité, version onglet

DuckDB écrit d'abord dans le journal, puis reporte dans le fichier principal au checkpoint : automatiquement au-delà de 16 Mo de journal, à la fermeture propre, ou sur CHECKPOINT. Or un onglet se ferme rarement proprement. D'où deux règles :

Plus bas encore, OPFS n'est pas une garantie : le navigateur peut l'évincer quand le disque manque ou quand le site n'a pas été visité depuis longtemps, et l'utilisateur peut le vider.

Source : Persistent Databases in the Browser with DuckDB-Wasm and OPFS, Carlo Piovesan et Geertjan Wielenga, blog DuckDB, 18 septembre 2026.