sochdb_core/
lib.rs

1// Copyright 2025 Sushanth (https://github.com/sushanthpy)
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//! SochDB Core
16//!
17//! TOON-native ACID database - fundamental types and data structures.
18//!
19//! SochDB is to TOON what MongoDB is to JSON - a database that natively
20//! understands and stores TOON (Tabular Object-Oriented Notation) documents.
21//!
22//! # Core Components
23//!
24//! - **TOON Format**: Native data format with schema support
25//! - **Transaction Manager**: ACID transaction support via WAL
26//! - **Virtual Filesystem**: POSIX-like VFS backed by WAL
27//! - **Schema Catalog**: Table and index metadata management
28//!
29//! # Memory Allocation
30//!
31//! **Recommended**: Enable jemalloc for production workloads:
32//!
33//! ```toml
34//! sochdb-core = { version = "...", features = ["jemalloc"] }
35//! ```
36//!
37//! jemalloc provides:
38//! - Thread-local caching (no lock contention)
39//! - Superior fragmentation handling
40//! - Automatic memory return to OS
41//! - Battle-tested in production (Firefox, Redis, RocksDB)
42//!
43//! **Note**: The `buddy_allocator` module is deprecated. See its documentation
44//! for migration guidance.
45//!
46//! # Features
47//!
48//! - `jemalloc` - Use jemalloc as the global allocator for better performance
49//!
50//! # Example
51//!
52//! ```rust,ignore
53//! use sochdb_core::soch::{SochSchema, SochType, SochTable, SochRow, SochValue};
54//!
55//! // Define a schema
56//! let schema = SochSchema::new("users")
57//!     .field("id", SochType::UInt)
58//!     .field("name", SochType::Text)
59//!     .field("email", SochType::Text)
60//!     .primary_key("id");
61//!
62//! // Create a table
63//! let mut table = SochTable::new(schema);
64//! table.push(SochRow::new(vec![
65//!     SochValue::UInt(1),
66//!     SochValue::Text("Alice".into()),
67//!     SochValue::Text("alice@example.com".into()),
68//! ]));
69//!
70//! // Format as TOON
71//! println!("{}", table.format());
72//! // Output: users[1]{id,name,email}:
73//! //         1,Alice,alice@example.com
74//! ```
75
76// Use jemalloc as global allocator when feature is enabled
77// This provides better performance for allocation-heavy workloads
78#[cfg(feature = "jemalloc")]
79#[global_allocator]
80static GLOBAL: tikv_jemallocator::Jemalloc = tikv_jemallocator::Jemalloc;
81
82pub mod block_storage;
83#[deprecated(
84    since = "0.2.0",
85    note = "Use jemalloc feature instead. See buddy_allocator module docs for migration."
86)]
87#[allow(deprecated)]
88pub mod buddy_allocator;
89pub mod catalog;
90pub mod columnar; // True Columnar Storage with Arrow-compatible layout (mm.md Task 1)
91pub mod concurrency; // Hierarchical Lock Architecture (mm.md Task 2)
92pub mod epoch_gc;
93pub mod error;
94pub mod format_migration;
95pub mod key;
96pub mod learned_index;
97pub mod lockfree_interner; // Lock-free string interner (mm.md Task 6)
98pub mod memory_schema; // Canonical Episode/Entity/Event schema
99pub mod path_trie;
100pub mod predefined_views;
101pub mod reclamation;
102pub mod schema_bridge;
103pub mod schema_evolution;
104pub mod sharded_block_store;
105pub mod string_interner; // String interning for path segments
106pub mod tbp; // TOON Binary Protocol for zero-copy wire format (mm.md Task 3.1)
107pub mod soch;
108pub mod soch_codec;
109pub mod sochfs_metadata;
110pub mod transaction_typestate; // Type-State Transaction API (compile-time safe transaction lifecycle)
111pub mod txn;
112pub mod version_chain; // Unified MVCC version chain trait
113pub mod vfs;
114pub mod zero_copy; // Predefined SochQL views (Task 7)
115
116// Analytics - anonymous usage tracking (disabled with SOCHDB_DISABLE_ANALYTICS=true)
117#[cfg(feature = "analytics")]
118pub mod analytics;
119
120// Re-export core types
121pub use block_storage::{
122    BlockCompression, BlockRef, BlockStore, BlockStoreStats, FileBlockManager,
123};
124pub use catalog::{Catalog, CatalogEntry, CatalogEntryType, McpToolDescriptor, OperationImpl};
125pub use columnar::{
126    ColumnChunk, ColumnStats, ColumnType as ColumnarColumnType, ColumnValue as ColumnarColumnValue,
127    ColumnarStore, ColumnarTable, MemoryComparison, TypedColumn, ValidityBitmap,
128};
129pub use error::{Result, SochDBError};
130pub use key::{CausalKey, TemporalKey};
131pub use learned_index::LearnedSparseIndex;
132pub use lockfree_interner::{InternerStats, LockFreeInterner, Symbol};
133pub use memory_schema::{
134    Entity, EntityFacts, EntityKind, EntitySearchResult, Episode, EpisodeSearchResult, EpisodeType,
135    Event, EventMetrics, EventRole, MemoryStore, TableRole, TableSemanticMetadata,
136};
137pub use path_trie::{ColumnGroupAffinity, ColumnType as PathTrieColumnType, PathTrie, TrieNode};
138pub use predefined_views::{
139    ViewDefinition, build_view_map, get_predefined_views, get_view, naming,
140};
141pub use soch::{SochField, SochIndex, SochRow, SochSchema, SochTable, SochType, SochValue};
142pub use soch_codec::{
143    SochDbBinaryCodec, SochDocument, SochParseError, SochTextEncoder, SochTextParser,
144    SochTokenCounter,
145};
146pub use sochfs_metadata::{DirEntryRow, FsMetadataStore, FsWalOp, InodeRow, SochFS};
147pub use txn::{
148    AriesCheckpointData, AriesDirtyPageEntry, AriesTransactionEntry, IsolationLevel, Lsn, PageId,
149    Transaction, TransactionManager, TxnId, TxnState, TxnStats, TxnWalEntry, TxnWrite,
150    WalRecordType,
151};
152pub use transaction_typestate::{
153    Transaction as TypestateTransaction, Active, Committed, Aborted,
154    ReadOnly, ReadWrite, WriteOnly, TransactionStorage, TransactionMode,
155};
156pub use version_chain::{
157    MvccVersionChain, MvccVersionChainMut, VersionMeta, VisibilityContext, WriteConflictDetection,
158};
159pub use vfs::{
160    BlockId, DirEntry, Directory, FileStat, FileType, Inode, InodeId, Permissions, Superblock,
161    VfsOp,
162};
163
164/// Database version
165pub const SOCHDB_VERSION: &str = env!("CARGO_PKG_VERSION");
166
167/// Magic bytes for SochDB files
168pub const SOCHDB_MAGIC: [u8; 4] = *b"TOON";
169
170/// Current schema version
171pub const SCHEMA_VERSION: u32 = 1;
172
173#[cfg(test)]
174mod tests {
175    use super::*;
176
177    #[test]
178    fn test_soch_roundtrip() {
179        let schema = SochSchema::new("test")
180            .field("id", SochType::UInt)
181            .field("value", SochType::Text);
182
183        let mut table = SochTable::new(schema);
184        table.push(SochRow::new(vec![
185            SochValue::UInt(1),
186            SochValue::Text("hello".into()),
187        ]));
188
189        let formatted = table.format();
190        let parsed = SochTable::parse(&formatted).unwrap();
191
192        assert_eq!(parsed.schema.name, "test");
193        assert_eq!(parsed.rows.len(), 1);
194    }
195}
sochdb_core/lib.rs

sochdb_core/
lib.rs
