{"id":41139770,"url":"https://github.com/adityamukho/minigraf","last_synced_at":"2026-01-22T18:47:36.624Z","repository":{"id":178232433,"uuid":"661300548","full_name":"adityamukho/minigraf","owner":"adityamukho","description":"The embeddable graph database.","archived":false,"fork":false,"pushed_at":"2026-01-11T08:57:41.000Z","size":158,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-11T11:07:23.365Z","etag":null,"topics":["database","embedded","gql","graph"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adityamukho.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-07-02T12:20:33.000Z","updated_at":"2026-01-11T08:57:44.000Z","dependencies_parsed_at":null,"dependency_job_id":"567cbdd4-d331-46fc-8893-9f69beb75a10","html_url":"https://github.com/adityamukho/minigraf","commit_stats":null,"previous_names":["adityamukho/minigraf"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/adityamukho/minigraf","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adityamukho%2Fminigraf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adityamukho%2Fminigraf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adityamukho%2Fminigraf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adityamukho%2Fminigraf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adityamukho","download_url":"https://codeload.github.com/adityamukho/minigraf/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adityamukho%2Fminigraf/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28668398,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-22T17:07:18.858Z","status":"ssl_error","status_checked_at":"2026-01-22T17:05:02.040Z","response_time":144,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["database","embedded","gql","graph"],"created_at":"2026-01-22T18:47:36.086Z","updated_at":"2026-01-22T18:47:36.613Z","avatar_url":"https://github.com/adityamukho.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Minigraf\n\n[![Build Status](https://github.com/adityamukho/minigraf/actions/workflows/rust.yml/badge.svg)](https://github.com/adityamukho/minigraf/actions/workflows/rust.yml)\n[![Clippy Status](https://github.com/adityamukho/minigraf/actions/workflows/rust-clippy.yml/badge.svg)](https://github.com/adityamukho/minigraf/actions/workflows/rust-clippy.yml)\n[![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](https://github.com/adityamukho/minigraf#license)\n[![Rust Edition](https://img.shields.io/badge/rust-2024-orange.svg)](https://blog.rust-lang.org/2024/10/17/Rust-1.82.0.html)\n[![Phase](https://img.shields.io/badge/phase-3%20complete-blue.svg)](https://github.com/adityamukho/minigraf/blob/main/ROADMAP.md)\n\n\u003e **The SQLite of bi-temporal graph databases** - Embedded Datalog engine written in Rust\n\nA tiny, self-contained graph database with **Datalog queries** and **bi-temporal time travel**. Think SQLite, but for connected data with full history.\n\n## Vision\n\nMinigraf is a **single-file embedded graph database** that lets you:\n- ✅ **Query relationships with Datalog** - Recursive rules, natural graph traversal\n- 🎯 **Time travel through history** - Bi-temporal queries (transaction time + valid time)\n- ✅ **Embed anywhere** - Native, WASM, mobile, IoT - one `.graph` file\n- ✅ **Zero configuration** - Just `Minigraf::open(\"data.graph\")` and you're done\n\n**Status**: Early development. Phase 3 complete (Datalog with recursive rules). Now starting Phase 4 (bi-temporal support).\n\n## Why Datalog?\n\n**Datalog is fundamentally better for graphs than SQL-like languages:**\n\n1. **Recursive by design** - Multi-hop traversals are natural, not an afterthought\n2. **Simpler to implement** - Smaller spec = more reliable, faster to production\n3. **Perfect for temporal** - Time is just another dimension in relations\n4. **Proven at scale** - 40+ years of research, production use (Datomic, XTDB)\n5. **Graph-native** - Facts (Entity-Attribute-Value) are literally edges\n\n## Current Status - Phase 3 Complete\n\nMinigraf has **working Datalog query engine with recursive rules**:\n\n- ✅ **EAV data model** - Entity-Attribute-Value facts with transaction IDs\n- ✅ **Datalog queries** - Pattern matching with variable unification\n- ✅ **Recursive rules** - Semi-naive evaluation, transitive closure\n- ✅ **Single `.graph` file** - Page-based storage (4KB pages)\n- ✅ **Embedded database API** - Use like SQLite (`Minigraf::open()`)\n- ✅ **Cross-platform** - Works on Linux, macOS, Windows, iOS, Android\n- ✅ **Auto-persistence** - Changes auto-save when database is dropped\n- ✅ **123 tests passing** - Comprehensive test coverage\n- 🎯 **Next: Bi-temporal support** - Transaction time + valid time (Phase 4)\n\n## Quick Start\n\n### Embedded Datalog Database (Working!)\n\n```rust\nuse minigraf::Minigraf;\n\n// Open or create a database\nlet mut db = Minigraf::open(\"myapp.graph\")?;\n\n// Add facts (Entity-Attribute-Value triples)\ndb.transact(vec![\n    [:alice, :person/name, \"Alice\"],\n    [:alice, :person/age, 30],\n    [:alice, :friend, :bob],\n    [:bob, :person/name, \"Bob\"],\n])?;\n\n// Query with Datalog\nlet results = db.query(\"\n    [:find ?friend-name\n     :where\n       [:alice :friend ?friend]\n       [?friend :person/name ?friend-name]]\n\")?;\n\n// Time travel - query as of past transaction\nlet past_db = db.as_of(tx_100);\nlet old_results = past_db.query(...)?;\n```\n\n### Interactive Console (Datalog REPL)\n\n```bash\n# Build and run the Datalog REPL\ncargo run\n\n# Run tests\ncargo test\n\n# Try the recursive rules demo\ncargo run \u003c demo_recursive.txt\n```\n\n## Datalog Query Language (Phase 3 - Working!)\n\n### Basic Facts\n\n```datalog\n;; Add facts about entities\n[:alice :person/name \"Alice\"]\n[:alice :person/age 30]\n[:alice :friend :bob]\n[:bob :person/name \"Bob\"]\n```\n\n### Simple Queries\n\n```datalog\n;; Find all friends of Alice\n[:find ?friend\n :where\n   [:alice :friend ?friend]]\n\n;; Find names of Alice's friends\n[:find ?name\n :where\n   [:alice :friend ?friend]\n   [?friend :person/name ?name]]\n```\n\n### Recursive Rules (The Power of Datalog)\n\n```datalog\n;; Define transitive friendship\n[(friends-network ?person ?reachable)\n [?person :friend ?reachable]]\n\n[(friends-network ?person ?reachable)\n [?person :friend ?intermediate]\n (friends-network ?intermediate ?reachable)]\n\n;; Find everyone in Alice's network\n[:find ?person\n :where\n   (friends-network :alice ?person)]\n```\n\n### Bi-temporal Queries (Phase 4)\n\n```datalog\n;; Query valid at a specific time\n[:find ?name\n :valid-at \"2023-06-01\"\n :where\n   [:alice :person/name ?name]]\n\n;; Query as of past transaction\n[:find ?friend\n :as-of tx-100\n :where\n   [:alice :friend ?friend]]\n\n;; Full bi-temporal query\n[:find ?status\n :valid-at \"2023-06-01\"\n :as-of tx-100\n :where\n   [:alice :employment/status ?status]]\n```\n\n## Architecture\n\n### Module Structure\n\n- **`src/graph/types.rs`**: Core graph data structures (EAV model)\n- **`src/graph/storage.rs`**: In-memory storage layer\n- **`src/storage/`**: Storage backend abstraction\n  - **`mod.rs`**: StorageBackend trait, file format\n  - **`backend/file.rs`**: Single-file persistent backend\n  - **`backend/memory.rs`**: In-memory backend for testing\n  - **`backend/indexeddb.rs`**: Future WASM backend\n- **`src/query/datalog/parser.rs`**: Query parser\n- **`src/query/datalog/executor.rs`**: Query executor\n- **`src/repl.rs`**: Interactive REPL console\n- **`src/lib.rs`**: Public API\n- **`src/main.rs`**: Binary entry point\n\n### Data Model\n\n- Facts: `(Entity, Attribute, Value, ValidFrom, ValidTo, TxTime)`\n- Entities are just UUIDs\n- Attributes are keywords (`:person/name`, `:friend`)\n- Values can be primitives or entity references\n- Time dimensions for bi-temporal support\n\n### Storage Format\n\nThe `.graph` file uses a page-based format (like SQLite):\n\n```\n+----------------+\n| Page 0: Header | \u003c- Magic \"MGRF\", version, page count\n+----------------+\n| Page 1: Facts  | \u003c- (E, A, V, ValidFrom, ValidTo, TxTime)\n+----------------+\n| Page 2: Indexes| \u003c- EAVT, AEVT, AVET, VAET indexes\n+----------------+\n| Page 3+: Data  |\n+----------------+\n```\n\n- **Page size**: 4KB (like SQLite)\n- **Endian-safe**: Works across all platforms\n- **Single file**: Easy to backup, share, version control\n- **Stable format**: Backwards compatible once v1.0 ships\n\n## Roadmap\n\n**Phase 1**: ✅ Property graph PoC (Complete)\n**Phase 2**: ✅ Persistent storage (Complete)\n**Phase 3**: ✅ Datalog core (Complete)\n- ✅ Basic facts and queries\n- ✅ Recursive rules\n- ✅ Pattern matching\n\n**Phase 4**: 🎯 Bi-temporal support\n- Valid time + transaction time\n- Time travel queries\n- Historical analysis\n\n**Phase 5**: 🎯 ACID + WAL\n- Write-ahead logging\n- Transactions\n- Crash recovery\n\n**Phase 6**: 🎯 Performance\n- Indexes (EAVT, AEVT, AVET, VAET)\n- Query optimization\n- Benchmarking\n\n**Phase 7**: 🎯 Cross-platform\n- WASM (IndexedDB backend)\n- Mobile bindings\n- Language bindings\n\n**v1.0.0**: Phase 7 complete\n\nSee [ROADMAP.md](ROADMAP.md) for detailed breakdown.\n\n## Why Minigraf?\n\n### Unique Positioning\n\nNo other database offers this combination:\n\n| Feature | Minigraf | XTDB | Cozo | Neo4j | SQLite |\n|---------|----------|------|------|-------|--------|\n| **Query Language** | Datalog | Datalog | Datalog | Cypher | SQL |\n| **Single File** | ✅ Yes | ❌ No | ❌ No | ❌ No | ✅ Yes |\n| **Bi-temporal** | 🎯 Goal | ✅ Yes | ⚠️ Time travel | ❌ No | ❌ No |\n| **Embedded** | ✅ Yes | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes |\n| **Graph Native** | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes | ❌ No |\n| **Rust** | ✅ Yes | ❌ Clojure | ✅ Yes | ❌ Java | ❌ C |\n| **WASM Ready** | 🎯 Goal | ❌ No | ⚠️ Limited | ❌ No | ✅ Yes |\n\n**Minigraf = SQLite's simplicity + Datomic's temporal model**\n\n### Target Use Cases\n\n1. **Audit-heavy applications** - Finance, healthcare, legal (bi-temporal = compliance)\n2. **Event sourcing** - Full history, time travel debugging\n3. **Personal knowledge bases** - Obsidian, Logseq, Roam-like apps\n4. **Local-first applications** - Offline-capable, user-owned data\n5. **AI/RAG systems** - Knowledge graphs with provenance\n6. **Mobile apps** - Embedded graph database on devices\n7. **WASM applications** - Graph database in the browser\n8. **Development/testing** - Local graph DB like SQLite\n\n### Philosophy: The SQLite of Graph Databases\n\n- **Zero-configuration** - No setup, just works\n- **Embedded-first** - Library, not server\n- **Single-file database** - Easy backup, share, version control\n- **Self-contained** - \u003c1MB binary, minimal dependencies (targetted)\n- **Cross-platform** - Native, WASM, mobile, embedded\n- **Reliability over features** - Do less, do it perfectly\n- **Long-term support** - Decades-long commitment\n\nSee [PHILOSOPHY.md](PHILOSOPHY.md) for complete design principles.\n\n## Scope\n\nMinigraf is designed to run in multiple environments:\n- ✅ As a standalone binary\n- ✅ As an embedded library\n- 🎯 As a WebAssembly module (future - Phase 7)\n\n## Unscope\n\nMinigraf will **NOT** be (by design):\n- **Distributed** - No clustering, no sharding, no replication\n- **Client-server** - No network protocol in core\n- **Enterprise-focused** - No RBAC, no HA, no multi-datacenter\n- **Billion-node scale** - Optimized for \u003c1M nodes (like SQLite)\n\nIf you need these, use Neo4j, TigerGraph, or similar.\n\n## Testing\n\nComprehensive test coverage:\n\n```bash\ncargo test\n```\n\nCurrent tests (123 total):\n- ✅ **94 unit tests** - Core Datalog, EAV model, parser, matcher, executor\n- ✅ **26 integration tests** - Complex queries, recursive rules, concurrency\n- ✅ **3 doc tests** - Inline documentation examples\n\n**Phase 3 Coverage** (Complete):\n- ✅ Datalog parser (EDN syntax)\n- ✅ Recursive rule evaluation (semi-naive)\n- ✅ Transitive closure queries\n- ✅ Pattern matching and unification\n- ✅ Storage backend operations\n- ✅ Concurrency and thread safety\n\n**Future tests** (Phase 4+):\n- ⏳ Bi-temporal queries (:as-of, :valid-at)\n- ⏳ Transaction isolation (ACID)\n- ⏳ Crash recovery (WAL)\n\n## Comparison to Similar Projects\n\n### vs. XTDB (formerly Crux)\n- ✅ **Minigraf**: Single `.graph` file, simpler scope\n- ✅ **XTDB**: More mature, production-ready, but Clojure + multi-file storage\n\n### vs. Cozo\n- ✅ **Minigraf**: Single file, bi-temporal first-class\n- ✅ **Cozo**: More features (vector search, time travel), but multi-file storage\n\n### vs. GraphLite\n- ✅ **Minigraf**: Datalog (recursive rules), bi-temporal\n- ✅ **GraphLite**: Full GQL compliance, but multi-file (Sled directories)\n\n### vs. Datomic\n- ✅ **Minigraf**: Single file, embedded, Rust\n- ✅ **Datomic**: Production-proven, but client-server, Clojure, proprietary\n\n**Minigraf aims to be the simplest, most portable option: SQLite's simplicity + Datomic's temporal model.**\n\n## Contributing\n\nThis is a hobby project with a long-term vision. Contributions welcome, but we prioritize:\n1. Reliability over features\n2. Simplicity over flexibility\n3. Philosophy alignment\n\nSee [ROADMAP.md](ROADMAP.md) and [PHILOSOPHY.md](PHILOSOPHY.md) before proposing features.\n\n## Learning Resources\n\n### Datalog\n- [Learn Datalog Today](http://www.learndatalogtoday.org/)\n- [Datomic Query Tutorial](https://docs.datomic.com/query/query-tutorial.html)\n- [XTDB Datalog Queries](https://xtdb.com/docs/)\n\n### Temporal Databases\n- [Temporal Database Wikipedia](https://en.wikipedia.org/wiki/Temporal_database)\n- [XTDB Bitemporality](https://v1-docs.xtdb.com/concepts/bitemporality/)\n- [Datomic Time Model](https://docs.datomic.com/time/time-model.html)\n\n### SQLite's VFS\n- [SQLite OS Interface](https://www.sqlite.org/vfs.html)\n- [SQLite File Format](https://www.sqlite.org/fileformat.html)\n\n## License\n\nLicensed under either of:\n\n- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)\n- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)\n\nat your option.\n\n### Contribution\n\nUnless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadityamukho%2Fminigraf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadityamukho%2Fminigraf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadityamukho%2Fminigraf/lists"}