Exportar una base de datos con sqldump

Traducción automática provisional, sin revisar. En caso de duda, consulte la versión en inglés, que es la versión de referencia.

kent sqldump exporta una base de datos a un script .sql que la recrea al reproducirlo. Con --schema-only exporta solo la estructura, que es como se producen los archivos de esquema publicados en El esquema en SQL.

Es de solo lectura. kent sqldump abre la base de datos en el modo de solo lectura de SQLite y no escribe nada en ella.

Sinopsis

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

Argumentos

Opción	Obligatoria	Descripción
`--in <dbfilename>`	Sí	Ruta de una base de datos `.sqlite` existente que exportar.
`--out <outfile>`	No	Dónde escribir el script. Omítala para escribir en la salida estándar.
`--schema-only`	No	Emite el esquema y ningún dato de filas. No toma valor.

Escribir en un archivo o en la salida estándar

Con --out, el script se escribe en ese archivo. Sin ella, el script va a la salida estándar para poder canalizarlo hacia otra cosa:

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

Como la salida estándar lleva el propio script, todos los mensajes que imprime kent sqldump van a la salida de error, errores y avisos por igual. Nada de lo que imprime Kent se intercala nunca en la exportación.

Qué contiene el script

En orden: una cabecera de comentario, PRAGMA foreign_keys=OFF y el PRAGMA user_version que restaura la marca de esquema, una transacción, todos los CREATE TABLE, todas las filas como INSERT, luego los índices, vistas y disparadores, y después 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;

Los datos de las tablas van antes que los disparadores de forma deliberada. Un disparador que modifica otra tabla al insertar una fila se dispararía de otro modo una segunda vez durante la restauración, dejando la base restaurada sutilmente distinta de la original.

PRAGMA user_version se arrastra porque Cordelia se niega a abrir una base de datos cuya versión de esquema no reconozca. Sin él, una exportación restaurada informaría de la versión 0 y Cordelia no la abriría.

Por qué la cabecera registra la versión de Cordelia

Cordelia es quien define el esquema de una base de datos Cordelia; Kent solo lo transcribe. Una compilación posterior de Kent produce el mismo esquema a partir de la misma base de datos, así que la versión del propio Kent no identifica de dónde salió el esquema: la de Cordelia sí. Para un archivo de esquema conservado como artefacto de referencia, esa es la línea que importa.

Dos exportaciones de la misma base de datos coinciden

Salvo por la marca de tiempo de la cabecera, dos exportaciones de la misma base de datos son idénticas byte a byte. Las tablas se emiten por orden de nombre y las filas por orden de inserción, de modo que una exportación puede compararse con otra, que es de lo que se trata si está escribiendo un script para convertir un esquema antiguo en uno nuevo.

--schema-only

Emite todas las sentencias CREATE y el PRAGMA user_version, sin ningún INSERT. Para una base de datos recién creada eso es la diferencia entre 54 KiB y 2,3 MiB, ya que en torno al 98 % de las filas de una base nueva son datos de consulta precargados:

$ 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

El script se sigue reproduciendo: simplemente produce una base de datos vacía con el mismo esquema. Esta es la forma que hay que usar para un artefacto de referencia por versión, donde diff schema_01.sql schema_02.sql pretende leerse como una declaración de lo que cambió entre dos versiones de esquema.

Una base de datos antigua se exporta, no se rechaza

A diferencia de todos los demás comandos de Kent, sqldump no rechaza una base de datos cuya versión de esquema difiera de la que espera esta compilación. La exporta de todos modos, con una nota en la salida de error. Rechazarla frustraría el propósito: exportar una base de datos antigua es exactamente lo que se hace antes de migrarla.

$ 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

Compárese con kent info, que rechaza ese mismo archivo.

La exportación se escribe sobre nada

Que --in y --out nombren el mismo archivo se rechaza antes de leer nada, en lugar de truncar la base de datos que pidió exportar.

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

Una ruta dada a --in que no existe se informa como ausente y no se crea: la propia llamada de apertura de SQLite crea el archivo que se le indica, así que una ruta mal escrita dejaría si no una base de datos vacía perdida por ahí.

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

Esquemas que no se pueden exportar

Una base de datos Cordelia no usa ninguno de estos. kent sqldump los rechaza en lugar de producir un script que restauraría incorrectamente: una exportación errónea es peor que una rechazada.

Característica	Por qué	¿Rechazada con `--schema-only`?
Tablas virtuales	Crear una arrastra tablas sombra que aparecen como tablas ordinarias: una tabla FTS5 produce cinco. Reproducir el `CREATE VIRTUAL TABLE` las recrea, así que el `CREATE TABLE` de cada sombra falla luego por existir ya.	Sí
Tablas `WITHOUT ROWID`	Las filas no tienen rowid por el que ordenarlas, así que la exportación no podría hacerse determinista.	No
Columnas generadas	En una columna generada no se puede insertar, así que el `INSERT` reproducido fallaría.	No

Dos de los tres existen solo porque se están escribiendo filas, de modo que --schema-only los levanta: sin INSERT que falle y sin filas que ordenar, ninguno de los dos problemas se plantea. El rechazo de las tablas virtuales tiene que ver con el esquema en sí, así que se mantiene en ambos modos.

Restaurar una exportación

El script se reproduce con cualquier herramienta SQLite, no 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

Restaure en un archivo vacío, no en una base de datos que kent createdb ya haya creado. Una exportación lleva todos los CREATE TABLE, así que reproducirla sobre una base de datos Cordelia existente falla de inmediato con table AadAccelFeatures already exists. La exportación es autónoma: es el esquema y los datos.

Una exportación es la entrada de una migración, no una migración en sí. Convertir un esquema antiguo en uno nuevo significa editar el script entre el volcado y la restauración: para eso está la tubería de arriba. Un script de conversión no debe eliminar las tablas de referencia precargadas (FileTypeLookup, FieldTypeLookup, better_labels_definitions, better_labels_lookup, unas 19 700 filas). Nada las regenera durante una restauración, porque nada crea el esquema salvo el propio script; eliminar sus filas produce una base de datos con las tablas de consulta vacías.

Véase también Mensajes de error y códigos de salida y El esquema en SQL.