Basic CRUD Examples

This guide covers fundamental Create, Read, Update, and Delete operations in PocketDB.

Setup

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

fn main() -> pocketdb::Result<()> {
    let db = Database::open("example.pdb")?;
    let users = db.collection("users")?;

    // ... examples below ...

    Ok(())
}

Create — Insert Documents

Single Insert

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

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

Bulk Insert

let docs = vec![
    doc! { "name" => "Alice", "age" => 30, "role" => "admin" },
    doc! { "name" => "Bob", "age" => 25, "role" => "user" },
    doc! { "name" => "Charlie", "age" => 35, "role" => "user" },
    doc! { "name" => "Diana", "age" => 28, "role" => "admin" },
];

let ids = users.insert_many(docs)?;
println!("Inserted {} users", ids.len());

Read — Query Documents

Find One

// By name
let alice = users.find_one(&filter! { "name" => == "Alice" });

// By ID
use pocketdb::PocketValue;
let user = users.find_one(&filter! { "_id" => PocketValue::ObjectId(id) });

match user {
    Some(doc) => println!("Found: {}", doc),
    None => println!("Not found"),
}

Find with Filters

// All active users
let active = users.find(filter! { "active" => == true })
    .run(&users.all_documents())?;

for user in &active {
    println!("{}", user.get("name").unwrap());
}

Find with Sorting and Pagination

use pocketdb::query::SortDirection;

let page = users.find(filter! { "active" => == true })
    .sort("name", SortDirection::Asc)
    .skip(0)    // offset
    .limit(10)  // page size
    .run(&users.all_documents())?;

Count Documents

let total = users.count(&filter::always_true())?;
let admins = users.count(&filter! { "role" => == "admin" })?;
println!("Total: {}, Admins: {}", total, admins);

Distinct Values

let roles = users.distinct("role", &filter::always_true())?;
for role in &roles {
    println!("Role: {}", role);
}

Update — Modify Documents

Update One

users.update_one(
    &filter! { "name" => == "Alice" },
    &UpdateExpression::new()
        .set("email", PocketValue::String("alice@newdomain.com".to_string()))
        .set("age", PocketValue::Int(31)),
)?;

Update Many

// Mark all users over 30 as "senior"
users.update_many(
    &filter! { "age" => > 30 },
    &UpdateExpression::new().set("level", PocketValue::String("senior".to_string())),
)?;

Increment Fields

// Increment age by 1
users.update_one(
    &filter! { "name" => == "Alice" },
    &UpdateExpression::new().inc("age", PocketValue::Int(1)),
)?;

Upsert

// Update if exists, otherwise insert
let id = users.upsert(
    &filter! { "email" => == "bob@example.com" },
    &doc! { "name" => "Bob", "email" => "bob@example.com", "age" => 25 },
)?;

Delete — Remove Documents

Delete One

let deleted = users.delete_one(&filter! { "name" => == "Charlie" })?;
println!("Deleted: {}", deleted);

Delete Many

let count = users.delete_many(&filter! { "active" => == false })?;
println!("Removed {} inactive users", count);

Replace Documents

Replace an entire document while keeping its _id:

users.replace_one(
    &filter! { "name" => == "Bob" },
    &doc! { "name" => "Bob", "email" => "bob@new.com", "age" => 26 },
)?;

Bulk Operations

Execute mixed operations atomically:

use pocketdb::collection::BulkOp;

let ops = vec![
    BulkOp::Insert(doc! { "name" => "Eve", "age" => 22 }),
    BulkOp::UpdateOne(
        filter! { "name" => == "Alice" },
        UpdateExpression::new().inc("age", PocketValue::Int(1)),
    ),
    BulkOp::DeleteOne(filter! { "name" => == "Charlie" }),
];

let affected = users.bulk_write(ops)?;

Database Management

List Collections

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

Database Stats

let stats = db.stats();
println!("Pages: {}", stats.page_count);
println!("Free pages: {}", stats.free_pages);
println!("Collections: {}", stats.collection_count);
println!("File size: {} bytes", stats.file_size);

Drop Collection

db.drop_collection("old_data")?;