noxu_db/
lib.rs

1// Copyright (C) 2024-2025 Greg Burd.  Licensed under either of the
2// Apache License, Version 2.0 or the MIT license, at your option.
3// See LICENSE-APACHE and LICENSE-MIT at the root of this repository.
4// SPDX-License-Identifier: Apache-2.0 OR MIT
5
6#![allow(
7    dead_code,
8    unused_macros,
9    unused_imports,
10    clippy::type_complexity,
11    clippy::too_many_arguments
12)]
13//! > **Internal component of the [`noxu`](https://crates.io/crates/noxu) database.**
14//! >
15//! > This crate is published only so the `noxu` umbrella crate can depend on it.
16//! > Use `noxu` (`noxu = "3"`) in applications; depend on this crate directly only
17//! > if you are extending the engine internals. Its API may change without a major
18//! > version bump.
19//!
20//! Noxu DB - An embedded transactional database engine.
21//!
22//! Public API : Environment, Database,
23//! Cursor, Transaction, DatabaseEntry, SecondaryDatabase, Sequence, etc.
24//!
25//! This crate provides the public API for Noxu DB.
26//! It is designed to be familiar to embedded database users while being
27//! idiomatic Rust.
28//!
29//! # Example
30//!
31//! ```no_run
32//! use noxu_db::{EnvironmentConfig, DatabaseConfig};
33//! use std::path::PathBuf;
34//!
35//! let env_config = EnvironmentConfig::new(PathBuf::from("/tmp/mydb"))
36//!     .with_allow_create(true)
37//!     .with_transactional(true);
38//!
39//! let db_config = DatabaseConfig::new()
40//!     .with_allow_create(true)
41//!     .with_transactional(true);
42//! ```
43
44#[macro_use]
45mod observe;
46pub mod unimplemented_params;
47
48/// Re-export of the observability crate when the `observability` feature is enabled.
49/// Users can access `noxu_db::observe_crate::{metrics, tracing}` for their own
50/// recorder/subscriber setup.
51#[cfg(feature = "observability")]
52pub use noxu_observe as observe_crate;
53
54/// Re-export of the synchronization primitive that appears in this crate's
55/// public API.  `SecondaryDatabase::open` takes the primary database wrapped
56/// in `Arc<Mutex<Database>>`; this re-export lets callers name that `Mutex`
57/// (and its guard) without depending on the internal `noxu-sync` crate
58/// directly — reachable as `noxu::Mutex` through the umbrella.
59pub use noxu_sync::{Mutex, MutexGuard};
60
61/// Re-exports of `noxu-dbi` types that appear in public API signatures.
62///
63/// `Environment::set_replica_coordinator` takes a
64/// `SharedReplicaAckCoordinator`; users implementing a custom
65/// `ReplicaAckCoordinator` for testing need `ReplicaAckCoordinator` and
66/// `AckWaitError`/`AckWaitErrorKind` without depending on the internal
67/// `noxu-dbi` crate directly.  All are reachable as `noxu::Type` through
68/// the umbrella crate.
69///
70/// Closes re-audit JE F-6 and the partial fix noted in reaudit-jonhoo #3.
71pub use noxu_dbi::{
72    AckWaitError, AckWaitErrorKind, ReplicaAckCoordinator,
73    ReplicaAckPolicyKind, SharedReplicaAckCoordinator,
74};
75
76/// Re-exports of `noxu-recovery` types that appear in public API signatures.
77///
78/// `Environment::recovered_prepared_txns` returns `Vec<PreparedTxnInfo>`;
79/// `Environment::take_recovered_prepared_lns` returns
80/// `Vec<PreparedLnReplay>`, and `apply_recovered_prepared_lns` takes
81/// `&[PreparedLnReplay]`.  XA users need these types to name return values
82/// without depending on the internal `noxu-recovery` crate directly.
83///
84/// Closes reaudit-jonhoo #3.
85pub use noxu_recovery::{
86    PreparedLnOperation, PreparedLnReplay, PreparedTxnInfo,
87};
88
89pub mod cache_mode;
90pub mod checkpoint_config;
91pub mod cursor;
92pub mod cursor_config;
93pub mod database;
94pub mod database_config;
95pub mod database_entry;
96pub mod database_stats;
97pub mod db_iter;
98pub mod disk_ordered_cursor;
99pub mod durability;
100pub mod environment;
101pub mod environment_config;
102pub mod environment_mutable_config;
103pub mod error;
104pub mod extinction_filter;
105pub mod get;
106pub mod join_config;
107pub mod join_cursor;
108pub mod lock_mode;
109pub mod operation_result;
110pub mod operation_status;
111pub mod preload;
112pub mod put;
113pub mod read_options;
114pub mod scan_filter;
115pub mod secondary_config;
116pub mod secondary_cursor;
117pub mod secondary_database;
118pub mod sequence;
119pub mod sequence_config;
120pub mod sequence_stats;
121pub mod stats_config;
122pub mod transaction;
123pub mod transaction_config;
124pub mod write_options;
125
126// Re-export commonly used types
127pub use cache_mode::CacheMode;
128pub use checkpoint_config::CheckpointConfig;
129pub use cursor::Cursor;
130pub use cursor_config::CursorConfig;
131pub use database::Database;
132pub use database_config::DatabaseConfig;
133pub use database_entry::DatabaseEntry;
134pub use database_stats::{BtreeStats, DatabaseStats};
135pub use db_iter::{DbIter, DbRange};
136pub use disk_ordered_cursor::{
137    DiskOrderedCursor, DiskOrderedCursorConfig, open_disk_ordered_cursor_multi,
138};
139pub use durability::{Durability, ReplicaAckPolicy, SyncPolicy};
140pub use environment::Environment;
141pub use environment_config::{EnvironmentConfig, ExceptionListenerHolder};
142pub use environment_mutable_config::EnvironmentMutableConfig;
143pub use error::{
144    EnvironmentFailureReason, ExceptionEvent, ExceptionListener,
145    ExceptionSource, NoxuError, Result,
146};
147pub use extinction_filter::{ExtinctionFilter, ExtinctionStatus};
148pub use get::Get;
149pub use join_config::JoinConfig;
150pub use join_cursor::JoinCursor;
151pub use lock_mode::LockMode;
152pub use noxu_engine::{
153    EnvironmentStats, VerifyConfig, VerifyError, VerifyResult,
154};
155pub use operation_result::OperationResult;
156pub use operation_status::OperationStatus;
157pub use preload::{PreloadConfig, PreloadStats};
158pub use put::Put;
159pub use read_options::ReadOptions;
160pub use scan_filter::{ScanFilter, ScanResult};
161pub use secondary_config::{
162    ForeignKeyDeleteAction, ForeignKeyNullifier, ForeignMultiKeyNullifier,
163    SecondaryConfig, SecondaryKeyCreator, SecondaryMultiKeyCreator,
164};
165pub use secondary_cursor::SecondaryCursor;
166pub use secondary_database::SecondaryDatabase;
167pub use sequence::Sequence;
168pub use sequence_config::SequenceConfig;
169pub use sequence_stats::SequenceStats;
170pub use stats_config::StatsConfig;
171pub use transaction::Transaction;
172pub use transaction_config::TransactionConfig;
173pub use write_options::WriteOptions;
noxu_db/lib.rs

noxu_db/
lib.rs
