Database API Reference

The Database struct is the main entry point for all PocketDB operations.

Installation

Add PocketDB to your Cargo.toml:

[dependencies]
pocketdb = "0.1"

Or via the command line:

cargo add pocketdb

Import

use pocketdb::Database;

Methods

Database::open

pub fn open(path: impl AsRef<Path>) -> Result<Self>

Opens or creates a database at the given path with default settings. If the file exists, WAL recovery is performed automatically.

Parameters:

• path — Path to the database file (e.g., "data.pdb")

Returns: Result<Database>

Example:

let db = Database::open("mydata.pdb")?;

---

Database::builder

pub fn builder(path: impl AsRef<Path>) -> DatabaseConfig

Returns a DatabaseConfig builder for customizing database settings.

Example:

let db = Database::builder("mydata.pdb")
    .build()?;

---

Database::collection

pub fn collection(&self, name: &str) -> Result<Arc<Collection>>

Returns a collection handle, creating it if it doesn't exist. Collections are created lazily on first access.

Parameters:

• name — The collection name

Returns: Result<Arc<Collection>>

Example:

let users = db.collection("users")?;

---

Database::begin_transaction

pub fn begin_transaction(&self) -> Result<Transaction<'_>>

Begins a multi-collection ACID transaction. Operations within the transaction are buffered until commit() is called.

Returns: Result<Transaction>

Example:

let mut tx = db.begin_transaction()?;
{
    let mut col = tx.collection("users")?;
    col.insert(doc! { "name" => "Alice" })?;
}
tx.commit()?;

---

Database::list_collections

pub fn list_collections(&self) -> Vec<String>

Returns the names of all collections in the database.

Returns: Vec<String>

Example:

let names = db.list_collections();
for name in &names {
    println!("Collection: {}", name);
}

---

Database::drop_collection

pub fn drop_collection(&self, name: &str) -> Result<()>

Drops a collection, removing it from the database.

Parameters:

• name — The collection name to drop

Returns: Result<()>

---

Database::stats

pub fn stats(&self) -> DatabaseStats

Returns database statistics.

Returns: DatabaseStats with fields:

• page_count: u64 — Total pages in the database file
• free_pages: u64 — Number of free (reusable) pages
• collection_count: u64 — Number of collections
• file_size: u64 — File size in bytes

Example:

let stats = db.stats();
println!("Pages: {}, Size: {} bytes", stats.page_count, stats.file_size);

---

Database::backup_to

pub fn backup_to(&self, dest: impl AsRef<Path>) -> Result<()>

Creates a hot backup of the database to the given path.

Parameters:

• dest — Destination path for the backup file

Returns: Result<()>

---

Database::export_collection_json

pub fn export_collection_json(&self, name: &str, dest: impl AsRef<Path>) -> Result<()>

Exports a collection's documents as a JSON array to a file.

Parameters:

• name — Collection name to export
• dest — Destination file path

Returns: Result<()>

---

Database::import_collection_json

pub fn import_collection_json(&self, name: &str, src: impl AsRef<Path>) -> Result<usize>

Imports documents from a JSON array file into a collection.

Parameters:

• name — Target collection name
• src — Source JSON file path

Returns: Result<usize> — Number of documents imported

---

Database::validate

pub fn validate(&self) -> Result<bool>

Validates the database integrity by checking all page checksums. Returns Ok(true) if all pages are valid, Ok(false) if any page has a checksum mismatch.

Example:

let db = Database::open("mydata.pdb")?;
if db.validate()? {
    println!("Database is healthy");
} else {
    eprintln!("Corruption detected — run Database::repair()");
}

---

Database::repair

pub fn repair(path: impl AsRef<Path>) -> Result<usize>

Static method that validates and attempts to repair a corrupted database file. Reads every page, identifies corrupted ones, and cleans up stale WAL files.

Parameters:

• path — Path to the database file

Returns: Result<usize> — Number of corrupted pages found

Example:

let corrupted = Database::repair("mydata.pdb")?;
println!("Found {} corrupted pages", corrupted);

---

Database::cleanup_orphaned

pub fn cleanup_orphaned(path: impl AsRef<Path>) -> Result<bool>

Cleans up orphaned WAL files when the .pdb file has been deleted. Only removes WAL files from the .pocketdb/ directory if the .pdb file is missing.

Parameters:

• path — Path to the (missing) database file

Returns: Result<bool> — true if cleanup was performed

Example:

let cleaned = Database::cleanup_orphaned("deleted.pdb")?;

---

Database::compact

pub fn compact(&self) -> Result<()>

Flushes all data to disk and cleans up WAL files.

Example:

db.compact()?;

---

Database::path

pub fn path(&self) -> &Path

Returns the database file path.

DatabaseStats

pub struct DatabaseStats {
    pub page_count: u64,
    pub free_pages: u64,
    pub collection_count: u64,
    pub file_size: u64,
}

Drop Behavior

When the Database is dropped, it automatically syncs all data to disk.