Exporter une base de données avec sqldump

Traduction automatique provisoire, non révisée. En cas de doute, consultez la version anglaise, qui fait foi.

kent sqldump exporte une base de données vers un script .sql qui la recrée lorsqu'on le rejoue. Avec --schema-only, il exporte la structure seule, ce qui est la façon dont sont produits les fichiers de schéma publiés sur Le schéma en SQL.

Il est en lecture seule. kent sqldump ouvre la base de données dans le mode lecture seule de SQLite et n'y écrit rien.

Synopsis

kent sqldump --in <dbfilename> [--out <outfile>] [--schema-only]

Arguments

Écrire dans un fichier, ou sur la sortie standard

Avec --out, le script est écrit dans ce fichier. Sans elle, le script part sur la sortie standard pour pouvoir être redirigé vers autre chose :

$ kent sqldump --in old.sqlite | python3 migrate.py > new.sql

Parce que la sortie standard porte le script lui-même, tous les messages qu'affiche kent sqldump partent sur la sortie d'erreur, erreurs comme avis. Rien de ce qu'affiche Kent ne s'intercale jamais dans l'export.

Ce que contient le script

Dans l'ordre : un en-tête en commentaire, PRAGMA foreign_keys=OFF et le PRAGMA user_version qui restaure la marque de schéma, une transaction, chaque CREATE TABLE, chaque ligne sous forme d'INSERT, puis les index, vues et déclencheurs, puis COMMIT.

$ kent sqldump --in mydata.sqlite --out mydata.sql
$ head -10 mydata.sql
-- kent sqldump
-- source: mydata.sqlite
-- kent: 1.3.4
-- cordelia: 1.3.3
-- exported: 2026-09-16T22:55:58Z
-- user_version: 2

PRAGMA foreign_keys=OFF;
PRAGMA user_version = 2;
BEGIN TRANSACTION;

Les données des tables viennent avant les déclencheurs, délibérément. Un déclencheur qui modifie une autre table à l'insertion d'une ligne se déclencherait sinon une seconde fois pendant la restauration, laissant la base restaurée subtilement différente de l'originale.

PRAGMA user_version est repris parce que Cordelia refuse d'ouvrir une base dont elle ne reconnaît pas la version de schéma. Sans lui, un export restauré annoncerait la version 0 et Cordelia ne l'ouvrirait pas.

Pourquoi l'en-tête consigne la version de Cordelia

C'est Cordelia qui définit le schéma d'une base de données Cordelia ; Kent ne fait que le transcrire. Une compilation ultérieure de Kent produit le même schéma à partir de la même base, donc la version de Kent lui-même n'identifie pas d'où vient le schéma, celle de Cordelia si. Pour un fichier de schéma conservé comme artefact de référence, c'est la ligne qui compte.

Deux exports de la même base de données coïncident

À l'horodatage de l'en-tête près, deux exports de la même base sont identiques octet pour octet. Les tables sont émises par ordre de nom et les lignes par ordre d'insertion, si bien qu'un export peut être comparé à un autre, ce qui est tout l'intérêt si vous écrivez un script pour convertir un ancien schéma en un nouveau.

--schema-only

Émet chaque instruction CREATE et le PRAGMA user_version, sans aucun INSERT. Pour une base fraîchement créée, c'est la différence entre 54 KiB et 2,3 MiB, puisque environ 98 % des lignes d'une nouvelle base sont des données de référence pré-remplies :

$ kent sqldump --in mydata.sqlite --schema-only --out schema_01.sql
$ grep -c '^CREATE' schema_01.sql
129
$ grep -c '^INSERT' schema_01.sql
0

Le script se rejoue toujours, il produit simplement une base vide avec le même schéma. C'est la forme à utiliser pour un artefact de référence par version, où diff schema_01.sql schema_02.sql est censé se lire comme un énoncé de ce qui a changé entre deux versions de schéma.

Une ancienne base est exportée, pas refusée

Contrairement à toutes les autres commandes de Kent, sqldump ne refuse pas une base dont la version de schéma diffère de celle attendue par cette compilation. Il l'exporte quand même, avec une note sur la sortie d'erreur. La refuser irait à l'encontre du but : exporter une ancienne base est exactement ce qu'on fait avant de la migrer.

$ kent sqldump --in old.sqlite --out old.sql
kent sqldump: note: this database reports schema version 0, but this build of cordelia expects 2. Exporting it anyway.
$ echo $?
0

Comparez avec kent info, qui refuse le même fichier.

L'export ne recouvre rien

--in et --out désignant le même fichier est refusé avant toute lecture, plutôt que de tronquer la base de données que vous demandiez d'exporter.

$ kent sqldump --in mydata.sqlite --out mydata.sqlite
kent sqldump: refusing to write the export over its own source: mydata.sqlite

Un chemin donné à --in qui n'existe pas est signalé comme manquant et n'est pas créé, l'appel d'ouverture de SQLite crée lui-même le fichier qu'on lui donne, si bien qu'un chemin mal saisi laisserait sinon derrière lui une base vide égarée.

$ kent sqldump --in nope.sqlite
kent sqldump: nope.sqlite does not exist

Schémas qui ne peuvent pas être exportés

Une base de données Cordelia n'en utilise aucun. kent sqldump les refuse plutôt que de produire un script qui restaurerait incorrectement, un export erroné est pire qu'un export refusé.

Deux des trois n'existent que parce que des lignes sont écrites : --schema-only les lève donc, sans INSERT pour échouer et sans lignes à trier, aucun des deux problèmes ne se pose. Le refus des tables virtuelles porte sur le schéma lui-même, il tient donc dans les deux modes.

Restaurer un export

Le script se rejoue sous n'importe quel outil SQLite, pas seulement Kent :

$ kent sqldump --in mydata.sqlite --out mydata.sql
$ sqlite3 restored.sqlite < mydata.sql
$ sqlite3 restored.sqlite 'PRAGMA user_version'
2
$ sqlite3 restored.sqlite 'SELECT count(*) FROM better_labels_lookup'
16866

Restaurez dans un fichier vide, pas dans une base de données que kent createdb a déjà créée. Un export porte chaque CREATE TABLE, si bien que le rejouer dans une base Cordelia existante échoue immédiatement avec table AadAccelFeatures already exists. L'export est autonome : il est le schéma et les données.

Un export est l'entrée d'une migration, pas une migration en soi. Convertir un ancien schéma en un nouveau signifie éditer le script entre le dump et la restauration, c'est à cela que sert le tube ci-dessus. Un script de conversion ne doit pas supprimer les tables de référence pré-remplies (FileTypeLookup, FieldTypeLookup, better_labels_definitions, better_labels_lookup, environ 19 700 lignes). Rien ne les régénère pendant une restauration, puisque rien ne crée le schéma hormis le script lui-même ; en supprimer les lignes produit une base dont les tables de référence sont vides.

Voir aussi Messages d'erreur et codes de sortie et Le schéma en SQL.

Voir aussi

• Codes de sortie
• Le dictionnaire de données
• Établir un rapport sur une base de données avec info
• Créer une base de données avec createdb
• Messages d'erreur et codes de sortie