Database

Core database operations for jasonisnthappy

The Database struct is the main entry point for interacting with jasonisnthappy. It manages connections, transactions, collections, and metadata.

Opening a database

Database::open

Open a database at the specified path with default options.

pub fn open(path: &str) -> Result<Database>

path · &str · required

Path to the database file

Returns: Result<Database> - The opened database instance

Example:

use jasonisnthappy::Database;

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

---

Database::open_with_options

Open a database with custom configuration options.

pub fn open_with_options(path: &str, opts: DatabaseOptions) -> Result<Database>

path · &str · required

Path to the database file

opts · DatabaseOptions · required

Configuration options for the database

Example:

use jasonisnthappy::{Database, DatabaseOptions};

let opts = DatabaseOptions {
    cache_size: 50_000,
    auto_checkpoint_threshold: 2000,
    read_only: false,
    max_bulk_operations: 100_000,
    max_document_size: 67_108_864,
    ..Default::default()
};

let db = Database::open_with_options("my.db", opts)?;

DatabaseOptions

Configuration options for opening a database.

cache_size · usize · default: "25,000"

Number of pages to cache in memory (1 page = ~4KB)

auto_checkpoint_threshold · u64 · default: "1,000"

Automatically checkpoint when WAL reaches this many frames

file_permissions · u32 · default: "0o644"

Unix file permissions for database files (Unix only)

read_only · bool · default: "false"

Open database in read-only mode

max_bulk_operations · usize · default: "100,000"

Maximum number of documents in bulk operations

max_document_size · usize · default: "67,108,864"

Maximum size of a single document in bytes (64MB)

max_request_body_size · usize · default: "52,428,800"

Maximum HTTP request body size for web server (50MB)

Collection operations

collection

Get a handle to a collection.

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

name · &str · required

Name of the collection

Returns: Collection - A collection handle

Example:

let users = db.collection("users");
users.insert(json!({"name": "Alice", "age": 30}))?;

---

list_collections

List all collections in the database.

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

Returns: Result<Vec<String>> - Sorted list of collection names

Example:

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

---

collection_stats

Get detailed statistics for a specific collection.

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

name · &str · required

Name of the collection

Returns: Result<CollectionInfo> - Collection statistics

Example:

let stats = db.collection_stats("users")?;
println!("Documents: {}", stats.document_count);
println!("Indexes: {}", stats.indexes.len());

Transaction management

begin

Begin a new transaction.

pub fn begin(&self) -> Result<Transaction>

Returns: Result<Transaction> - A new transaction

Example:

let mut tx = db.begin()?;
let mut users = tx.collection("users")?;
// Perform operations...
tx.commit()?;

---

run_transaction

Execute a function within a transaction with automatic retry on conflicts.

pub fn run_transaction<F, R>(&self, f: F) -> Result<R>
where
    F: Fn(&mut Transaction) -> Result<R>

f · Fn(&mut Transaction) -> Result<R> · required

Function to execute within the transaction

Returns: Result<R> - The result from the transaction function

Example:

let result = db.run_transaction(|tx| {
    let mut users = tx.collection("users")?;
    users.insert(json!({"name": "Bob", "age": 25}))?;
    Ok(())
})?;

Index management

create_index

Create a single-field index on a collection.

pub fn create_index(
    &self,
    collection_name: &str,
    index_name: &str,
    field: &str,
    unique: bool
) -> Result<()>

collection_name · &str · required

Name of the collection

index_name · &str · required

Name for the index

field · &str · required

Field to index

unique · bool · required

Whether to enforce uniqueness

Example:

db.create_index("users", "email_idx", "email", true)?;

---

create_compound_index

Create a compound index on multiple fields.

pub fn create_compound_index(
    &self,
    collection_name: &str,
    index_name: &str,
    fields: &[&str],
    unique: bool
) -> Result<()>

collection_name · &str · required

Name of the collection

index_name · &str · required

Name for the index

fields · &[&str] · required

Ordered list of fields to include in the compound index

unique · bool · required

Whether to enforce uniqueness on the combination of field values

Example:

db.create_compound_index("users", "city_age_idx", &["city", "age"], false)?;

---

create_text_index

Create a text index for full-text search.

pub fn create_text_index(
    &self,
    collection_name: &str,
    index_name: &str,
    fields: &[&str]
) -> Result<()>

collection_name · &str · required

Name of the collection

index_name · &str · required

Name for the text index

fields · &[&str] · required

List of text fields to index for search

Example:

db.create_text_index("posts", "search_idx", &["title", "body"])?;

---

drop_index

Drop an index from a collection.

pub fn drop_index(&self, collection_name: &str, index_name: &str) -> Result<()>

collection_name · &str · required

Name of the collection

index_name · &str · required

Name of the index to drop

Example:

db.drop_index("users", "email_idx")?;

---

list_indexes

List all indexes for a specific collection.

pub fn list_indexes(&self, collection_name: &str) -> Result<Vec<IndexInfo>>

collection_name · &str · required

Name of the collection

Returns: Result<Vec<IndexInfo>> - List of index information

Schema validation

set_schema

Set a validation schema for a collection.

pub fn set_schema(&self, collection_name: &str, schema: Schema) -> Result<()>

collection_name · &str · required

Name of the collection

schema · Schema · required

The schema to apply

Example:

use jasonisnthappy::{Schema, ValueType};
use std::collections::HashMap;

let mut schema = Schema::new();
schema.value_type = Some(ValueType::Object);
schema.required = Some(vec!["name".to_string(), "email".to_string()]);

let mut properties = HashMap::new();
let mut name_schema = Schema::new();
name_schema.value_type = Some(ValueType::String);
name_schema.min_length = Some(1);
properties.insert("name".to_string(), name_schema);

schema.properties = Some(properties);
db.set_schema("users", schema)?;

---

get_schema

Get the validation schema for a collection.

pub fn get_schema(&self, collection_name: &str) -> Option<Schema>

collection_name · &str · required

Name of the collection

Returns: Option<Schema> - The schema if set, or None

---

remove_schema

Remove the validation schema from a collection.

pub fn remove_schema(&self, collection_name: &str) -> Result<()>

collection_name · &str · required

Name of the collection

Database maintenance

checkpoint

Manually trigger a WAL checkpoint.

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

Example:

db.checkpoint()?;

---

garbage_collect

Remove old document versions that are no longer needed.

pub fn garbage_collect(&self) -> Result<GarbageCollectionStats>

Returns: Result<GarbageCollectionStats> - Statistics about the garbage collection

Example:

let stats = db.garbage_collect()?;
println!("Freed {} pages", stats.pages_freed);

---

backup

Create a backup of the database.

pub fn backup(&self, dest_path: &str) -> Result<()>

dest_path · &str · required

Destination path for the backup file

Example:

db.backup("./backups/mydb-2024-01-15.db")?;

---

verify_backup

Verify a backup file by checking its integrity.

pub fn verify_backup(backup_path: &str) -> Result<BackupInfo>

backup_path · &str · required

Path to the backup file to verify

Returns: Result<BackupInfo> - Backup information if valid

Example:

let info = Database::verify_backup("./backups/mydb.db")?;
println!("Backup has {} collections", info.num_collections);

---

close

Close the database connection.

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

Example:

db.close()?;

Database information

info

Get comprehensive database information.

pub fn info(&self) -> Result<DatabaseInfo>

Returns: Result<DatabaseInfo> - Detailed database statistics

Example:

let info = db.info()?;
println!("Database: {}", info.path);
println!("Collections: {}", info.collections.len());
println!("Total documents: {}", info.total_documents);

---

metrics

Get a snapshot of current database metrics.

pub fn metrics(&self) -> MetricsSnapshot

Returns: MetricsSnapshot - Current metrics

Example:

let metrics = db.metrics();
println!("Page reads: {}", metrics.page_reads);
println!("Page writes: {}", metrics.page_writes);

---

path

Get the database file path.

pub fn path(&self) -> &str

Returns: &str - The database file path

---

is_read_only

Check if the database is in read-only mode.

pub fn is_read_only(&self) -> bool

Returns: bool - true if read-only, false otherwise

Configuration

set_transaction_config

Set transaction retry configuration.

pub fn set_transaction_config(&self, config: TransactionConfig)

config · TransactionConfig · required

Transaction configuration

Example:

use jasonisnthappy::database::TransactionConfig;

let config = TransactionConfig {
    max_retries: 5,
    retry_backoff_base_ms: 2,
    max_retry_backoff_ms: 200,
};
db.set_transaction_config(config);

---

set_auto_checkpoint_threshold

Set the auto-checkpoint threshold.

pub fn set_auto_checkpoint_threshold(&self, threshold: u64)

threshold · u64 · required

Number of WAL frames before auto-checkpoint

Example:

db.set_auto_checkpoint_threshold(2000);