rust-kgdb 0.1.10 → 0.1.12

package/README.md

@@ -108,7 +108,7 @@ rust-kgdb uses a pluggable storage architecture. **Default is in-memory** (zero
 |---------|--------------|----------|--------|
 | **InMemory** | `default` | Development, testing, embedded | ✅ **Production Ready** |
 | **RocksDB** | `rocksdb-backend` | Production, large datasets | ✅ **61 tests passing** |
-| **LMDB** | `lmdb-backend` | Read-heavy workloads | ⏳ Planned v0.2.0 |
+| **LMDB** | `lmdb-backend` | Read-heavy workloads | ✅ **31 tests passing** |
 
 ### InMemory (Default)
 
@@ -176,6 +176,58 @@ store.flush()?;
 - Unicode & binary data (4 tests)
 - Large key/value handling (8 tests)
 
+### LMDB (Memory-Mapped Persistent)
+
+B+tree based storage with memory-mapped I/O (via `heed` crate). Optimized for **read-heavy workloads** with MVCC (Multi-Version Concurrency Control). Tested with **31 comprehensive tests**.
+
+```toml
+# Cargo.toml - Enable LMDB backend
+[dependencies]
+storage = { version = "0.1.12", features = ["lmdb-backend"] }
+```
+
+```rust
+use storage::{QuadStore, LmdbBackend};
+
+// Create persistent database (default 10GB map size)
+let backend = LmdbBackend::new("/path/to/data")?;
+let store = QuadStore::new(backend);
+
+// Or with custom map size (1GB)
+let backend = LmdbBackend::with_map_size("/path/to/data", 1024 * 1024 * 1024)?;
+
+// Features:
+// - Memory-mapped I/O (zero-copy reads)
+// - MVCC for concurrent readers
+// - Crash-safe ACID transactions
+// - Range & prefix scanning
+// - Excellent for read-heavy workloads
+
+// Sync to disk
+store.flush()?;
+```
+
+**When to use LMDB vs RocksDB:**
+
+| Characteristic | LMDB | RocksDB |
+|----------------|------|---------|
+| **Read Performance** | ✅ Faster (memory-mapped) | Good |
+| **Write Performance** | Good | ✅ Faster (LSM-tree) |
+| **Concurrent Readers** | ✅ Unlimited | Limited by locks |
+| **Write Amplification** | Low | Higher (compaction) |
+| **Memory Usage** | Higher (map size) | Lower (cache-based) |
+| **Best For** | Read-heavy, OLAP | Write-heavy, OLTP |
+
+**LMDB Test Coverage:**
+- Basic CRUD operations (8 tests)
+- Range scanning (4 tests)
+- Prefix scanning (3 tests)
+- Batch operations (3 tests)
+- Large key/value handling (4 tests)
+- Concurrent access (4 tests)
+- Statistics & flush (3 tests)
+- Edge cases (2 tests)
+
 ### TypeScript SDK
 
 The npm package uses the in-memory backend—ideal for:
@@ -380,6 +432,60 @@ db.updateDelete(`
 
 ---
 
+## Sample Application
+
+### Knowledge Graph Demo
+
+A complete, production-ready sample application demonstrating enterprise knowledge graph capabilities is available in the repository.
+
+**Location**: [`examples/knowledge-graph-demo/`](../../examples/knowledge-graph-demo/)
+
+**Features Demonstrated**:
+- Complete organizational knowledge graph (employees, departments, projects, skills)
+- SPARQL SELECT queries with star and chain patterns (WCOJ-optimized)
+- Aggregations (COUNT, AVG, GROUP BY, HAVING)
+- Property paths for transitive closure (organizational hierarchy)
+- SPARQL ASK and CONSTRUCT queries
+- Named graphs for multi-tenant data isolation
+- Data export to Turtle format
+
+**Run the Demo**:
+
+```bash
+cd examples/knowledge-graph-demo
+npm install
+npm start
+```
+
+**Sample Output**:
+
+The demo creates a realistic knowledge graph with:
+- 5 employees across 4 departments
+- 13 technical and soft skills
+- 2 software projects
+- Reporting hierarchies and salary data
+- Named graph for sensitive compensation data
+
+**Example Query from Demo** (finds all direct and indirect reports):
+
+```typescript
+const pathQuery = `
+  PREFIX ex: <http://example.org/>
+  PREFIX foaf: <http://xmlns.com/foaf/0.1/>
+
+  SELECT ?employee ?name WHERE {
+    ?employee ex:reportsTo+ ex:alice .  # Transitive closure
+    ?employee foaf:name ?name .
+  }
+  ORDER BY ?name
+`
+const results = db.querySelect(pathQuery)
+```
+
+**Learn More**: See the [demo README](../../examples/knowledge-graph-demo/README.md) for full documentation, query examples, and how to customize the knowledge graph.
+
+---
+
 ## API Reference
 
 ### GraphDB Class
@@ -455,6 +561,14 @@ Total: ~120 bytes/triple including indexes
 
 ## Version History
 
+### v0.1.12 (2025-12-01) - LMDB Backend Release
+
+- **LMDB storage backend** fully implemented (31 tests passing)
+- Memory-mapped I/O for optimal read performance
+- MVCC concurrency for unlimited concurrent readers
+- Complete LMDB vs RocksDB comparison documentation
+- Sample application with 87 triples demonstrating all features
+
 ### v0.1.9 (2025-12-01) - SIMD + PGO Release
 
 - **44.5% average speedup** via SIMD + PGO compiler optimizations

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rust-kgdb",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "High-performance RDF/SPARQL database with 100% W3C compliance and WCOJ execution",
   "main": "index.js",
   "types": "index.d.ts",
@@ -21,7 +21,7 @@
     "build:debug": "napi build --platform native/rust-kgdb-napi",
     "prepublishOnly": "napi prepublish -t npm",
     "test": "jest",
-    "version": "0.1.10"
+    "version": "0.1.12"
   },
   "keywords": [
     "rdf",
@@ -56,10 +56,10 @@
     "*.node"
   ],
   "optionalDependencies": {
-    "rust-kgdb-win32-x64-msvc": "0.1.10",
-    "rust-kgdb-darwin-x64": "0.1.10",
-    "rust-kgdb-linux-x64-gnu": "0.1.10",
-    "rust-kgdb-darwin-arm64": "0.1.10",
-    "rust-kgdb-linux-arm64-gnu": "0.1.10"
+    "rust-kgdb-win32-x64-msvc": "0.1.12",
+    "rust-kgdb-darwin-x64": "0.1.12",
+    "rust-kgdb-linux-x64-gnu": "0.1.12",
+    "rust-kgdb-darwin-arm64": "0.1.12",
+    "rust-kgdb-linux-arm64-gnu": "0.1.12"
   }
 }