obj-db 1.1.2

Embedded document database. Stable file format, full ACID, single-file portability.
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

# obj-db

> The embedded document database for Rust. Dependable. Portable. Zero-infrastructure.

[![crates.io](https://img.shields.io/crates/v/obj-db.svg)](https://crates.io/crates/obj-db)
[![docs.rs](https://docs.rs/obj-db/badge.svg)](https://docs.rs/obj-db)

Part of [`obj`](https://github.com/uname-n/obj) — a self-contained,
serverless, single-file document database with a stable file format and
full ACID semantics. It is to document storage what SQLite is to
relational storage.

Crate name `obj-db`; import as `obj`.

**Stability.** v1.0 froze the on-disk format (`format_major = 1`) and the
public Rust API under strict SemVer. Backwards-incompatible changes
require a 2.0 release with a migration tool; readers still open pre-1.0
(`format_major = 0`) files.

---

## Quickstart

```toml
# Cargo.toml
[dependencies]
obj-db = "1.0"
serde = { version = "1", features = ["derive"] }
```

```rust
use obj::Db;
use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize, obj::Document)]
struct Order {
    customer_id: u64,
    total_cents: u64,
}

fn main() -> obj::Result<()> {
    let dir = tempfile::tempdir()?;
    let db = Db::open(dir.path().join("app.obj"))?;
    let id = db.insert(Order { customer_id: 1, total_cents: 4_200 })?;
    let back: Order = db
        .get::<Order>(id)?
        .ok_or(obj::Error::InvalidArgument("just inserted"))?;
    assert_eq!(back.total_cents, 4_200);
    Ok(())
}
```

Collection name and schema version default to the type name and `1`;
override with `#[obj(collection = "...", version = N)]`. See the docs
for queries, indexes, transactions, and migrations.

---

## Features

All features are off by default — enable with
`cargo add obj-db --features <name>`.

| Feature       | What it does                                                                 |
|---------------|------------------------------------------------------------------------------|
| `serde`       | Derive `Serialize`/`Deserialize` on public types; re-export both traits.     |
| `tracing`     | Structured spans around open, transactions, queries, and checkpoints.        |
| `compression` | LZ4 per-page compression at the pager layer.                                 |
| `encryption`  | ChaCha20-Poly1305 per-page at-rest encryption.                               |
| `async`       | Runtime-agnostic `obj::asynchronous` mirror of the blocking API.             |

See [docs.rs/obj-db](https://docs.rs/obj-db) for per-feature details.

---

## Documentation

- [docs.rs/obj-db](https://docs.rs/obj-db) — canonical API docs, with
  worked examples on every public type.
- [Project README](https://github.com/uname-n/obj) — overview, other
  bindings, and the full documentation index.
- [Format spec](https://github.com/uname-n/obj/blob/master/docs/format.md)
  · [Concurrency model](https://github.com/uname-n/obj/blob/master/docs/concurrency.md)

---

## License

Dual-licensed under [MIT](https://github.com/uname-n/obj/blob/master/LICENSE-MIT)
or [Apache 2.0](https://github.com/uname-n/obj/blob/master/LICENSE-APACHE),
at your option.