overgraph 0.1.0

The fastest embedded graph database — pure Rust, sub-microsecond reads
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133

# Contributing to OverGraph

Thanks for your interest in contributing. This doc covers everything you need to build, test, and submit changes.

## Prerequisites

You'll need:

- **Rust** (stable, 1.75+): https://rustup.rs
- **Node.js** (18+) and npm: for the Node.js connector
- **Python** (3.9+) and pip: for the Python connector
- **maturin**: `pip install maturin` (for building the Python extension)

## Building from source

### Rust core

```bash
cargo build
cargo build --release  # optimized build
```

The `cli` feature flag enables the `overgraph-inspect` binary:

```bash
cargo build --features cli
```

### Node.js connector

```bash
cd overgraph-node
npm install
npm run build        # release build
npm run build:debug  # debug build
```

### Python connector

```bash
cd overgraph-python
pip install maturin
maturin develop      # debug build, installs into current venv
maturin develop --release  # optimized build
```

## Running tests

```bash
# Rust (all tests including integration tests)
cargo test

# Rust with CLI feature tests
cargo test --features cli

# Node.js
cd overgraph-node && npm test

# Python
cd overgraph-python && pytest
```

All tests must pass before submitting a PR. The CI matrix runs on macOS, Linux, and Windows.

## Project structure

```
overgraph/
  src/                  # Rust core library
    engine.rs           # Main database engine
    types.rs            # Data types (Node, Edge, PropValue, etc.)
    wal.rs              # Write-ahead log
    memtable.rs         # In-memory table
    segment_reader.rs   # Reading immutable segments
    segment_writer.rs   # Writing/flushing segments
    manifest.rs         # Manifest management
    encoding.rs         # Binary encoding helpers
    error.rs            # Error types
    bin/                # CLI tools (behind "cli" feature)
  tests/                # Integration tests
  benches/              # Criterion benchmarks
  overgraph-node/       # Node.js connector (napi-rs)
    src/lib.rs          # napi-rs bindings
    __test__/           # Node.js tests
    index.d.ts          # TypeScript declarations
  overgraph-python/     # Python connector (PyO3)
    src/lib.rs          # PyO3 bindings
    python/overgraph/   # Python package (type stubs, async wrapper)
    tests/              # pytest tests
  docs/                 # Documentation
```

## Coding conventions

- **Rust style:** Standard `rustfmt` formatting. Run `cargo fmt` before committing.
- **Error handling:** Use `Result<T, EngineError>` for all fallible operations. Don't panic in library code.
- **Tests:** Every change that touches behavior should have a test. Unit tests go in `#[cfg(test)]` modules alongside the code. Integration tests go in `tests/`.
- **Dependencies:** Minimize external crates. Add a dependency only when it clearly beats a hand-rolled solution. We intentionally keep the dependency tree small for fast compile times and a small binary.
- **No C/C++ dependencies.** The core must stay pure Rust. This is a hard constraint.

## Dual index path

If you're adding a new index type, there's an important invariant to know about. Indexes are written in two places:

1. **Flush path** (`write_segment` in `segment_writer.rs`): builds indexes from the in-memory memtable
2. **Compaction path** (`write_indexes_from_metadata` in `segment_writer.rs`): builds indexes from metadata sidecars

Both paths must produce the same indexes. If you add a new index in the flush path but forget the compaction path, it will work for newly flushed segments but break after compaction. This is the most common source of subtle bugs in the storage engine.

## Submitting a PR

1. Fork the repo and create a branch from `main`.
2. Make your changes. Write tests.
3. Run `cargo test`, `npm test` (in overgraph-node), and `pytest` (in overgraph-python) to make sure everything passes.
4. Run `cargo fmt` to format your Rust code.
5. Open a PR against `main` with a clear description of what you changed and why.

## Reporting bugs

Open an issue with:

- What you expected to happen
- What actually happened
- Steps to reproduce (ideally a minimal code example)
- Your OS, Rust version, and OverGraph version

## Feature requests

Open an issue describing the use case. The more concrete the better: "I'm building X and I need Y because Z" is much more useful than "it would be cool if...".

## License

By contributing, you agree that your contributions will be licensed under both the MIT License and the Apache License 2.0, at the user's option.