{"id":13546165,"url":"https://github.com/ex0dus-0x/microkv","last_synced_at":"2025-08-15T03:32:02.193Z","repository":{"id":45606970,"uuid":"128689842","full_name":"ex0dus-0x/microkv","owner":"ex0dus-0x","description":"Minimal and persistent key-value store designed with security in mind","archived":false,"fork":false,"pushed_at":"2023-01-16T23:18:41.000Z","size":67,"stargazers_count":32,"open_issues_count":2,"forks_count":6,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-11-14T14:25:36.776Z","etag":null,"topics":["crypto","database","rust","security","systems"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ex0dus-0x.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-04-08T23:18:15.000Z","updated_at":"2024-08-12T19:37:35.000Z","dependencies_parsed_at":"2023-02-10T06:45:35.468Z","dependency_job_id":null,"html_url":"https://github.com/ex0dus-0x/microkv","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ex0dus-0x%2Fmicrokv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ex0dus-0x%2Fmicrokv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ex0dus-0x%2Fmicrokv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ex0dus-0x%2Fmicrokv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ex0dus-0x","download_url":"https://codeload.github.com/ex0dus-0x/microkv/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229776246,"owners_count":18122350,"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":["crypto","database","rust","security","systems"],"created_at":"2024-08-01T12:00:32.778Z","updated_at":"2024-12-15T23:45:00.348Z","avatar_url":"https://github.com/ex0dus-0x.png","language":"Rust","funding_links":[],"categories":["Cryptography","Rust"],"sub_categories":["Frameworks"],"readme":"# microkv\n\n[![Actions][actions-badge]][actions-url]\n[![crates.io version][crates-microkv-badge]][crates-microkv]\n[![Docs][docs-badge]][docs.rs]\n\n[actions-badge]: https://github.com/ex0dus-0x/microkv/workflows/CI/badge.svg?branch=master\n[actions-url]: https://github.com/ex0dus-0x/microkv/actions\n\n[crates-microkv-badge]: https://img.shields.io/crates/v/microkv.svg\n[crates-microkv]: https://crates.io/crates/microkv\n\n[docs-badge]: https://docs.rs/microkv/badge.svg\n[docs.rs]: https://docs.rs/microkv\n\nMinimal and persistent key-value store designed with security in mind.\n\n## Introduction\n\n__microkv__ is a minimal and persistent key-value store designed with security in mind, built to prioritize secure storage for client-side application. I created this project out of a yearning to learn more about the intricacies of distributed systems, databases, and secure persistent storage.\n\nWhile __microkv__ shouldn't be used in large-scale environments that facilitate an insane volume of transactional interactions,\nit is still optimal for use in a production-grade system/application that may not require the complex luxuries of a\nfull-blown database or even industry-standard KV-store like Redis or LevelDB.\n\n## Features\n\n* __Performant__\n\n__microkv__'s underlying map structure is based off of @bluss's [indexmap](https://github.com/bluss/indexmap) implementation, which offers performance on par with built-in `HashMap`'s amortized constant runtime, but can also provided sorted key iteration, similar to the less-performant `BTreeMap`. This provides a strong balance between performance and functionality.\n\nWhen reading and persisting to disk, the key-value store uses `bincode` for fast de/serialization of the underlying structures, allowing users to insert any serializable structure without worrying about incurred overhead for storing complex data structures.\n\n* __Secure__\n\n__microkv__ acts almost in the sense of a secure enclave with any stored information. First, inserted values are immediately encryped using authenticated encryption with XSalsa20 (stream cipher) and Poly1305 (HMAC) from `sodiumoxide`, guarenteeing security and integrity. Encryped values in-memory are also memory-locked with `mlock`, and securely zeroed when destroyed to avoid persistence in memory pages.\n\n__microkv__ also provides locking support with `RwLock`s, which utilize mutual exclusion like mutexes, but robust in the sense that concurrent read locks can be held, but only one writer lock can be held at a time. This helps remove thread-safety and data race concerns, but also enables multiple read accesses safely.\n\n* __Small__\n\nAt its core, __microkv__ is implemented in ~500 LOCs, making the implementation portable and auditable. It remains faithfully opinionated, meaning it will not offer extensions to other serializable formats, or any other user-involved configurability, allowing it to work right out of the box.\n\n## Usage\n\nTo install locally, simply clone the repository and install with `cargo`:\n\n```\n# .. from crates.io\n$ cargo install microkv\n\n# .. or locally\n$ git clone https://github.com/ex0dus-0x/microkv\n$ cargo install --path .\n```\n\nHere's example usage of the `microkv` library crate:\n\n```rust\nuse microkv::MicroKV;\n\n#[derive(Serialize, Deserialize, Debug)]\nstruct Identity {\n    uuid: u32,\n    name: String,\n    sensitive_data: String,\n}\n\n\nfn main() {\n    let unsafe_pwd: String = \"my_password_123\";\n\n    // initialize in-memory database with (unsafe) cleartext password\n    let db: MicroKV = MicroKV::new(\"my_db\")\n        .with_pwd_clear(unsafe_pwd);\n\n    // ... or backed by disk, with auto-commit per transaction\n    let db: MicroKV = MicroKV::open_with_base_path(\"my_db_on_disk\", SOME_PATH)\n        .expect(\"Failed to create MicroKV from a stored file or create MicroKV for this file\")\n        .set_auto_commit(true)\n        .with_pwd_clear(unsafe_pwd);\n\n    // simple interaction to default namespace\n    db.put(\"simple\", 1);\n    print(\"{}\", db.get_unwrap(\"simple\").unwrap());\n    db.delete(\"simple\");\n\n    // more complex interaction to default namespace\n    let identity = Identity {\n        uuid: 123,\n        name: String::from(\"Alice\"),\n        sensitive_data: String::from(\"something_important_here\")\n    };\n    db.put(\"complex\", identity);\n    let stored_identity: Identity = db.get_unwrap(\"complex\").unwrap();\n    println!(\"{:?}\", stored_identity);\n    db.delete(\"complex\");\n}\n```\n\n__microkv__ also supports transactions on other namespaces to support grouping and\norganizing keys (thanks @fewensa!):\n\n```rust\n    let namespace_one = db.namespace(\"one\");\n    namespace_one.put(\"zoo\", \u0026\"big\".to_string()).unwrap();\n```\n\n__microkv__ also includes a [simple command line application](https://github.com/ex0dus-0x/microkv/tree/master/cli)\nthat is installed alongside the package. While not entirely useful at the moment, future plans are to be able \nto integrate it such that it can be exposed through a Docker container.\n\n## Contributions\n\nInterested on improving the state of this project? Check out the [issue tracker](https://github.com/ex0dus-0x/microkv/issues) for what we need help on!\n\n## License\n\n[MIT license](https://codemuch.tech/docs/license.txt)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fex0dus-0x%2Fmicrokv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fex0dus-0x%2Fmicrokv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fex0dus-0x%2Fmicrokv/lists"}