noxu/
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//! # Noxu DB — umbrella crate
7//!
8//! **`noxu`** is the single crate users depend on to get the full
9//! Noxu DB engine.  It re-exports the public API of all component crates
10//! behind a single name and version so you write only:
11//!
12//! ```toml
13//! [dependencies]
14//! noxu = "3"
15//! ```
16//!
17//! ## Quick-start
18//!
19//! ```no_run
20//! use noxu::{DatabaseConfig, DatabaseEntry, Environment, EnvironmentConfig};
21//! use std::path::PathBuf;
22//!
23//! # fn main() -> noxu::Result<()> {
24//! let env = Environment::open(
25//!     EnvironmentConfig::new(PathBuf::from("/tmp/mydb"))
26//!         .with_allow_create(true)
27//!         .with_transactional(true),
28//! )?;
29//! let db_config = DatabaseConfig::new()
30//!     .with_allow_create(true)
31//!     .with_transactional(true);
32//! let db = env.open_database(None, "kv", &db_config)?;
33//! let txn = env.begin_transaction(None)?;
34//! db.put(
35//!     Some(&txn),
36//!     &DatabaseEntry::from_bytes(b"hello"),
37//!     &DatabaseEntry::from_bytes(b"world"),
38//! )?;
39//! txn.commit()?;
40//! # Ok(())
41//! # }
42//! ```
43//!
44//! ## Feature flags
45//!
46//! | Feature | Default | What it enables |
47//! |---|---|---|
48//! | `collections` | yes | [`collections`] module — `StoredMap`, `StoredSet`, `StoredList` |
49//! | `persist` | yes | [`persist`] module — `#[derive(Entity)]`, `PrimaryIndex`, `EntityStore` |
50//! | `xa` | yes | [`xa`] module — XA two-phase-commit (`XaEnvironment`) |
51//! | `replication` | no | `replication` module — master-replica HA, elections |
52//! | `replication-tls-rustls` | no | TLS for replication via pure-Rust `rustls` |
53//! | `replication-tls-native` | no | TLS for replication via OS/OpenSSL |
54//! | `observability` | no | `observe` module — `tracing` + `metrics` glue |
55//!
56//! ## Derive macros
57//!
58//! With the `persist` feature (on by default) the derive macros
59//! `Entity`, `PrimaryKey`, and `SecondaryKey` are available directly
60//! through this crate:
61//!
62//! ```no_run
63//! use noxu::persist::{Entity, SecondaryKey};
64//!
65//! #[derive(Clone, Entity, SecondaryKey)]
66//! struct User {
67//!     #[primary_key]
68//!     id: u64,
69//!     #[secondary_key(name = "by_email", relate = OneToOne)]
70//!     email: String,
71//! }
72//! ```
73
74// Re-export the entire core public API at the crate root.
75pub use noxu_db::*;
76
77/// Binding helpers: tuple encoding, entry views, serial encoding.
78pub mod bind {
79    pub use noxu_bind::*;
80}
81
82/// Iterator-based collection views (`StoredMap`, `StoredSet`, `StoredList`).
83#[cfg(feature = "collections")]
84pub mod collections {
85    pub use noxu_collections::*;
86}
87
88/// Trait-based entity persistence (DPL): `Entity`, `PrimaryKey`,
89/// `PrimaryIndex`, `EntityStore`, and the derive macros.
90///
91/// The derive macros (`#[derive(Entity)]`, `#[derive(PrimaryKey)]`,
92/// `#[derive(SecondaryKey)]`) are re-exported here so that the generated
93/// code — which references `::noxu::persist::…` paths — resolves
94/// correctly when the user only depends on the `noxu` umbrella crate.
95#[cfg(feature = "persist")]
96pub mod persist {
97    pub use noxu_persist::*;
98    // Re-export the derive macros so `use noxu::persist::Entity;` brings
99    // both the trait AND the derive macro into scope.
100    pub use noxu_persist_derive::{Entity, PrimaryKey, SecondaryKey};
101}
102
103/// XA distributed transactions (X/Open XA two-phase commit).
104#[cfg(feature = "xa")]
105pub mod xa {
106    pub use noxu_xa::*;
107}
108
109/// Master-replica high-availability replication.
110#[cfg(feature = "replication")]
111pub mod replication {
112    pub use noxu_rep::*;
113}
114
115/// Optional observability integration (`tracing` + `metrics` + OpenTelemetry).
116#[cfg(feature = "observability")]
117pub mod observe {
118    pub use noxu_observe::*;
119}
noxu/lib.rs

noxu/
lib.rs
