Crate noxu

Expand description

§Noxu DB — umbrella crate

noxu is the single crate users depend on to get the full Noxu DB engine. It re-exports the public API of all component crates behind a single name and version so you write only:

[dependencies]
noxu = "3"

§Quick-start

use noxu::{DatabaseConfig, DatabaseEntry, Environment, EnvironmentConfig};
use std::path::PathBuf;

let env = Environment::open(
    EnvironmentConfig::new(PathBuf::from("/tmp/mydb"))
        .with_allow_create(true)
        .with_transactional(true),
)?;
let db_config = DatabaseConfig::new()
    .with_allow_create(true)
    .with_transactional(true);
let db = env.open_database(None, "kv", &db_config)?;
let txn = env.begin_transaction(None)?;
db.put(
    Some(&txn),
    &DatabaseEntry::from_bytes(b"hello"),
    &DatabaseEntry::from_bytes(b"world"),
)?;
txn.commit()?;

§Feature flags

Feature	Default	What it enables
`collections`	yes	`collections` module — `StoredMap`, `StoredSet`, `StoredList`
`persist`	yes	`persist` module — `#[derive(Entity)]`, `PrimaryIndex`, `EntityStore`
`xa`	yes	`xa` module — XA two-phase-commit (`XaEnvironment`)
`replication`	no	`replication` module — master-replica HA, elections
`replication-tls-rustls`	no	TLS for replication via pure-Rust `rustls`
`replication-tls-native`	no	TLS for replication via OS/OpenSSL
`observability`	no	`observe` module — `tracing` + `metrics` glue

§Derive macros

With the persist feature (on by default) the derive macros Entity, PrimaryKey, and SecondaryKey are available directly through this crate:

use noxu::persist::{Entity, SecondaryKey};

#[derive(Clone, Entity, SecondaryKey)]
struct User {
    #[primary_key]
    id: u64,
    #[secondary_key(name = "by_email", relate = OneToOne)]
    email: String,
}

Modules§

bind: Binding helpers: tuple encoding, entry views, serial encoding.
cache_mode: Cache modes for database operations.
checkpoint_config: Configuration for manual checkpoint operations.
collections: Iterator-based collection views (StoredMap, StoredSet, StoredList).
cursor: Cursor handle for Noxu DB.
cursor_config: Cursor configuration.
database: Database handle.
database_config: Database configuration.
database_entry: Database entry for keys and data.
database_stats: Per-database statistics.
db_iter: Lazy iterator adapters for crate::Database.
disk_ordered_cursor: Disk-ordered cursor for high-throughput unordered scans.
durability: Durability and sync policies for transactions.
environment: Environment handle.
environment_config: Environment configuration.
environment_mutable_config: Runtime-mutable environment configuration.
error: Error types for Noxu DB.
extinction_filter: Filter interface for identifying extinct records.
get: Get operation types.
join_config: Configuration for JoinCursor.
join_cursor: Join cursor for multi-secondary-index intersection queries.
lock_mode: Lock modes for read operations.
observe: Optional observability integration (tracing + metrics + OpenTelemetry).
observe_crate: Internal component of the noxu database.This crate is published only so the noxu umbrella crate can depend on it. Use noxu (noxu = "3") in applications; depend on this crate directly only if you are extending the engine internals. Its API may change without a major version bump.
operation_result: Result of database operations.
operation_status: Operation status for database operations.
persist: Trait-based entity persistence (DPL): Entity, PrimaryKey, PrimaryIndex, EntityStore, and the derive macros.
preload: Database preloading configuration and statistics.
put: Put operation types.
read_options: Read operation options.
replication: Master-replica high-availability replication.
scan_filter: Filter interface for sequential database scans.
secondary_config: Secondary database configuration.
secondary_cursor: Secondary cursor for iterating a secondary (index) database.
secondary_database: Secondary database handle.
sequence: Sequence handle.
sequence_config: Sequence configuration.
sequence_stats: Sequence statistics.
stats_config: Configuration for statistics retrieval operations.
transaction: Transaction handle for Noxu DB.
transaction_config: Transaction configuration.
unimplemented_params: Registry of EnvironmentConfig parameters that are accepted but not yet implemented.
write_options: Write operation options.
xa: XA distributed transactions (X/Open XA two-phase commit).

Structs§

AckWaitError: Error returned by ReplicaAckCoordinator::await_replica_acks when the configured number of replica acks could not be obtained within the supplied timeout.
BtreeStats: B-tree statistics for a single database.
CheckpointConfig: Specifies the attributes of a checkpoint operation invoked via Environment::checkpoint.
Cursor: A database cursor for iterating over records.
CursorConfig: Configuration for opening a cursor.
Database: A database handle.
DatabaseConfig: Configuration for opening a database.
DatabaseEntry: Encodes database key and data items as byte arrays.
DatabaseStats: Base statistics type for a database.
DbIter: A forward-scanning iterator over all records in a database.
DbRange: A lazy key-range iterator over a database.
DiskOrderedCursor: A cursor that returns records in on-disk order rather than key order.
DiskOrderedCursorConfig: Configuration for a DiskOrderedCursor.
Durability: Durability characteristics for a transaction.
Environment: A database environment.
EnvironmentConfig: Configuration for opening a Noxu DB environment.
EnvironmentMutableConfig: The subset of environment properties that can be changed after the environment has been opened.
EnvironmentStats: Aggregated statistics for the environment.
ExceptionEvent: An exception event delivered to an ExceptionListener.
ExceptionListenerHolder: Wrapper around an optional ExceptionListener that implements Debug and Clone so that EnvironmentConfig can keep those derives.
JoinConfig: Configuration properties for a JoinCursor.
JoinCursor: A cursor that returns records satisfying all secondary-key constraints.
OperationResult: Result of a successful database operation.
PreloadConfig: Configuration for database preloading.
PreloadStats: Statistics returned from a database preload operation.
PreparedLnReplay: A single LN entry queued for replay when a recovered prepared transaction is committed via xa_commit(xid).
PreparedTxnInfo: Information about a transaction that was found prepared (XA phase 1 completed) but not yet committed or rolled back.
ReadOptions: Options for read operations.
SecondaryConfig: Configuration for a secondary database.
SecondaryCursor: A cursor that iterates a secondary index database.
SecondaryDatabase: A secondary (index) database handle.
Sequence: A handle for manipulating a sequence record stored in a Database.
SequenceConfig: Specifies the attributes of a sequence.
SequenceStats: Statistics for a Sequence handle.
StatsConfig: Specifies the attributes of a statistics retrieval operation.
Transaction: A transaction handle.
TransactionConfig: Configuration for transactions.
VerifyConfig: Configuration for verification.
VerifyResult: Result of an environment verification.
WriteOptions: Options for write operations.

Enums§

AckWaitErrorKind: Reason an ack-wait did not satisfy the durability contract.
CacheMode: Cache mode for database operations.
EnvironmentFailureReason: Distinguishes the root cause of an EnvironmentFailure.
ExceptionSource: The source subsystem that raised an exception event.
ExtinctionStatus: Classification returned by ExtinctionFilter::get_extinction_status.
ForeignKeyDeleteAction: Action taken when a record in a foreign key database is deleted.
Get: Type of get operation for cursors and databases.
LockMode: Lock mode for read operations.
NoxuError: Errors that can occur when using Noxu DB.
OperationStatus: Operation status returned by database and cursor operations.
PreparedLnOperation: LN operation type for a prepared-txn replay record.
Put: Type of put operation for cursors and databases.
ReplicaAckPolicy: Acknowledgment policy for replicated environments.
ReplicaAckPolicyKind: Replica acknowledgment policy as visible to the durability path.
ScanResult: Result returned by ScanFilter::check_key to control scan inclusion and termination.
SyncPolicy: Sync policy for local commit synchronization.
VerifyError: Types of verification errors.

Traits§

ExceptionListener: Callback interface for exceptions thrown in background daemon threads.
ExtinctionFilter: Callback for classifying records as extinct.
ForeignKeyNullifier: Callback trait for nullifying a single foreign key reference in primary data.
ForeignMultiKeyNullifier: Callback trait for nullifying multi-valued foreign key references.
ReplicaAckCoordinator: Coordinates with a replication subsystem to satisfy a replica-ack policy on commit.
ScanFilter: Interface for filtering and optionally stopping a sequential scan.
SecondaryKeyCreator: Callback trait for creating a single secondary key from a primary record.
SecondaryMultiKeyCreator: Callback trait for creating multiple secondary keys from a primary record.

Functions§

open_disk_ordered_cursor_multi: Opens a disk-ordered cursor that scans entries from any of the given databases.

Type Aliases§

Mutex: Mutual exclusion primitive backed by a futex.
MutexGuard: RAII guard returned by Mutex::lock.
Result: Result type for Noxu DB operations.
SharedReplicaAckCoordinator: Type alias used in noxu-db::Environment to hold the optional installed coordinator.

Crate noxu

Crate noxu Copy item path

§Noxu DB — umbrella crate

§Quick-start

§Feature flags

§Derive macros

Modules§

Structs§

Enums§

Traits§

Functions§

Type Aliases§

Crate noxu