Exportar um banco de dados com sqldump

Tradução automática provisória, não revisada. Em caso de dúvida, consulte a versão em inglês, que é a versão de referência.

O kent sqldump exporta um banco de dados para um script .sql que o recria quando reproduzido. Com --schema-only, ele exporta apenas a estrutura, que é como são produzidos os arquivos de esquema publicados em O esquema em SQL.

Ele é somente leitura. O kent sqldump abre o banco de dados no modo somente leitura do SQLite e não grava nada nele.

Sinopse

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

Argumentos

Gravar em um arquivo, ou na saída padrão

Com --out, o script é gravado nesse arquivo. Sem ela, o script vai para a saída padrão, para poder ser encadeado em outra coisa:

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

Como a saída padrão carrega o próprio script, toda mensagem que o kent sqldump imprime vai para a saída de erro, erros e avisos igualmente. Nada do que o Kent imprime é jamais intercalado na exportação.

O que o script contém

Em ordem: um cabeçalho de comentário, PRAGMA foreign_keys=OFF e o PRAGMA user_version que restaura a marca de esquema, uma transação, todos os CREATE TABLE, todas as linhas como INSERT, depois os índices, visões e gatilhos, e então 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;

Os dados das tabelas vêm antes dos gatilhos, deliberadamente. Um gatilho que altera outra tabela quando uma linha é inserida dispararia, de outro modo, uma segunda vez durante a restauração, deixando o banco restaurado sutilmente diferente do original.

O PRAGMA user_version é levado adiante porque o Cordelia se recusa a abrir um banco de dados cuja versão de esquema ele não reconhece. Sem ele, uma exportação restaurada informaria a versão 0 e o Cordelia não a abriria.

Por que o cabeçalho registra a versão do Cordelia

É o Cordelia que define o esquema de um banco de dados Cordelia; o Kent apenas o transcreve. Uma compilação posterior do Kent produz o mesmo esquema a partir do mesmo banco, então a versão do próprio Kent não identifica de onde veio o esquema, a do Cordelia identifica. Para um arquivo de esquema guardado como artefato de referência, é essa a linha que importa.

Duas exportações do mesmo banco de dados coincidem

Fora o carimbo de data e hora no cabeçalho, duas exportações do mesmo banco de dados são idênticas byte a byte. As tabelas são emitidas em ordem de nome e as linhas em ordem de inserção, de modo que uma exportação pode ser comparada com outra, que é justamente o ponto, se você está escrevendo um script para converter um esquema antigo em um novo.

--schema-only

Emite todas as instruções CREATE e o PRAGMA user_version, sem nenhum INSERT. Para um banco de dados recém-criado, essa é a diferença entre 54 KiB e 2,3 MiB, já que cerca de 98 % das linhas de um banco novo são dados de consulta pré-carregados:

$ 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

O script continua a ser reproduzível, ele apenas produz um banco de dados vazio com o mesmo esquema. Esta é a forma a usar para um artefato de referência por versão, em que diff schema_01.sql schema_02.sql deve ser lido como uma declaração do que mudou entre duas versões de esquema.

Um banco de dados antigo é exportado, não recusado

Ao contrário de todos os outros comandos do Kent, o sqldump não recusa um banco de dados cuja versão de esquema difere da que esta compilação espera. Ele o exporta assim mesmo, com uma observação na saída de erro. Recusá-lo frustraria o propósito: exportar um banco antigo é exatamente o que se faz antes de migrá-lo.

$ 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

Compare com o kent info, que recusa o mesmo arquivo.

A exportação não é gravada por cima de nada

--in e --out nomeando o mesmo arquivo é recusado antes de qualquer leitura, em vez de truncar o banco de dados que você pediu para exportar.

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

Um caminho dado a --in que não existe é relatado como ausente e não é criado, a própria chamada de abertura do SQLite cria o arquivo que recebe, então um caminho digitado errado deixaria para trás um banco de dados vazio perdido.

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

Esquemas que não podem ser exportados

Um banco de dados Cordelia não usa nenhum destes. O kent sqldump os recusa em vez de produzir um script que restauraria incorretamente, uma exportação errada é pior do que uma recusada.

Dois dos três existem apenas porque linhas estão sendo gravadas, então o --schema-only os suspende: sem INSERT para falhar e sem linhas para ordenar, nenhum dos dois problemas surge. A recusa de tabelas virtuais é sobre o esquema em si, então vale nos dois modos.

Restaurar uma exportação

O script é reproduzível sob qualquer ferramenta SQLite, não apenas o 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 em um arquivo vazio, não em um banco de dados que o kent createdb já tenha criado. Uma exportação carrega todos os CREATE TABLE, então reproduzi-la em um banco de dados Cordelia existente falha de imediato com table AadAccelFeatures already exists. A exportação é autossuficiente: ela é o esquema e os dados.

Uma exportação é a entrada de uma migração, não uma migração em si. Converter um esquema antigo em um novo significa editar o script entre o dump e a restauração, é para isso que serve o encadeamento acima. Um script de conversão não deve remover as tabelas de referência pré-carregadas (FileTypeLookup, FieldTypeLookup, better_labels_definitions, better_labels_lookup, cerca de 19.700 linhas). Nada as regenera durante uma restauração, porque nada cria o esquema além do próprio script; descartar suas linhas produz um banco de dados cujas tabelas de consulta estão vazias.

Veja também Mensagens de erro e códigos de saída e O esquema em SQL.

Veja também

• Códigos de saída
• O Dicionário de Dados
• Relatar um banco de dados com info
• Criar um banco de dados com createdb
• Mensagens de erro e códigos de saída