Backups, updates, import and export
This page covers keeping recovery points, updating Bookclerk safely, and moving a library in or out: to and from Libation, between Bookclerk installs, and out to Postgres. For a step-by-step move from Libation, see Coming from Libation.
A recovery point is a backup of the library database's schema and
data, made with bookclerk db. Use recovery points before an update and
whenever you want a way back.
| Task | Command |
|---|---|
| Show the schema state | bookclerk db version |
| Make a recovery point | bookclerk db backup create --path ./recovery-point.tar.gz |
| Include plugin databases | bookclerk db backup create --include-plugin-databases |
| List recovery points | bookclerk db backup list |
| Check one | bookclerk db backup verify --from <id-or-archive> |
| Remove old automatic ones | bookclerk db backup prune |
| Restore from a file | bookclerk db restore --from ./recovery-point.tar.gz |
| Restore by id or time | bookclerk db restore --from <recovery-point-id-or-timestamp> |
| Migrate to a schema version | bookclerk db migrate --to 1 |
Schema backups live only on bookclerk db. export native makes a files
archive, config database migrate switches backends, and plugins db
lists or drops plugin bindings.
bookclerk db version prints one of:
uninitialized: no schema yet.unreleased@base<n>+<checksum>: a development schema.frozen@<version>+<checksum>: a released schema.
SCHEMA_VERSION = 0 means there are no frozen revisions yet. There is no
released v1 schema yet either.
- Bookclerk makes a pre-migrate recovery point automatically, under
$BOOKCLERK_FILES_DIR/backups/. It keeps the last five, and removes ones nothing refers to. - Recovery points you make yourself (
manual) are never pruned.
Warning
A restore replaces the schema and the data. It does not migrate afterwards.
- Bookclerk checks the recovery point's integrity before it changes anything.
- The content is in Bookclerk's own format, so it restores onto a different database adapter too.
migrate --to <older>can only step down through reversible frozen steps, and none exist yet. To go back in time, restore instead.
--include-plugin-databases also saves the databases plugins own (the
plugin_databases registry), in Bookclerk's portable format.
- Each database is replaced as a whole on restore. A bundle of several databases is not one transaction across them.
- An adapter that can't take part fails closed.
- Plugin schema changes run as host-mediated BookclerkSQL in the plugin's own namespace, not through a migration framework of the plugin's.
Contributors adding host schema changes: see ADR: schema versioning.
Bookclerk has no release yet, so its database layout is a development layout. There is no upgrade path between two builds whose layouts differ.
A build opens a library whose layout matches it. Otherwise it refuses,
with unreleased schema checksum … does not match this binary …; recreate the database (cargo reset --yes), rather than reshape the library. See
ADR: schema versioning.
-
Make a recovery point with the build you are running now:
bookclerk db backup create --path ./before-update.tar.gz -
Keep a copy of
master.key, and know yourBOOKCLERK_AUTH_PASSWORDif you set one. If the key is in the OS keychain or sealed withsystemd-creds(bookclerk config master-key statussaysstore=keychainorstore=systemd-creds),master.keyonly names the item: save a recovery copy withbookclerk config master-key export --out <file>(or from Settings → Server Settings in the web app) instead, and restore it withbookclerk config master-key import --from <file>. Import only writes a newmaster.key: if the item was lost but itsmaster.keypointer is still there, stop every host and move thatmaster.keyaside first. -
Optionally, save a book list that any build can read:
bookclerk export libation --path ./LibationFilesOut --force
Caution
Without the key (master.key or a recovery copy, and its password),
sealed store sign-ins can't be read back.
- Update the checkout with
git pull. - Start Bookclerk again:
cargo dev --optional, or rebuild the release binaries and restart the service.
Pick one:
- Go back to the previous build. Your recovery point still restores there.
- Start fresh. Run
cargo reset --yes, then bring the book list back withbookclerk import libation --from ./LibationFilesOut. Store sign-ins are never exported, so connect the stores again afterwards.
A native backup is a .tar.gz of the files directory: config,
library.db, and any extras you add. Use it to move between Bookclerk
installs. It is an archive of files, not a walk of the schema.
bookclerk export native --path ./bookclerk-backup.tar.gz
bookclerk import native --from ./bookclerk-backup.tar.gz --force
Optional export flags add more: --include-plugin-manifests,
--include-cache, --include-logs and --include-plugin-databases.
Bookclerk imports classic Libation Files: settings, accounts and the SQLite database.
export BOOKCLERK_FILES_DIR=./BookclerkFiles
bookclerk import libation --from ~/LibationFiles --force
bookclerk migrate import still works as a hidden alias.
| Flag | Meaning |
|---|---|
--from |
The Libation Files folder (or BOOKCLERK_CLASSIC_FILES) |
--force |
Overwrite an existing config.toml |
--skip-auth |
Does nothing; kept so old scripts still run |
--dry-run |
Report what would happen, change nothing |
- Settings go to
config.toml: Widevine, lossy decrypt, folder and file templates, and cover, cue and fix-up flags. The packaging settings seed thecore.outputdocument when the database has none yet. If it has one, Bookclerk keeps it and warns. AccountsSettings.jsonbecomes account details inlibrary.db, without credentials.LibationContext.dbbecomes Bookclerk'slibrary.db.- Naming templates and user metadata, where present.
Example accounts file:
examples/AccountsSettings.example.json.
Important
Store credentials don't come across. IdentityTokens and other file-based sign-ins are discarded. After the import, connect Audible again from Accounts; see Stores.
- Run
bookclerk plugins listand keep only the stores you use.bookclerk plugins undeploy <id>retires the rest on this host. - Check the accounts with
bookclerk library accountsandbookclerk library status. - Check the destination with
bookclerk plugins config get local. The import seeds the books folder there. - If books are already on disk or in S3, run
bookclerk library scan --match-storage. - Keep
library.auto_acquire = falseuntil a dry run looks right.
How Bookclerk's settings and commands map to Libation's: Libation parity.
bookclerk export libation --path ./LibationFilesOut --force
This writes Settings.json, AccountsSettings.json (account details
only) and LibationContext.db, for classic tools. Credentials are never
exported; they stay in encrypted_secrets.
LibationContext.db lists every store account title. Tags, ratings and
finished flags belong to each person, so they are empty unless
--user <login name or id> names whose to write.
bookclerk export library --path ./library.csv
bookclerk export library --path ./riley.xlsx --user riley
This writes one row per store account title, as CSV, JSON or XLSX (picked
by --csv, --json, --xlsx or the file's extension, CSV otherwise).
bookclerk library export is the same command.
- Without
--userthe file lists the whole library, and thetagsandis_finishedcolumns are empty (nullin JSON), because those belong to each person. - With
--user <login name or id>the file lists the same titles with that person's own tags and finished flags. --accountkeeps one store account's titles, and ids after the flags (ASIN, ISBN, product id or holding id) keep only those titles.
The spreadsheet columns are asin, account_id, title, authors,
narrators, series, acquire_status, pdf_status, storage_key,
tags and is_finished. JSON has one object per title with the same
fields plus its holding_id, edition_id, work_id, store and listing
details.
bookclerk export postgres …
bookclerk copydb is a hidden alias. The default layout matches classic
Libation's EF Postgres schema; --format flat picks Bookclerk's flat
layout, one books row per account title. Either way the titles come
from the library and leave people's own tags, ratings and finished flags
empty, as export libation does without --user. See
bookclerk export postgres --help.
- Database: backends, and moving between them.
- Security checklist: what to set up before going public.
- CLI reference: every command and flag.
Source: docs/server/backups.md at main · View as Markdown