bookclerk_migrate
Import/export classic Libation Files and native Bookclerk backups.
CLI migration commands and host tooling. Converts classic Libation directories
into Bookclerk files layouts, and round-trips native .tar.zst backups.
| Item | Kind | Summary |
|---|---|---|
ClassicSource |
struct | Paths discovered in a classic Libation Files directory. |
LibationExportOptions |
struct | Options for Libation-compatible export. |
LibationExportSummary |
struct | Summary of a Libation export. |
NativeExportOptions |
struct | Options for exporting a native backup. |
NativeExportSummary |
struct | Summary of a native export. |
NativeImportOptions |
struct | Options for importing a native backup. |
NativeImportSummary |
struct | Summary of a native import. |
ClassicPluginSettings |
struct | Classic settings that belong to plugin instances rather than config.toml. |
MigrateOptions |
struct | Options for a full classic Libation Files directory import. |
MigrateSummary |
struct | Summary of a migration run. |
MigrateError |
enum | Errors from Libation import / native backup export and import. |
import_accounts |
function | Import account metadata from AccountsSettings.json. |
write_classic_storefront_file |
function | Writes AccountsSettings.json from library identity rows. |
discover_source |
function | Discover importable files under root. |
export_libation |
function | Write Settings.json and LibationContext.db. |
load_audio_paths |
function | Load audio paths keyed by ASIN. |
import_library_db |
function | Import books from classic EF Core SQLite LibationContext.db. |
export_native |
function | Export Bookclerk files-dir essentials into a .tar.gz archive. |
import_native |
function | Restore a native backup archive into dest_files_dir. |
apply_settings_json |
function | Apply classic Settings.json keys onto config. |
config_to_settings_json |
function | Best-effort reverse of apply_settings_json for Libation Settings.json export. |
load_settings_json |
function | Load Settings.json as a JSON object. |
migrate |
function | Import classic Libation Files into a bookclerk data directory. |
resolve_classic_files_dir |
function | Resolve a classic Libation path from CLI / env. |
Result |
type alias | Result alias for this crate's error type. |
NATIVE_BACKUP_FORMAT_VERSION |
constant | Current native backup format version. |
pub struct ClassicSource {
pub root: PathBuf,
pub settings_json: Option<PathBuf>,
pub accounts_settings: Option<PathBuf>,
pub library_db: Option<PathBuf>,
pub file_locations: Option<PathBuf>,
}
Paths discovered in a classic Libation Files directory.
Fields
root: Filesystem root of the classic Libation Files directory.settings_json: Path to LibationSettings.jsonwhen present.accounts_settings: Path to LibationAccountsSettings.jsonwhen present.library_db: Path to Libationlibation.db(or equivalent) when present.file_locations: Path to Libation file-locations JSON when present.
Implements: Clone, Debug
pub struct LibationExportOptions {
pub files_dir: PathBuf,
pub dest: PathBuf,
pub force: bool,
pub dry_run: bool,
pub user: Option<String>,
}
Options for Libation-compatible export.
Fields
files_dir: Bookclerk or Libation files directory root for this operation.dest: Destination path for the export archive or directory.force: When true, overwrite existing data instead of failing on conflict.dry_run: When true, report what would change without writing files.user: Whose tags, ratings and finished flags to export (login name or user id);Noneexports every title with them empty, since they belong to each person.
Implements: Clone, Debug
pub struct LibationExportSummary {
pub settings: bool,
pub storefronts: usize,
pub books: usize,
pub warnings: Vec<String>,
}
Summary of a Libation export.
Fields
settings: Count of settings keys imported or exported.storefronts: Count of storefront identities exported (JSON key remainsaccounts).books: Count of book rows imported or exported.warnings: Non-fatal warnings collected during the run (operator-facing).
Implements: Clone, Debug, Default, Deserialize<'de>, Serialize
pub struct NativeExportOptions {
pub files_dir: PathBuf,
pub dest: PathBuf,
pub bookclerk_version: String,
pub include_plugin_manifests: bool,
pub include_cache: bool,
pub include_logs: bool,
pub include_plugin_databases: bool,
}
Options for exporting a native backup.
Fields
files_dir: Bookclerk or Libation files directory root for this operation.dest: Destination archive path. Absolute, or relative to the process cwd. This is an operator choice and is not jailed underSelf::files_dir.bookclerk_version: Bookclerk version string recorded in the backup manifest.include_plugin_manifests: Includeplugins/**/plugin.toml(not plugin binaries).include_cache: Includecache/(large; off by default).include_logs: Includelogs/(off by default).include_plugin_databases: Includeplugin-databases/(SQLite binding files; plugin DDL is not migrated).
Implements: Clone, Debug
pub struct NativeExportSummary {
pub archive: String,
pub files: usize,
pub included: Vec<String>,
}
Summary of a native export.
Fields
archive: Path to the native backup.tar.zst(or similar) archive.files: Count of files packaged or restored.included: Logical paths included in the archive.
Implements: Clone, Debug, Default, Deserialize<'de>, Serialize
pub struct NativeImportOptions {
pub archive: PathBuf,
pub dest_files_dir: PathBuf,
pub force: bool,
pub dry_run: bool,
}
Options for importing a native backup.
Fields
archive: Path to the native backup.tar.zst(or similar) archive.dest_files_dir: Destination Bookclerk files directory for import.force: When true, overwrite existing data instead of failing on conflict.dry_run: When true, report what would change without writing files.
Implements: Clone, Debug
pub struct NativeImportSummary {
pub files: usize,
pub format_version: u32,
pub warnings: Vec<String>,
}
Summary of a native import.
Fields
files: Count of files packaged or restored.format_version: Native backup format version actually read from the archive.warnings: Non-fatal warnings collected during the run (operator-facing).
Implements: Clone, Debug, Default, Deserialize<'de>, Serialize
pub struct ClassicPluginSettings {
pub books_root: Option<PathBuf>,
pub audible_bitrate: Option<String>,
}
Classic settings that belong to plugin instances rather than config.toml.
Fields
books_root: LibationBooksdirectory: thelocaldestination'sroot.audible_bitrate: LibationFileDownloadQualityas the Audible plugin'sbitrate(highornormal).
Implements: Clone, Debug, Default, Eq, PartialEq
pub struct MigrateOptions {
pub source: PathBuf,
pub dest_files_dir: PathBuf,
pub force: bool,
pub skip_auth: bool,
pub dry_run: bool,
pub audible_plugin_key: String,
pub local_plugin_key: Option<String>,
pub host_config: Option<Config>,
}
Options for a full classic Libation Files directory import.
Fields
source: Absolute path to the classic Libation Files directory to import.dest_files_dir: Destination files dir (auth, library.db, config.toml).force: When true, overwrite an existing destinationconfig.toml.skip_auth: Retained for CLI compatibility; credentials are never imported by migrate (use the Audible plugin:auth login/auth import).dry_run: Report only; do not write.audible_plugin_key: Canonical PluginKey of the Audible storefront plugin. Imported accounts and books are owned by that plugin; the caller resolves it from the installed plugin (bookclerk plugins list).local_plugin_key: Canonical PluginKey of thelocaldestination plugin, when installed. The classicBooksdirectory is written to its default instance asroot, so acquired files keep landing where Libation put them.host_config: Host configuration used to enrol the installed plugins into the destination database before instance settings are seeded. A fresh files directory has no pinned schema and no default instance until a host enrols, so without this therootandbitrateseeds have nowhere to go.Noneskips enrollment (tests, dry runs).
Implements: Clone, Debug
pub struct MigrateSummary {
pub settings_imported: bool,
pub accounts: usize,
pub credentials: usize,
pub books: usize,
pub acquired: usize,
pub storage_keys: usize,
pub plugin_settings: usize,
pub warnings: Vec<String>,
}
Summary of a migration run.
Fields
settings_imported: When true,Settings.jsonwas found and applied (or would be, in dry-run).accounts: Count of accounts imported or exported.credentials: Count of credential blobs imported.books: Count of book rows imported or exported.acquired: Count of books marked acquired after import.storage_keys: Count of storage-key mappings written.plugin_settings: Count of plugin instance settings written (localroot, Audible bitrate).warnings: Non-fatal warnings collected during the run (operator-facing).
Implements: Clone, Debug, Default, Deserialize<'de>, Serialize
pub enum MigrateError {
Source(String),
Settings(String),
Accounts(String),
Library(String),
Config(ConfigError),
Store(LibraryError),
Io(Error),
Sqlite(Error),
Other(Error),
}
Errors from Libation import / native backup export and import.
Variants
Source: Failure while reading or interpreting the migration source tree.Settings: Failure while importing or exporting settings.Accounts: Failure while importing or exporting accounts / credentials.Library: Error propagated frombookclerk_library.Config: Error propagated frombookclerk_config.Store: Failure while writing into the destination library store.Io: Underlying filesystem or stream I/O failure.Sqlite: SQLite error while reading a classic Libation database.Other: Opaque error wrapped fromanyhow.
Implements: Debug, Display, Error, From<ConfigError>, From<Error>, From<LibraryError>
pub async fn import_accounts(
path: &Path,
store: &LibraryStore,
plugin_key: &str,
_force: bool,
_skip_auth: bool,
dry_run: bool,
) -> Result<AccountsImportSummary>
Import account metadata from AccountsSettings.json.
skip_auth is retained for CLI compatibility; credentials are never sealed
here (Audible IdentityTokens are not converted in migrate).
path- Filesystem path involved in this operation.store- Destination library (opened by the caller through the adapter).force- When true, overwrite or force a full remote rescan.skip_auth- Boolean flagskip_auth.dry_run- Boolean flagdry_run.
On success, the inner AccountsImportSummary value.
Returns an error when the underlying I/O, parse, network, or store operation fails.
pub async fn write_classic_storefront_file(
files_dir: &Path,
dest_dir: &Path,
) -> Result<()>
Writes AccountsSettings.json from library identity rows.
files_dir- Bookclerk files directory containinglibrary.db.dest_dir- Classic Libation Files directory to write into.
Ok(()) when the file is written, or when library.db is absent.
Returns an error when listing identities or writing the JSON file fails.
pub fn discover_source(root: &Path) -> Result<ClassicSource>
Discover importable files under root.
Accepts either a classic Libation Files directory or a directory that contains
one of the expected files (for Docker /config layouts).
root- Cargo workspace root directory.
On success, the inner ClassicSource value.
Returns an error when the underlying I/O, parse, network, or store operation fails.
pub async fn export_libation(opts: LibationExportOptions) -> Result<LibationExportSummary>
Write Settings.json and LibationContext.db.
AccountsSettings.json is written separately by
crate::write_classic_storefront_file so the operator-facing summary
never carries list_accounts() payloads.
opts- Options struct for this operation.
On success, the inner LibationExportSummary value.
Returns an error when the underlying I/O, parse, network, or store operation fails.
pub fn load_audio_paths(path: &Path) -> Result<HashMap<String, PathBuf>>
Load audio paths keyed by ASIN.
path- Filesystem path involved in this operation.
On success, the inner AudioPathMap value.
Returns an error when the underlying I/O, parse, network, or store operation fails.
pub async fn import_library_db(
classic_db: &Path,
store: &LibraryStore,
plugin_key: &str,
audio_paths: &HashMap<String, PathBuf>,
books_root: &Path,
account_id_map: &HashMap<(String, String), String>,
_dry_run: bool,
) -> Result<LibraryImportSummary>
Import books from classic EF Core SQLite LibationContext.db.
classic_db- Filesystem path (classic_db).store-storeinput for this call.audio_paths- Filesystem path (audio_paths).books_root- Filesystem path (books_root).account_id_map- Stringaccount_id_mapfor this call.dry_run- Boolean flagdry_run.
On success, the inner LibraryImportSummary value.
Returns an error when the underlying I/O, parse, network, or store operation fails.
pub fn export_native(opts: NativeExportOptions) -> Result<NativeExportSummary>
Export Bookclerk files-dir essentials into a .tar.gz archive.
opts- Options struct for this operation.
On success, the inner NativeExportSummary value.
Returns an error when the underlying I/O, parse, network, or store operation fails.
pub fn import_native(opts: NativeImportOptions) -> Result<NativeImportSummary>
Restore a native backup archive into dest_files_dir.
opts- Options struct for this operation.
On success, the inner NativeImportSummary value.
Returns an error when the underlying I/O, parse, network, or store operation fails.
pub fn apply_settings_json(config: &mut Config, settings: &Value) -> ClassicPluginSettings
Apply classic Settings.json keys onto config.
Keys that configure a plugin (the books directory, the Audible bitrate) are returned instead so the caller can write them on the plugin instance.
config- Loaded Bookclerk configuration.settings-settingsinput for this call.
pub fn config_to_settings_json(
config: &Config,
plugin_settings: &ClassicPluginSettings,
) -> Value
Best-effort reverse of apply_settings_json for Libation Settings.json export.
config- Loaded Bookclerk configuration.plugin_settings- Books directory and Audible bitrate from the plugin instances, when the caller could read them.
Value result.
pub fn load_settings_json(path: &Path) -> Result<Value>
Load Settings.json as a JSON object.
path- Filesystem path involved in this operation.
On success, the inner Value value.
Returns an error when the underlying I/O, parse, network, or store operation fails.
pub async fn migrate(opts: MigrateOptions) -> Result<MigrateSummary>
Import classic Libation Files into a bookclerk data directory.
opts- Options struct for this operation.
On success, the inner MigrateSummary value.
Returns an error when the underlying I/O, parse, network, or store operation fails.
pub fn resolve_classic_files_dir(explicit: Option<&Path>) -> Option<PathBuf>
Resolve a classic Libation path from CLI / env.
explicit- Filesystem path (explicit).
Some(...) when found / applicable; otherwise None.
pub type Result<T> = Result<T, MigrateError>;
Result alias for this crate's error type.
pub const NATIVE_BACKUP_FORMAT_VERSION: u32 = 1;
Current native backup format version.
Generated from crates/bookclerk-migrate at main · View as Markdown