Getting Started

PocketDB is a fast, embedded, single-file NoSQL document database for Rust built entirely from scratch — no server process, no configuration files, just open a file and start working.

Installation

Add PocketDB to your Cargo.toml:

[dependencies]
pocketdb = "0.1"

Or add it via the command line:

cargo add pocketdb

Quick Start

1. Open a Database

use pocketdb::Database;

fn main() -> pocketdb::Result<()> {
    // Opens or creates a database file
    let db = Database::open("mydata.pdb")?;
    Ok(())
}

If the file doesn't exist, it's created. If it does, it's opened and any pending WAL recovery is performed automatically.

2. Get a Collection

Collections are created lazily — just request one by name:

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

3. Insert Documents

Use the doc! macro for convenient document creation:

use pocketdb::doc;

let id = users.insert(doc! {
    "name" => "Alice",
    "age" => 30,
    "email" => "alice@example.com",
    "active" => true
})?;

println!("Inserted user with ID: {}", id);

4. Query Documents

Use Filter methods or the filter! macro:

use pocketdb::{filter, PocketValue};

// Find all active users over 18
let f = filter! { "age" => > 18, "active" => == true };
let results = users.find(f).run(&users.all_documents())?;

for doc in &results {
    println!("{}", doc);
}

5. Update Documents

use pocketdb::query::UpdateExpression;

users.update_one(
    &filter! { "name" => == "Alice" },
    &UpdateExpression::new().set("age", PocketValue::Int(31)),
)?;

6. Delete Documents

users.delete_one(&filter! { "name" => == "Alice" })?;

7. Use Transactions

let mut tx = db.begin_transaction()?;
{
    let mut orders = tx.collection("orders")?;
    orders.insert(doc! { "item" => "Widget", "qty" => 5 })?;
}
tx.commit()?;

Complete Example

use pocketdb::{Database, doc, filter, PocketValue};
use pocketdb::query::UpdateExpression;

fn main() -> pocketdb::Result<()> {
    // Create or open the database
    let db = Database::open("example.pdb")?;

    // Get a collection (created automatically if needed)
    let products = db.collection("products")?;

    // Insert some products
    products.insert(doc! {
        "name" => "Laptop",
        "price" => 999.99,
        "category" => "electronics",
        "in_stock" => true
    })?;

    products.insert(doc! {
        "name" => "Book",
        "price" => 19.99,
        "category" => "books",
        "in_stock" => true
    })?;

    // Query: find products under $50
    let cheap = products.find(
        filter! { "price" => < 50.0 }
    ).run(&products.all_documents())?;

    println!("Affordable products: {}", cheap.len());

    // Update: put laptop on sale
    products.update_one(
        &filter! { "name" => == "Laptop" },
        &UpdateExpression::new().set("price", PocketValue::Float(899.99)),
    )?;

    // Get stats
    let stats = db.stats();
    println!("Collections: {}, Pages: {}", stats.collection_count, stats.page_count);

    Ok(())
}

What's Next?

• Learn about Documents & PocketValue types
• Explore Queries & Filters for powerful data retrieval
• Set up Indexes for fast lookups
• Use Transactions for atomic multi-document operations
• Try Aggregation Pipelines for data analysis