{"id":28743516,"url":"https://github.com/trueai-org/ultra-kv","last_synced_at":"2025-07-12T00:05:40.044Z","repository":{"id":298640059,"uuid":"1000613803","full_name":"trueai-org/ultra-kv","owner":"trueai-org","description":"Single File Lightning-Fast Key-Value Storage Engine","archived":false,"fork":false,"pushed_at":"2025-06-12T04:45:46.000Z","size":139,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-12T05:34:45.969Z","etag":null,"topics":["keyvaluestore","litedb","single-file","sqlite","storage"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/trueai-org.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-12T04:07:36.000Z","updated_at":"2025-06-12T04:45:49.000Z","dependencies_parsed_at":"2025-06-12T05:44:59.867Z","dependency_job_id":null,"html_url":"https://github.com/trueai-org/ultra-kv","commit_stats":null,"previous_names":["trueai-org/ultra-kv"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/trueai-org/ultra-kv","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trueai-org%2Fultra-kv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trueai-org%2Fultra-kv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trueai-org%2Fultra-kv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trueai-org%2Fultra-kv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trueai-org","download_url":"https://codeload.github.com/trueai-org/ultra-kv/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trueai-org%2Fultra-kv/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260139230,"owners_count":22964700,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["keyvaluestore","litedb","single-file","sqlite","storage"],"created_at":"2025-06-16T10:07:13.871Z","updated_at":"2025-07-12T00:05:40.018Z","avatar_url":"https://github.com/trueai-org.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🚀 UltraKV - Lightning-Fast Key-Value Storage Engine\n\n\u003cdiv align=\"center\"\u003e\n\n[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://choosealicense.com/licenses/mit/)\n[![.NET 8.0](https://img.shields.io/badge/.NET-8.0-purple.svg)](https://dotnet.microsoft.com/download/dotnet/8.0)\n[![C#](https://img.shields.io/badge/Language-C%23-blue.svg)](https://docs.microsoft.com/en-us/dotnet/csharp/)\n[![Performance](https://img.shields.io/badge/Performance-⚡%20Lightning%20Fast-red.svg)](#performance-benchmarks)\n\n**An ultra-high performance, enterprise-grade key-value storage solution designed for the .NET ecosystem**\n\n[English](README.md) | [中文文档](README_CN.md)\n\n\u003c/div\u003e\n\n## 🎯 Minimal Code, Maximum Performance\n\n\u003cdiv align=\"center\"\u003e\n\n### **🚀 Less than 1,000 Lines of Code for a Complete Database Engine**\n\n*Proving that simplicity and performance can coexist*\n\n\u003c/div\u003e\n\nOne of the most remarkable aspects of **UltraKV** is achieving enterprise-grade database performance with an incredibly compact codebase. The entire **UltraKV** engine core is implemented in **less than 1,000 lines of C# code**, demonstrating the power of focused, efficient design. Database initializing only requires **64 bytes**.\n\n### 💡 Philosophy: \"Perfect is the Enemy of Good\"\n\nUltraKV proves that:\n- **Less code = Less bugs**\n- **Simple design = Better performance**\n- **Focused scope = Reliable execution**\n- **Clear logic = Easy maintenance**\n\n\u003e *\"The best code is no code at all. The second best is code so simple and efficient that it feels like no code.\"*\n\n\n## Installation\n\n[More Document / WIKI](https://github.com/trueai-org/ultra-kv/wiki)\n\n```bash\ndotnet add package UltraKV\n\nusing var engine = new UltraKVEngine\u003cstring, string\u003e(\"test.db\");\nengine.Set(\"key1\", \"value1\");\nvar value = engine.Get(\"key1\");\nengine.Remove(\"key1\");\nengine.Flush();\n```\n\n## 📋 Table of Contents\n\n- [🌟 Project Overview](#-project-overview)\n- [🔥 Key Features](#-key-features)\n- [⚡ Performance Benchmarks](#-performance-benchmarks)\n- [🏗️ Architecture Design](#️-architecture-design)\n- [🚀 Quick Start](#-quick-start)\n- [📖 Detailed Usage Guide](#-detailed-usage-guide)\n- [🔧 Advanced Configuration](#-advanced-configuration)\n- [📊 Performance Testing](#-performance-testing)\n- [🔐 Security Features](#-security-features)\n- [🛠️ Best Practices](#️-best-practices)\n- [🤝 Contributing](#-contributing)\n- [📄 License](#-license)\n\n## 🌟 Project Overview\n\n**UltraKV** is a modern, single file, high-performance key-value storage system.\n\n### 🎯 Design Goals\n\n- **🚀 Extreme Performance**: Supporting millions of ops/sec for read/write operations per instance\n- **🔒 Data Security**: Enterprise-grade encryption, compression, and data integrity protection\n- **🛡️ High Reliability**: Atomic transactions, data persistence, and fault recovery\n- **⚙️ Highly Configurable**: Flexible configuration options for different application scenarios\n- **📈 Scalable**: Multi-engine management and horizontal scaling support\n\n## 🔥 Key Features\n\n### 🎯 UltraKV Engine Features\n\n| Feature Category | Specific Functionality | Description |\n|-----------------|------------------------|-------------|\n| **🚀 Performance Optimization** | In-Memory Index + Disk Storage | Dual-guarantee high-performance architecture |\n| | Batch Operations Support | Efficient batch read/write and delete operations |\n| | Smart Buffering Mechanism | Configurable write buffer |\n| | Concurrency Control | Thread-safe concurrent access |\n| **💾 Storage Management** | Automatic Space Reclaim | Intelligent disk space compaction |\n| | Multiple Update Modes | Append mode and replace mode |\n| | Scheduled Persistence | Configurable auto-flush strategy |\n| | Optimized File Format | Compact binary storage format |\n| **🔐 Data Security** | Multiple Encryption Algorithms | AES256-GCM, ChaCha20-Poly1305 |\n| | Compression Support | LZ4, Zstd, Snappy, Gzip, etc. |\n| | Data Integrity Verification | Multiple hash algorithms for validation |\n| | Atomicity Guarantee | Write locks ensure transaction atomicity |\n\n### 🏗️ File Storage Structure\n\n#### UltraKV Storage Format\n```\n┌──────────────────────────────────────────────────┐\n│ 1. Database Header (Fixed 64 bytes)   │ ← File Start │\n├──────────────────────────────────────────────────┤\n│ 2. Value Data Area                               │\n│   ├─ Data Record 1 (Variable length)            │\n│   ├─ Data Record 2 (Variable length)            │\n│   └─ ...                                        │\n├──────────────────────────────────────────────────┤\n│ 3. Index Data Area [Start, End]    │ ← File End   │\n│   ├─ Index Entry 1 (Key + Position info)        │\n│   ├─ Index Entry 2 (Key + Position info)        │\n│   └─ ...                                        │\n└──────────────────────────────────────────────────┘\n```\n\n\n## ⚡ Performance Benchmarks\n\n### 🏆 UltraKV Performance Benchmark\n\n\u003e Test Environment: .NET 8.0, Windows 11, SSD Storage\n\n| Operation Type | Performance (ops/sec) | Notes |\n|---------------|----------------------|-------|\n| **Sequential Write** | **462,963** | Optimized for high-frequency writes |\n| **Batch Insert** | **564,972** | Enhanced batch operation performance |\n| **Random Read** | **632,911** | Accelerated by in-memory index |\n| **Contains Check** | **25,000,000** | Ultra-fast memory operations |\n| **Data Delete** | **833,333** | Efficient delete operations |\n| **Batch Delete** | **1,562,500** | Outstanding batch delete performance |\n| **Data Update** | **333,333** | In-place update optimization |\n| **Random Access** | **500,000** | Excellent random access performance |\n\n#### 🧠 In-Memory Mode Performance\n\n\u003e Test Environment: .NET 8.0, Windows 11, Average of 10 rounds, Memory mode operations\n\n| Operation Type | Performance (ops/sec) | Notes |\n|---------------|----------------------|-------|\n| **Write Performance** | **1,958,190** | Ultra-high speed memory writes |\n| **Read Performance** | **6,100,949** | Lightning-fast memory reads |\n| **ContainsKey Performance** | **7,844,485** | Optimized key existence checks |\n| **Delete Performance** | **5,984,823** | Efficient memory deletions |\n\n\u003e *Memory mode provides 3-8x performance improvement over file-based storage, ideal for cache and temporary data scenarios, Automatic timed persistence, and the memory mode can be turned off at any time*\n\n## 🚀 Quick Start\n\n### 📦 Installation\n\n```xml\n\u003cPackageReference Include=\"UltraKV\" Version=\"1.0.0\" /\u003e\n```\n\n### 🔧 Basic Usage\n\n#### UltraKV Basic Example\n\n```csharp\nusing UltraKV;\n\n// Create engine manager\nusing var manager = new UltraKVManager\u003cstring, string\u003e(\"./data\");\n\n// Get engine instance\nvar engine = manager.GetEngine(\"my_database\");\n\n// Basic operations\nengine.Set(\"user:1001\", \"John Doe\");\nengine.Set(\"user:1002\", \"Jane Smith\");\n\n// Read data\nvar user = engine.Get(\"user:1001\"); // Returns: \"John Doe\"\nvar exists = engine.ContainsKey(\"user:1001\"); // Returns: true\n\n// Delete data\nengine.Remove(\"user:1002\");\n\n// Batch operations\nvar batch = new Dictionary\u003cstring, string\u003e\n{\n    [\"product:1\"] = \"Laptop\",\n    [\"product:2\"] = \"Mouse\",\n    [\"product:3\"] = \"Keyboard\"\n};\nengine.SetBatch(batch);\n\n// Persist data\nengine.Flush();\n```\n\n#### Advanced Configuration Example\n\n```csharp\n// Create high-performance configuration\nvar config = new UltraKVConfig\n{\n    // Compression configuration\n    CompressionType = CompressionType.LZ4,\n    \n    // Encryption configuration\n    EncryptionType = EncryptionType.AES256GCM,\n    EncryptionKey = \"MySecureKey32BytesLong!@#$%^\u0026*()\",\n    \n    // Performance configuration\n    FileStreamBufferSizeKB = 1024, // 1MB buffer\n    WriteBufferSizeKB = 2048,      // 2MB write buffer\n    FlushInterval = 10,            // 10-second auto-flush\n    \n    // Maintenance configuration\n    AutoCompactEnabled = true,     // Enable auto-compaction\n    AutoCompactThreshold = 30,     // 30% fragmentation triggers compaction\n    \n    // File update mode\n    FileUpdateMode = FileUpdateMode.Append // Append mode for higher performance\n};\n\nvar engine = manager.GetEngine(\"high_performance_db\", config);\n```\n\n## 📖 Detailed Usage Guide\n\n### 🔧 Configuration Options Explained\n\n#### UltraKVConfig Core Configuration\n\n```csharp\npublic class UltraKVConfig\n{\n    // 🎯 Performance Related\n    public bool EnableMemoryMode { get; set; } = false;           // Memory mode\n    public int FileStreamBufferSizeKB { get; set; } = 64;         // File buffer\n    public bool EnableWriteBuffer { get; set; } = true;           // Write buffer\n    public int WriteBufferSizeKB { get; set; } = 1024;            // Buffer size\n    \n    // 🔐 Security Related\n    public CompressionType CompressionType { get; set; }          // Compression algorithm\n    public EncryptionType EncryptionType { get; set; }            // Encryption algorithm\n    public HashType HashType { get; set; } = HashType.XXH3;       // Hash algorithm\n    public string? EncryptionKey { get; set; }                    // Encryption key\n    \n    // 🔄 Maintenance Related\n    public bool AutoCompactEnabled { get; set; } = false;         // Auto-compaction\n    public byte AutoCompactThreshold { get; set; } = 50;          // Compaction threshold\n    public ushort FlushInterval { get; set; } = 5;                // Flush interval\n    public FileUpdateMode FileUpdateMode { get; set; }            // Update mode\n    \n    // 🛡️ Validation Related\n    public bool EnableUpdateValidation { get; set; } = false;     // Update validation\n    public int MaxKeyLength { get; set; } = 4096;                 // Maximum key length\n}\n```\n\n### 🔄 Lifecycle Management\n\n```csharp\n// Engine manager supports multiple engines\nusing var manager = new UltraKVManager\u003cstring, object\u003e(\"./databases\");\n\n// Create engines for different purposes\nvar userEngine = manager.GetEngine(\"users\", UltraKVConfig.Default);\nvar sessionEngine = manager.GetEngine(\"sessions\", UltraKVConfig.Minimal);\nvar cacheEngine = manager.GetEngine(\"cache\", new UltraKVConfig \n{ \n    FlushInterval = 30,      // Cache data can flush less frequently\n    EnableMemoryMode = true  // Enable memory mode for cache\n});\n\n// Batch flush\nmanager.FlushAll();\n\n// Close specific engine\nmanager.CloseEngine(\"cache\");\n\n// Get engine list\nvar engineNames = manager.GetEngineNames();\n```\n\n### 📊 Performance Monitoring\n\n```csharp\n// Get engine statistics\nvar stats = engine.GetStats();\nConsole.WriteLine($\"Record Count: {stats.RecordCount}\");\nConsole.WriteLine($\"Deleted Count: {stats.DeletedCount}\");\nConsole.WriteLine($\"File Size: {stats.FileSize / 1024.0 / 1024.0:F2} MB\");\nConsole.WriteLine($\"Deletion Ratio: {stats.DeletionRatio:P1}\");\nConsole.WriteLine($\"Compaction Recommended: {stats.ShrinkRecommended}\");\n\n// Manually trigger compaction\nif (engine.ShouldShrink())\n{\n    engine.Compact(fullRebuild: false);\n}\n```\n\n## 🔧 Advanced Configuration\n\n### 🚀 Performance Optimization Configuration\n\n#### High Throughput Write Scenarios\n```csharp\nvar highThroughputConfig = new UltraKVConfig\n{\n    FileUpdateMode = FileUpdateMode.Append,  // Append mode for best performance\n    WriteBufferSizeKB = 4096,                // 4MB large buffer\n    FileStreamBufferSizeKB = 2048,           // 2MB file buffer\n    FlushInterval = 30,                      // Longer flush interval\n    AutoCompactThreshold = 70                // Higher compaction threshold\n};\n```\n\n#### Low Latency Read Scenarios\n```csharp\nvar lowLatencyConfig = new UltraKVConfig\n{\n    EnableMemoryMode = true,                 // Memory mode for lowest latency\n    FlushInterval = 5,                       // Frequent flushing for data safety\n    EnableUpdateValidation = true            // Enable validation for data correctness\n};\n```\n\n#### Storage Space Sensitive Scenarios\n```csharp\nvar compactConfig = new UltraKVConfig\n{\n    CompressionType = CompressionType.Zstd,  // Best compression ratio\n    AutoCompactEnabled = true,               // Enable auto-compaction\n    AutoCompactThreshold = 20,               // Low threshold triggers compaction\n    FileUpdateMode = FileUpdateMode.Replace  // Replace mode reduces fragmentation\n};\n```\n\n### 🔐 Security Configuration Examples\n\n#### Enterprise-Grade Security Configuration\n```csharp\nvar secureConfig = UltraKVConfig.Secure(\"MyEnterprise256BitSecretKey!@#\");\n// Equivalent to:\nvar secureConfig = new UltraKVConfig\n{\n    CompressionType = CompressionType.Gzip,\n    EncryptionType = EncryptionType.AES256GCM,\n    EncryptionKey = \"MyEnterprise256BitSecretKey!@#\",\n    HashType = HashType.SHA256,\n    EnableUpdateValidation = true\n};\n```\n\n#### Debug and Development Configuration\n```csharp\nvar debugConfig = UltraKVConfig.Debug; // Enable all validation options\n```\n\n### 🔄 Compression Algorithm Selection Guide\n\n| Algorithm | Compression Ratio | Speed | Use Case |\n|-----------|------------------|-------|----------|\n| **LZ4** | Medium | Extremely Fast | High-performance requirements |\n| **Zstd** | Excellent | Fast | Balance performance and compression |\n| **Snappy** | Medium | Extremely Fast | Google ecosystem |\n| **Gzip** | Good | Medium | General-purpose compression |\n| **Brotli** | Excellent | Slower | Web application optimization |\n\n### 🔐 Encryption Algorithm Selection Guide\n\n| Algorithm | Security Level | Performance | Use Case |\n|-----------|---------------|-------------|----------|\n| **AES256-GCM** | Extremely High | Excellent | Enterprise applications |\n| **ChaCha20-Poly1305** | Extremely High | Excellent | Mobile device optimization |\n\n## 📊 Performance Testing\n\n### 🧪 Built-in Performance Tests\n\nThe project includes a complete performance testing suite. You can run the following tests:\n\n```bash\n# Clone the project\ngit clone https://github.com/trueai-org/UltraKV.git\ncd UltraKV\n\n# Run UltraKV performance tests\ndotnet run --project src/UltraKV --configuration Release\n\n# Run comparison tests\ndotnet test src/UltraKV.Tests --configuration Release\n```\n\n### 📈 Custom Performance Testing\n\n```csharp\n// Performance testing example\npublic async Task BenchmarkWritePerformance()\n{\n    using var manager = new UltraKVManager\u003cstring, string\u003e(\"./benchmark\");\n    var engine = manager.GetEngine(\"test\");\n    \n    const int iterations = 100_000;\n    var stopwatch = Stopwatch.StartNew();\n    \n    for (int i = 0; i \u003c iterations; i++)\n    {\n        engine.Set($\"key_{i}\", $\"value_{i}\");\n        \n        if (i % 1000 == 0)  // Flush every 1000 operations\n        {\n            engine.Flush();\n        }\n    }\n    \n    engine.Flush();\n    stopwatch.Stop();\n    \n    var opsPerSecond = iterations * 1000.0 / stopwatch.ElapsedMilliseconds;\n    Console.WriteLine($\"Write Performance: {opsPerSecond:N0} ops/sec\");\n}\n```\n\n### 🔄 Compaction Performance Testing\n\n```csharp\n// Test compaction operation performance\npublic void BenchmarkCompactPerformance()\n{\n    using var engine = new UltraKVEngine\u003cstring, string\u003e(\"./compact_test.db\");\n    \n    // Write large amount of data\n    for (int i = 0; i \u003c 50_000; i++)\n    {\n        engine.Set($\"key_{i}\", new string('x', 1024)); // 1KB data\n    }\n    \n    // Delete 50% of data to create fragmentation\n    for (int i = 0; i \u003c 50_000; i += 2)\n    {\n        engine.Remove($\"key_{i}\");\n    }\n    \n    var beforeSize = new FileInfo(\"./compact_test.db\").Length;\n    var beforeStats = engine.GetStats();\n    \n    var stopwatch = Stopwatch.StartNew();\n    engine.Compact(fullRebuild: false);\n    stopwatch.Stop();\n    \n    var afterSize = new FileInfo(\"./compact_test.db\").Length;\n    var afterStats = engine.GetStats();\n    \n    Console.WriteLine($\"Compaction Time: {stopwatch.ElapsedMilliseconds}ms\");\n    Console.WriteLine($\"File Size: {beforeSize / 1024 / 1024}MB -\u003e {afterSize / 1024 / 1024}MB\");\n    Console.WriteLine($\"Space Saved: {(1 - (double)afterSize / beforeSize):P1}\");\n}\n```\n\n## 🔐 Security Features\n\n### 🔒 Data Encryption\n\nUltraKV supports industry-standard encryption algorithms:\n\n- **AES256-GCM**: Widely recognized enterprise-grade encryption standard\n- **ChaCha20-Poly1305**: Modern high-performance encryption algorithm\n\n```csharp\n// Enable encrypted storage\nvar encryptedEngine = manager.GetEngine(\"secure_data\", new UltraKVConfig\n{\n    EncryptionType = EncryptionType.AES256GCM,\n    EncryptionKey = \"MySecure32ByteEncryptionKey12345\"\n});\n\n// Data will be automatically encrypted when stored\nencryptedEngine.Set(\"sensitive_data\", \"confidential_information\");\n```\n\n### 📋 Data Integrity\n\nMultiple data integrity protection mechanisms:\n\n```csharp\nvar validatedConfig = new UltraKVConfig\n{\n    EnableUpdateValidation = true,  // Enable write validation\n    HashType = HashType.SHA256,     // Use SHA256 for data verification\n};\n```\n\nSupported hash algorithms:\n- **XXH3**: Ultra-fast hash, default choice\n- **SHA256**: Cryptographic-grade hash\n- **BLAKE3**: Modern high-performance hash\n- **XXH128**: 128-bit hash with low collision rate\n\n## 🛠️ Best Practices\n\n### 💡 Performance Optimization Recommendations\n\n1. **Buffer Configuration**\n```csharp\n// Adjust buffer size based on memory availability\nvar config = new UltraKVConfig\n{\n    FileStreamBufferSizeKB = Environment.Is64BitProcess ? 1024 : 256,\n    WriteBufferSizeKB = Environment.Is64BitProcess ? 4096 : 1024\n};\n```\n\n2. **Batch Operation Optimization**\n```csharp\n// Use batch operations to improve performance\nvar batch = new Dictionary\u003cstring, string\u003e();\nfor (int i = 0; i \u003c 10000; i++)\n{\n    batch[$\"key_{i}\"] = $\"value_{i}\";\n}\nengine.SetBatch(batch);  // Much faster than individual Set operations\n```\n\n3. **Reasonable Flush Strategy**\n```csharp\n// High-frequency write scenarios\nvar highWriteConfig = new UltraKVConfig\n{\n    FlushInterval = 30,      // Flush every 30 seconds\n    WriteBufferSizeKB = 8192 // 8MB buffer\n};\n\n// Low-latency scenarios\nvar lowLatencyConfig = new UltraKVConfig\n{\n    FlushInterval = 1,       // Flush every 1 second\n    EnableUpdateValidation = true  // Enable validation\n};\n```\n\n### 🔧 Maintenance and Monitoring\n\n1. **Regular Statistics Monitoring**\n```csharp\n// Regularly check engine status\nvar timer = new Timer(async _ =\u003e\n{\n    var stats = engine.GetStats();\n    if (stats.DeletionRatio \u003e 0.3)  // Deletion ratio exceeds 30%\n    {\n        Console.WriteLine(\"Compaction operation recommended\");\n        if (engine.ShouldShrink())\n        {\n            engine.Compact();\n        }\n    }\n}, null, TimeSpan.Zero, TimeSpan.FromMinutes(5));\n```\n\n2. **Graceful Shutdown Handling**\n```csharp\n// Ensure data safety when application shuts down\nAppDomain.CurrentDomain.ProcessExit += (sender, e) =\u003e\n{\n    manager.FlushAll();  // Flush all engines\n    manager.Dispose();   // Release resources\n};\n```\n\n### 🚨 Error Handling\n\n```csharp\ntry\n{\n    engine.Set(\"key\", \"value\");\n}\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"disposed\"))\n{\n    // Engine has been disposed\n    Console.WriteLine(\"Engine is closed, please reinitialize\");\n}\ncatch (ArgumentException ex) when (ex.Message.Contains(\"EncryptionKey\"))\n{\n    // Encryption configuration error\n    Console.WriteLine(\"Encryption key configuration error\");\n}\ncatch (IOException ex)\n{\n    // Disk IO error\n    Console.WriteLine($\"Disk operation failed: {ex.Message}\");\n}\n```\n\n## 🔄 Data Migration and Backup\n\n### 📤 Data Export\n\n```csharp\n// Export all data\npublic void ExportData(UltraKVEngine\u003cstring, string\u003e engine, string backupFile)\n{\n    var allKeys = engine.GetAllKeys();\n    var backup = new Dictionary\u003cstring, string\u003e();\n    \n    foreach (var key in allKeys)\n    {\n        var value = engine.Get(key);\n        if (value != null)\n        {\n            backup[key] = value;\n        }\n    }\n    \n    var json = JsonSerializer.Serialize(backup, new JsonSerializerOptions \n    { \n        WriteIndented = true \n    });\n    File.WriteAllText(backupFile, json);\n}\n```\n\n### 📥 Data Import\n\n```csharp\n// Restore data from backup\npublic void ImportData(UltraKVEngine\u003cstring, string\u003e engine, string backupFile)\n{\n    var json = File.ReadAllText(backupFile);\n    var backup = JsonSerializer.Deserialize\u003cDictionary\u003cstring, string\u003e\u003e(json);\n    \n    if (backup != null)\n    {\n        engine.SetBatch(backup);\n        engine.Flush();\n    }\n}\n```\n\n## 🌐 Integration with Other Technologies\n\n### 🔄 ASP.NET Core Integration\n\n```csharp\n// Startup.cs or Program.cs\nservices.AddSingleton\u003cUltraKVManager\u003cstring, object\u003e\u003e(provider =\u003e\n    new UltraKVManager\u003cstring, object\u003e(\"./app_data\"));\n\nservices.AddSingleton\u003cIMemoryCache\u003e(provider =\u003e\n{\n    var manager = provider.GetService\u003cUltraKVManager\u003cstring, object\u003e\u003e();\n    return new UltraKVCache(manager.GetEngine(\"cache\"));\n});\n```\n\n### 🔧 Custom Cache Implementation\n\n```csharp\npublic class UltraKVCache : IMemoryCache\n{\n    private readonly UltraKVEngine\u003cstring, object\u003e _engine;\n    \n    public UltraKVCache(UltraKVEngine\u003cstring, object\u003e engine)\n    {\n        _engine = engine;\n    }\n    \n    public bool TryGetValue(object key, out object value)\n    {\n        value = _engine.Get(key.ToString()!);\n        return value != null;\n    }\n    \n    public ICacheEntry CreateEntry(object key)\n    {\n        return new UltraKVCacheEntry(key.ToString()!, _engine);\n    }\n    \n    // ... other interface implementations\n}\n```\n\n## 🤝 Contributing\n\nWe welcome all forms of contribution! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for detailed information.\n\n### 🐛 Bug Reports\n\nBefore submitting an issue, please ensure:\n\n1. Search existing issues\n2. Provide detailed error information and reproduction steps\n3. Include environment information (.NET version, operating system, etc.)\n\n### 💡 Feature Requests\n\nWe welcome feature suggestions! Please describe in detail in the issue:\n\n1. Use case for the feature\n2. Expected behavior\n3. Possible implementation approaches\n\n### 🔧 Development Environment Setup\n\n```bash\n# 1. Fork and clone the project\nhttps://github.com/trueai-org/ultra-kv.git\ncd ultra-kv\n\n# 2. Install dependencies\ndotnet restore\n\n# 3. Run tests\ndotnet test\n\n# 4. Build project\ndotnet build --configuration Release\n```\n\n## 📚 References\n\nThis project references the following excellent open-source projects:\n\n- [Lightning.NET](https://github.com/CoreyKaylor/Lightning.NET) - LMDB .NET bindings\n- [Fast-Persistent-Dictionary](https://github.com/jgric2/Fast-Persistent-Dictionary) - Persistent dictionary implementation\n- [Microsoft FASTER](https://github.com/microsoft/FASTER) - High-performance key-value store\n- [DBreeze](https://github.com/hhblaze/DBreeze) - .NET embedded database\n\n## 📊 Performance Comparison\n\n| Database | Write (ops/s) | Read (ops/s) | Features |\n|----------|--------------|-------------|----------|\n| **UltraKV UltraKV** | **462,963** | **632,911** | Pure .NET, zero dependencies |\n| FASTER | ~400,000 | ~1,000,000 | Microsoft product, memory optimized |\n| LevelDB (C++) | ~100,000 | ~200,000 | Google product, battle-tested |\n| SQLite | ~50,000 | ~100,000 | Relational, feature-complete |\n\n\u003e *Performance data based on benchmark tests on the same hardware environment. Actual performance varies by environment*\n\n\n## 📈 Roadmap\n\n### 🎯 Near-term Goals (v1.1)\n- [ ] Distributed support and cluster mode\n- [ ] More compression algorithm support\n- [ ] Performance monitoring and metrics export\n- [ ] Database repair tools\n\n### 🚀 Mid-term Goals (v2.0)\n- [ ] Support for complex queries and indexing\n- [ ] Plugin-based storage backends\n- [ ] Cloud-native support\n- [ ] Graphical management interface\n\n### 🌟 Long-term Goals (v3.0)\n- [ ] Machine learning optimized performance tuning\n- [ ] Automated operations and fault recovery\n- [ ] Cross-platform mobile support\n\n## 📱 Community and Support\n\n- 💬 [Discussions](https://github.com/trueai-org/ultra-kv/discussions) - Technical discussions and Q\u0026A\n- 📧 [Mailing List](mailto:ultrakv@trueai.org) - Official announcements and updates\n- 🐛 [Issue Tracker](https://github.com/trueai-org/ultra-kv/issues) - Bug reports and feature requests\n- 📖 [Wiki](https://github.com/trueai-org/ultra-kv/wiki) - Detailed documentation and tutorials\n\n## 📄 License\n\nThis project is licensed under the [MIT License](LICENSE).\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**⭐ If this project helps you, please give us a Star! ⭐**\n\n[🏠 Home](https://github.com/trueai-org/ultra-kv) • \n[📚 Documentation](https://github.com/trueai-org/ultra-kv/wiki) • \n[🐛 Report Issues](https://github.com/trueai-org/ultra-kv/issues) • \n[💡 Feature Requests](https://github.com/trueai-org/ultra-kv/issues/new?template=feature_request.md)\n\nCopyright © 2024 TrueAI.org. All rights reserved.\n\n\u003c/div\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrueai-org%2Fultra-kv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrueai-org%2Fultra-kv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrueai-org%2Fultra-kv/lists"}