Struct DatabaseManager

Source

pub struct DatabaseManager { /* private fields */ }

Expand description

Main type that manages a database directory and its index.

Implementations§

Source §

impl DatabaseManager

Source

pub fn create_database( path: impl AsRef<Path>, name: impl AsRef<Path>, ) -> Result<Self, DatabaseError>

Creates or opens a database directory and returns a manager for it.

§Parameters

path: parent directory where the database folder should exist.
name: database directory name appended to path.

§Errors

Returns an error if:

the target path exists but is not a directory,
parent directories are missing when creating a new database directory,
the process cannot create/read directories at the destination.

§Examples

use file_database::{DatabaseError, DatabaseManager};

fn main() -> Result<(), DatabaseError> {
    let _manager = DatabaseManager::create_database(".", "database")?;
    Ok(())
}

Source

pub fn write_new( &mut self, id: impl Into<ItemId>, parent: impl Into<ItemId>, ) -> Result<(), DatabaseError>

Creates a new file or directory under parent.

Name interpretation is extension-based:

if id.name has an extension, a file is created,
otherwise, a directory is created.

§Parameters

id: name key for the new item. Root ItemId is not allowed.
parent: destination parent item. Use ItemId::database_id() for database root.

§Errors

Returns an error if:

id is the ItemId::database_id(),
parent cannot be found,
another item already exists at the target relative path,
filesystem create operations fail.

§Examples

use file_database::{DatabaseError, DatabaseManager, ItemId};

fn main() -> Result<(), DatabaseError> {
    let mut manager = DatabaseManager::create_database(".", "database")?;
    manager.write_new(ItemId::id("notes.txt"), ItemId::database_id())?;
    Ok(())
}

Source

pub fn overwrite_existing<T>( &self, id: impl Into<ItemId>, data: T, ) -> Result<(), DatabaseError>
where T: AsRef<[u8]>,

Overwrites an existing file with raw bytes in a safe way.

It writes to a temp file first, then replaces the target file.

§Parameters

id: target file ItemId.
data: raw bytes to write.

§Errors

Returns an error if:

id cannot be found,
id points to a directory,
writing, syncing, or renaming fails.

§Examples

use file_database::{DatabaseError, DatabaseManager, ItemId};

fn main() -> Result<(), DatabaseError> {
    let mut manager = DatabaseManager::create_database(".", "database")?;
    manager.write_new(ItemId::id("blob.bin"), ItemId::database_id())?;
    manager.overwrite_existing(ItemId::id("blob.bin"), [1_u8, 2, 3, 4])?;
    Ok(())
}

Source

pub fn overwrite_existing_json<T: Serialize>( &self, id: impl Into<ItemId>, value: &T, pretty: impl Into<bool>, ) -> Result<(), DatabaseError>

Converts value to JSON and overwrites the target file.

§Parameters

id: target file ItemId.
value: serializable value.
pretty: if true, writes pretty-printed JSON; otherwise compact JSON.

§Errors

Returns an error if:

JSON serialization fails,
finding id or overwriting the file fails.

§Examples

use file_database::{DatabaseError, DatabaseManager, ItemId};
use serde::Serialize;

#[derive(Serialize)]
struct Config {
    retries: u8,
}

fn main() -> Result<(), DatabaseError> {
    let mut manager = DatabaseManager::create_database(".", "database")?;
    manager.write_new(ItemId::id("config.json"), ItemId::database_id())?;
    manager.overwrite_existing_json(ItemId::id("config.json"), &Config { retries: 3 }, false)?;
    Ok(())
}

Source

pub fn overwrite_existing_binary<T: Serialize>( &self, id: impl Into<ItemId>, value: &T, ) -> Result<(), DatabaseError>

Converts value to bincode and overwrites the target file.

§Parameters

id: target file ItemId.
value: serializable value.

§Errors

Returns an error if:

bincode serialization fails,
finding id or overwriting the file fails.

§Examples

use file_database::{DatabaseError, DatabaseManager, ItemId};
use serde::Serialize;

#[derive(Serialize)]
enum State {
    Ready,
}

fn main() -> Result<(), DatabaseError> {
    let mut manager = DatabaseManager::create_database(".", "database")?;
    manager.write_new(ItemId::id("state.bin"), ItemId::database_id())?;
    manager.overwrite_existing_binary(ItemId::id("state.bin"), &State::Ready)?;
    Ok(())
}

Source

pub fn overwrite_existing_from_reader<R: Read>( &self, id: impl Into<ItemId>, reader: &mut R, ) -> Result<u64, DatabaseError>

Streams bytes from reader into the target file and returns bytes written.

This uses chunked I/O and a safe replace step, so it works well for large payloads.

§Parameters

id: target file ItemId.
reader: source stream consumed until EOF.

§Errors

Returns an error if:

id cannot be found,
target is not a file,
stream read/write/sync/rename fails.

§Examples

use std::io::Cursor;
use file_database::{DatabaseError, DatabaseManager, ItemId};

fn main() -> Result<(), DatabaseError> {
    let mut manager = DatabaseManager::create_database(".", "database")?;
    manager.write_new(ItemId::id("stream.bin"), ItemId::database_id())?;
    let mut source = Cursor::new(vec![9_u8; 1024]);
    let _bytes = manager.overwrite_existing_from_reader(ItemId::id("stream.bin"), &mut source)?;
    Ok(())
}

Source

pub fn read_existing( &self, id: impl Into<ItemId>, ) -> Result<Vec<u8>, DatabaseError>

Reads a managed file and returns its raw bytes.

§Parameters

id: target file ItemId.

§Errors

Returns an error if:

id cannot be found,
id points to a directory,
file reading fails.

§Examples

use file_database::{DatabaseError, DatabaseManager, ItemId};

fn main() -> Result<(), DatabaseError> {
    let mut manager = DatabaseManager::create_database(".", "database")?;
    manager.write_new(ItemId::id("data.bin"), ItemId::database_id())?;
    manager.overwrite_existing(ItemId::id("data.bin"), [1_u8, 2, 3])?;
    let _data = manager.read_existing(ItemId::id("data.bin"))?;
    Ok(())
}

Source

pub fn read_existing_json<T: DeserializeOwned>( &self, id: impl Into<ItemId>, ) -> Result<T, DatabaseError>

Reads a managed file and turns JSON into T.

§Parameters

id: target file ItemId.

§Errors

Returns an error if:

finding id or reading the file fails,
JSON deserialization fails.

§Examples

use file_database::{DatabaseError, DatabaseManager, ItemId};
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize)]
struct Config {
    retries: u8,
}

fn main() -> Result<(), DatabaseError> {
    let mut manager = DatabaseManager::create_database(".", "database")?;
    manager.write_new(ItemId::id("config.json"), ItemId::database_id())?;
    manager.overwrite_existing_json(ItemId::id("config.json"), &Config { retries: 3 }, false)?;
    let _loaded: Config = manager.read_existing_json(ItemId::id("config.json"))?;
    Ok(())
}

Source

pub fn read_existing_binary<T: DeserializeOwned>( &self, id: impl Into<ItemId>, ) -> Result<T, DatabaseError>

Reads a managed file and turns bincode into T.

§Parameters

id: target file ItemId.

§Errors

Returns an error if:

finding id or reading the file fails,
bincode deserialization fails.

§Examples

use file_database::{DatabaseError, DatabaseManager, ItemId};
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize)]
enum State {
    Ready,
}

fn main() -> Result<(), DatabaseError> {
    let mut manager = DatabaseManager::create_database(".", "database")?;
    manager.write_new(ItemId::id("state.bin"), ItemId::database_id())?;
    manager.overwrite_existing_binary(ItemId::id("state.bin"), &State::Ready)?;
    let _loaded: State = manager.read_existing_binary(ItemId::id("state.bin"))?;
    Ok(())
}

Source

pub fn get_all(&self, sorted: impl Into<bool>) -> Vec<ItemId>

Returns every tracked item in the database.

§Parameters

sorted: whether output should be sorted by ItemId ordering.

§Examples

use file_database::{DatabaseError, DatabaseManager, ItemId};

fn main() -> Result<(), DatabaseError> {
    let mut manager = DatabaseManager::create_database(".", "database")?;
    manager.write_new(ItemId::id("a.txt"), ItemId::database_id())?;
    let _all = manager.get_all(true);
    Ok(())
}

Source

pub fn get_by_parent( &self, parent: impl Into<ItemId>, sorted: impl Into<bool>, ) -> Result<Vec<ItemId>, DatabaseError>

Returns all tracked items that are direct children of parent.

If parent is the ItemId::database_id(), this returns all top-level items.

§Parameters

parent: parent directory item to query.
sorted: whether output should be sorted by ItemId.

§Errors

Returns an error if:

parent cannot be found,
parent points to a file instead of a directory.

§Examples

use file_database::{DatabaseError, DatabaseManager, ItemId};

fn main() -> Result<(), DatabaseError> {
    let mut manager = DatabaseManager::create_database(".", "database")?;
    manager.write_new(ItemId::id("folder"), ItemId::database_id())?;
    manager.write_new(ItemId::id("a.txt"), ItemId::id("folder"))?;
    let _children = manager.get_by_parent(ItemId::id("folder"), true)?;
    Ok(())
}

Source

pub fn get_parent(&self, id: impl Into<ItemId>) -> Result<ItemId, DatabaseError>

Returns the parent ItemId for an item.

Top-level items return ItemId::database_id.

§Parameters

id: item whose parent should be looked up.

§Errors

Returns an error if:

id cannot be found,
parent path data cannot be converted to UTF-8 string.

§Examples

use file_database::{DatabaseError, DatabaseManager, ItemId};

fn main() -> Result<(), DatabaseError> {
    let mut manager = DatabaseManager::create_database(".", "database")?;
    manager.write_new(ItemId::id("folder"), ItemId::database_id())?;
    manager.write_new(ItemId::id("a.txt"), ItemId::id("folder"))?;
    let _parent = manager.get_parent(ItemId::id("a.txt"))?;
    Ok(())
}

Source

pub fn rename( &mut self, id: impl Into<ItemId>, to: impl AsRef<str>, ) -> Result<(), DatabaseError>

Renames the chosen item to to in the same parent directory.

§Parameters

id: source ItemId to rename.
to: new file or directory name.

§Errors

Returns an error if:

id is the ItemId::database_id(),
id cannot be found,
destination name already exists at the same relative path,
underlying filesystem rename fails.

§Examples

use file_database::{DatabaseError, DatabaseManager, ItemId};

fn main() -> Result<(), DatabaseError> {
    let mut manager = DatabaseManager::create_database(".", "database")?;
    manager.write_new(ItemId::id("old.txt"), ItemId::database_id())?;
    manager.rename(ItemId::id("old.txt"), "new.txt")?;
    Ok(())
}

Source

pub fn delete( &mut self, id: impl Into<ItemId>, force: impl Into<bool>, ) -> Result<(), DatabaseError>

Deletes a file, directory, or the whole database root.

§Parameters

id: item to delete. Use ItemId::database_id() to target the database folder itself.
force: when deleting directories, controls recursive vs empty-only behavior.

§Errors

Returns an error if:

id cannot be found,
directory deletion does not match force rules,
filesystem delete operations fail.

§Examples

use file_database::{DatabaseError, DatabaseManager, ForceDeletion, ItemId};

fn main() -> Result<(), DatabaseError> {
    let mut manager = DatabaseManager::create_database(".", "database")?;
    manager.write_new(ItemId::id("tmp.txt"), ItemId::database_id())?;
    manager.delete(ItemId::id("tmp.txt"), ForceDeletion::Force)?;
    Ok(())
}

Source

pub fn locate_absolute( &self, id: impl Into<ItemId>, ) -> Result<PathBuf, DatabaseError>

Gets the absolute file path for an ItemId.

For the ItemId::database_id(), this returns the database directory path.

§Parameters

id: ItemId to look up.

§Errors

Returns an error if:

id does not exist.

§Examples

use file_database::{DatabaseError, DatabaseManager, ItemId};

fn main() -> Result<(), DatabaseError> {
    let mut manager = DatabaseManager::create_database(".", "database")?;
    manager.write_new(ItemId::id("a.txt"), ItemId::database_id())?;
    let _path = manager.locate_absolute(ItemId::id("a.txt"))?;
    Ok(())
}

Source

pub fn locate_relative( &self, id: impl Into<ItemId>, ) -> Result<&PathBuf, DatabaseError>

Gets the stored relative path reference for an ItemId.

For the ItemId::database_id(), this currently returns a reference to the manager root path.

§Parameters

id: ItemId to look up.

§Errors

Returns an error if:

id does not exist.

§Examples

use file_database::{DatabaseError, DatabaseManager, ItemId};

fn main() -> Result<(), DatabaseError> {
    let mut manager = DatabaseManager::create_database(".", "database")?;
    manager.write_new(ItemId::id("a.txt"), ItemId::database_id())?;
    let _relative = manager.locate_relative(ItemId::id("a.txt"))?;
    Ok(())
}

Source

pub fn get_ids_by_name(&self, name: impl AsRef<str>) -> Vec<ItemId>

Returns all stored ItemId values that share a name.

The returned IDs use the occupied stable indexes from that internal name bucket.

Source

pub fn get_ids_by_index(&self, index: usize) -> Vec<ItemId>

Returns all stored ItemId values that share an index.

This scans all name buckets and returns every ID whose stable slot equals index.

Source

pub fn scan_for_changes( &mut self, scan_from: impl Into<ItemId>, policy: ScanPolicy, recursive: bool, ) -> Result<ScanReport, DatabaseError>

Scans files on disk and compares them to entries in this scan area.

Missing tracked items are always removed from the items index kept in memory.

Policy behavior for newly discovered external items:

DetectOnly: detect only.
AddNew: detect and add to the index.
RemoveNew: delete from disk and do not keep them in the report.

§Parameters

scan_from: root ItemId to scan from (ItemId::database_id() scans the full database).
policy: change handling policy.
recursive: true scans full subtree, false scans immediate children only.

§Errors

Returns an error if:

scan_from cannot be found,
scan_from points to a file,
path-to-string conversion fails for discovered entries,
filesystem read or delete operations fail.

§Examples

use file_database::{DatabaseError, DatabaseManager, ItemId, ScanPolicy};

fn main() -> Result<(), DatabaseError> {
    let mut manager = DatabaseManager::create_database(".", "database")?;
    let _report = manager.scan_for_changes(ItemId::database_id(), ScanPolicy::AddNew, true)?;
    Ok(())
}

Source

pub fn migrate_database( &mut self, to: impl AsRef<Path>, ) -> Result<(), DatabaseError>

Moves the entire database directory to a new parent directory.

Existing destination database directory with the same name is removed first.

§Parameters

to: destination parent directory.

§Errors

Returns an error if:

current database path is invalid,
destination cleanup fails,
recursive copy or source removal fails.

§Examples

use file_database::{DatabaseError, DatabaseManager};

fn main() -> Result<(), DatabaseError> {
    let mut manager = DatabaseManager::create_database(".", "database")?;
    manager.migrate_database("./new_parent")?;
    Ok(())
}

Source

pub fn migrate_item( &mut self, id: impl Into<ItemId>, to: impl Into<ItemId>, ) -> Result<(), DatabaseError>

Moves a managed item to another directory inside the same database.

§Parameters

id: source item to move.
to: destination directory item (or ItemId::database_id()).

§Errors

Returns an error if:

id is root or cannot be found,
destination is not a directory,
source and destination are identical,
filesystem move fails.

§Examples

use file_database::{DatabaseError, DatabaseManager, ItemId};

fn main() -> Result<(), DatabaseError> {
    let mut manager = DatabaseManager::create_database(".", "database")?;
    manager.write_new(ItemId::id("folder"), ItemId::database_id())?;
    manager.write_new(ItemId::id("a.txt"), ItemId::database_id())?;
    manager.migrate_item(ItemId::id("a.txt"), ItemId::id("folder"))?;
    Ok(())
}

Source

pub fn export_item( &mut self, id: impl Into<ItemId>, to: impl AsRef<Path>, mode: ExportMode, ) -> Result<(), DatabaseError>

Exports a managed file or directory to an external destination directory.

Copy keeps the item in the index. Move removes the moved entry from the index.

§Parameters

id: source item to export.
to: external destination directory path.
mode: copy or move behavior.

§Errors

Returns an error if:

id is root or cannot be found,
destination is inside the database,
destination path cannot be created or used as a directory,
filesystem copy/move operations fail.

§Examples

use file_database::{DatabaseError, DatabaseManager, ExportMode, ItemId};

fn main() -> Result<(), DatabaseError> {
    let mut manager = DatabaseManager::create_database(".", "database")?;
    manager.write_new(ItemId::id("a.txt"), ItemId::database_id())?;
    manager.export_item(ItemId::id("a.txt"), "./exports", ExportMode::Copy)?;
    Ok(())
}

Source

pub fn import_item( &mut self, from: impl AsRef<Path>, to: impl Into<ItemId>, ) -> Result<(), DatabaseError>

Imports an external file or directory into a database destination directory.

The imported item keeps its original name.

§Parameters

from: source path outside the database.
to: destination directory item in the database.

§Errors

Returns an error if:

source path points inside the database,
destination is not a directory,
destination path/name already exists,
source does not exist as file or directory,
filesystem copy operations fail.

§Examples

use file_database::{DatabaseError, DatabaseManager, ItemId};

fn main() -> Result<(), DatabaseError> {
    let mut manager = DatabaseManager::create_database(".", "database")?;
    manager.write_new(ItemId::id("imports"), ItemId::database_id())?;
    manager.import_item("./outside/example.txt", ItemId::id("imports"))?;
    Ok(())
}

Source

pub fn duplicate_item( &mut self, id: impl Into<ItemId>, parent: impl Into<ItemId>, name: impl AsRef<str>, ) -> Result<(), DatabaseError>

Duplicates a managed item into parent using a caller-provided name.

§Parameters

id: source item to duplicate.
parent: destination parent directory item (or ItemId::database_id()).
name: new name for the duplicate.

§Errors

Returns an error if:

id is root or cannot be found,
destination parent is not a directory,
destination name already exists in the target directory,
filesystem copy fails.

§Examples

use file_database::{DatabaseError, DatabaseManager, ItemId};

fn main() -> Result<(), DatabaseError> {
    let mut manager = DatabaseManager::create_database(".", "database")?;
    manager.write_new(ItemId::id("a.txt"), ItemId::database_id())?;
    manager.duplicate_item(ItemId::id("a.txt"), ItemId::database_id(), "copy.txt")?;
    Ok(())
}

Source

pub fn get_file_information( &self, id: impl Into<ItemId>, ) -> Result<FileInformation, DatabaseError>

Returns filesystem metadata summary for a managed file or directory.

Includes:

name/extension,
normalized size,
Unix timestamps and “time since” timestamps where available.

§Parameters

id: item to inspect.

§Errors

Returns an error if:

id cannot be found,
metadata lookup fails.

§Examples

use file_database::{DatabaseError, DatabaseManager, ItemId};

fn main() -> Result<(), DatabaseError> {
    let mut manager = DatabaseManager::create_database(".", "database")?;
    manager.write_new(ItemId::id("a.txt"), ItemId::database_id())?;
    let _info = manager.get_file_information(ItemId::id("a.txt"))?;
    Ok(())
}