Rebuilding a Database with restore

kent restore rebuilds a database from a .kent archive. It is the inverse of archive, and together the two make a round trip: a database you archive today is a database you can have back.

Synopsis

kent restore --in <archive> --out <dbfilename>

Arguments

Flag	Required	Description
`--in <archive>`	Yes	The `.kent` archive to read.
`--out <dbfilename>`	Yes	The database to create. Refused if it already exists.

The same two flag names archive uses, with the file kinds swapped: --in is the archive here, --out the database.

$ kent restore --in mydata.kent --out restored.sqlite
Restored restored.sqlite from mydata.kent
Tables:  11
Rows:    63686
Schema version: 2

It will not overwrite a database

An existing --out is refused, never replaced, the same rule createdb follows. These are the only two Kent commands that write a database, and the destination is the one thing you cannot get back if it is wrong.

$ kent restore --in mydata.kent --out existing.sqlite
kent restore: existing.sqlite already exists

There is also no way to load an archive into a database that already holds data. That would be a merge, which is a separate command Kent does not have. See the Product Roadmap.

What comes back

Every value, and its SQLite storage class. A number stored as a decimal comes back a decimal rather than a whole number, an empty piece of binary data comes back as empty binary data rather than as nothing at all, and text keeps whatever it held: accented characters, symbols, even embedded line breaks.

That is a stronger promise than "the same values", and it is checked that way: the round-trip test compares the storage class of every column of every row, not just what the values print as.

The one thing that cannot come back

Not-a-number and infinity were written into the archive as 0.0, because JSON has no way to express them. A restore cannot tell those apart from a measured zero and does not pretend to.

An old archive restores to an old database

The archive records the schema version of the database it came from, and restore puts it back. So restoring an archive of a database made by an older Cordelia gives you a database that older Cordelia would recognise, and that the current Cordelia will refuse to open, exactly as it would have refused the original.

kent restore is not a migration tool, and neither is anything else in Kent. Moving an old database to a current schema means changing the data in between, which is what kent sqldump's pipe form is for.

Archives it refuses

Everything is checked before the database is created, so a bad archive costs you nothing.

Refusal	Why
Not an archive at all	It is not a zip, or it has no manifest and schema inside.
Carries no `mimetype`, or one naming another format	Same reason: the `mimetype` entry is what a `.kent` says it is. See Archive for what it holds.
Written by a newer Kent than this one	Kent will not guess at a format that postdates it. The message names the version it found and the version it understands.
A table listed but missing	The archive's own manifest promised it. A restore that quietly loaded part of an archive and reported success would be worse than one that refuses.
Contents disagreeing with the manifest	A row count or schema version that does not match what the archive says about itself. The archive is damaged or was built incorrectly.

$ kent restore --in future.kent --out out.sqlite
kent restore: this archive is format version 99, but this build of kent understands version 1 at most
$ echo $?
1

A failure leaves nothing behind: no partial database, no temporary directory, no half-written file to notice and delete. Every table is loaded inside a single transaction.