Esportare un database con sqldump

Traduzione automatica provvisoria, non revisionata. In caso di dubbio, consultare la versione inglese, che fa fede.

kent sqldump esporta un database in uno script .sql che lo ricrea quando viene rieseguito. Con --schema-only esporta la sola struttura, che è il modo in cui vengono prodotti i file di schema pubblicati su Lo schema in SQL.

È di sola lettura. kent sqldump apre il database nella modalità di sola lettura di SQLite e non vi scrive nulla.

Sintassi

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

Argomenti

Scrivere su un file, o sullo standard output

Con --out, lo script viene scritto in quel file. Senza, lo script va sullo standard output così da poter essere convogliato altrove:

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

Poiché lo standard output trasporta lo script stesso, ogni messaggio che kent sqldump stampa va sullo standard error, errori e avvisi allo stesso modo. Nulla di ciò che Kent stampa viene mai intercalato nell'esportazione.

Cosa contiene lo script

Nell'ordine: un'intestazione di commento, PRAGMA foreign_keys=OFF e il PRAGMA user_version che ripristina il marcatore di schema, una transazione, ogni CREATE TABLE, ogni riga come INSERT, poi indici, viste e trigger, poi 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;

I dati delle tabelle vengono prima dei trigger, deliberatamente. Un trigger che modifica un'altra tabella all'inserimento di una riga scatterebbe altrimenti una seconda volta durante il ripristino, lasciando il database ripristinato sottilmente diverso dall'originale.

PRAGMA user_version viene riportato perché Cordelia rifiuta di aprire un database la cui versione di schema non riconosce. Senza di esso, un export ripristinato dichiarerebbe la versione 0 e Cordelia non lo aprirebbe.

Perché l'intestazione registra la versione di Cordelia

È Cordelia a definire lo schema di un database Cordelia; Kent si limita a trascriverlo. Una build successiva di Kent produce lo stesso schema dallo stesso database, quindi la versione di Kent non identifica da dove venga lo schema: quella di Cordelia sì. Per un file di schema conservato come artefatto di riferimento, è quella la riga che conta.

Due esportazioni dello stesso database coincidono

A parte il timestamp nell'intestazione, due esportazioni dello stesso database sono identiche byte per byte. Le tabelle vengono emesse in ordine di nome e le righe in ordine di inserimento, così un'esportazione può essere confrontata con un'altra: che è poi il punto, se state scrivendo uno script per convertire un vecchio schema in uno nuovo.

--schema-only

Emette ogni istruzione CREATE e il PRAGMA user_version, senza alcun INSERT. Per un database appena creato è la differenza fra 54 KiB e 2,3 MiB, dato che circa il 98 % delle righe di un database nuovo sono dati di lookup precaricati:

$ 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

Lo script si riesegue comunque: produce semplicemente un database vuoto con lo stesso schema. È questa la forma da usare per un artefatto di riferimento per versione, dove diff schema_01.sql schema_02.sql è pensato per leggersi come una dichiarazione di ciò che è cambiato fra due versioni dello schema.

Un database vecchio viene esportato, non rifiutato

A differenza di ogni altro comando di Kent, sqldump non rifiuta un database la cui versione di schema differisce da quella attesa da questa build. Lo esporta comunque, con una nota sullo standard error. Rifiutarlo vanificherebbe lo scopo: esportare un database vecchio è esattamente ciò che si fa prima di migrarlo.

$ 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

Si confronti con kent info, che rifiuta lo stesso file.

L'esportazione non sovrascrive nulla

Che --in e --out indichino lo stesso file viene rifiutato prima che venga letto alcunché, anziché troncare il database che avevate chiesto di esportare.

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

Un percorso passato a --in che non esiste viene segnalato come mancante e non viene creato: la chiamata di apertura di SQLite crea da sé il file che le viene passato, quindi un percorso digitato male lascerebbe altrimenti in giro un database vuoto.

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

Schemi che non si possono esportare

Un database Cordelia non ne usa nessuno. kent sqldump li rifiuta anziché produrre uno script che ripristinerebbe in modo scorretto: un'esportazione sbagliata è peggiore di una rifiutata.

Due dei tre esistono solo perché si stanno scrivendo righe, quindi --schema-only li rimuove: senza INSERT che possa fallire e senza righe da ordinare, nessuno dei due problemi si pone. Il rifiuto delle tabelle virtuali riguarda lo schema in sé, quindi vale in entrambe le modalità.

Ripristinare un'esportazione

Lo script si riesegue con qualunque strumento SQLite, non solo con 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

Ripristinate in un file vuoto, non in un database che kent createdb ha già creato. Un'esportazione porta con sé ogni CREATE TABLE, quindi rieseguirla su un database Cordelia esistente fallisce subito con table AadAccelFeatures already exists. L'esportazione è autosufficiente: è lo schema e i dati.

Un'esportazione è l'input di una migrazione, non una migrazione in sé. Convertire un vecchio schema in uno nuovo significa modificare lo script fra il dump e il ripristino: è a questo che serve la pipe qui sopra. Uno script di conversione non deve eliminare le tabelle di riferimento precaricate (FileTypeLookup, FieldTypeLookup, better_labels_definitions, better_labels_lookup, circa 19.700 righe). Nulla le rigenera durante un ripristino, perché nulla crea lo schema se non lo script stesso; eliminarne le righe produce un database con le tabelle di lookup vuote.

Si veda anche Messaggi di errore e codici di uscita e Lo schema in SQL.

Vedi anche

• Codici di uscita
• Il dizionario dei dati
• Analizzare un database con info
• Creare un database con createdb
• Messaggi di errore e codici di uscita