fjall 3.0.0

Log-structured, embeddable key-value storage engine
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
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205

<p align="center">
  <img src="/kawaii.png" height="200">
</p>

<p align="center">
  <a href="https://github.com/fjall-rs/fjall/actions/workflows/test.yml">
    <img src="https://github.com/fjall-rs/fjall/actions/workflows/test.yml/badge.svg" alt="CI" />
  </a>
  <a href="https://docs.rs/fjall">
    <img src="https://img.shields.io/docsrs/fjall?color=green" alt="docs.rs" />
  </a>
  <a href="https://crates.io/crates/fjall">
    <img src="https://img.shields.io/crates/v/fjall?color=blue" alt="Crates.io" />
  </a>
  <img src="https://img.shields.io/badge/MSRV-1.91.0-blue" alt="MSRV" />
  <a href="https://deps.rs/repo/github/fjall-rs/fjall">
    <img src="https://deps.rs/repo/github/fjall-rs/fjall/status.svg" alt="dependency status" />
  </a>
</p>

<p align="center">
  <a href="https://discord.com/invite/HvYGp4NFFk">
    <img src="https://img.shields.io/discord/1240426554111164486" alt="Discord" />
  </a>
  <a href="https://bsky.app/profile/fjallrs.bsky.social">
    <img src="https://img.shields.io/badge/bluesky-blue" alt="Bluesky" />
  </a>
</p>

*Fjall* _(Nordic: "Mountain")_ is a log-structured, embeddable key-value storage engine written in Rust.
It features:

- A thread-safe BTreeMap-like API
- 100% safe & stable Rust
- LSM-tree-based storage similar to `RocksDB`
- Range & prefix searching with forward and reverse iteration
- Multiple keyspaces (a.k.a. column families) with cross-keyspace atomic semantics
- Built-in compression (default = `LZ4`)
- Serializable transactions (optional)
- Key-value separation for large blob use cases (optional)
- Automatic background maintenance

It is not:

- A standalone database server
- A relational or wide-column database: it has no built-in notion of columns or query language

## Sponsors

<a href="https://sqlsync.dev">
  <picture>
    <source width="240" alt="Orbitinghail" media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/fjall-rs/fjall-rs.github.io/d22fcb1e6966ce08327ea3bf6cf2ea86a840b071/public/logos/orbitinghail.svg" />
    <source width="240" alt="Orbitinghail" media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/fjall-rs/fjall-rs.github.io/d22fcb1e6966ce08327ea3bf6cf2ea86a840b071/public/logos/orbitinghail_dark.svg" />
    <img width="240" alt="Orbitinghail" src="https://raw.githubusercontent.com/fjall-rs/fjall-rs.github.io/d22fcb1e6966ce08327ea3bf6cf2ea86a840b071/public/logos/orbitinghail_dark.svg" />
  </picture>
</a>

## Basic usage

```bash
cargo add fjall
```

```rust
use fjall::{PersistMode, Database, KeyspaceCreateOptions};

// A database may contain multiple keyspaces
// You should probably only use a single database for your application
let db = Database::builder(folder).open()?;
// TxDatabase::builder for transactional semantics

// Each keyspace is its own physical LSM-tree, and thus isolated from other keyspaces
let items = db.keyspace("my_items", KeyspaceCreateOptions::default)?;

// Write some data
items.insert("a", "hello")?;

// And retrieve it
let bytes = items.get("a")?;

// Or remove it again
items.remove("a")?;

// Search by prefix
for kv in items.prefix("prefix") {
  // ...
}

// Search by range
for kv in items.range("a"..="z") {
  // ...
}

// Iterators implement DoubleEndedIterator, so you can search backwards, too!
for kv in items.prefix("prefix").rev() {
  // ...
}

// Sync the journal to disk to make sure data is definitely durable
// When the database is dropped, it will try to persist with `PersistMode::SyncAll` automatically
keyspace.persist(PersistMode::SyncAll)?;
```

> [!TIP]
> Like any typical key-value store, keys are stored in lexicographic order.
> If you are storing integer keys (e.g. timeseries data), you should use the big endian form to have predictable ordering.

## Durability

To support different kinds of workloads, Fjall is agnostic about the type of durability
your application needs.
After writing data (`insert`, `remove` or committing a write batch/transaction), you can choose to call [`Database::persist`](https://docs.rs/fjall/latest/fjall/struct.Database.html#method.persist) which takes a [`PersistMode`](https://docs.rs/fjall/latest/fjall/enum.PersistMode.html) parameter.
By default, any operation will flush to OS buffers, but **not** to disk.
This matches RocksDB's default durability.
Also, when dropped, the database will try to persist the journal *to disk* synchronously.

## Multithreading, Async and Multiprocess

> [!WARNING]
> A single database may **not** be loaded in parallel from separate *processes*.

Fjall is internally synchronized for multi-*threaded* access, so you can clone around the `Database` and `Keyspace`s as needed, without needing to lock yourself.

For an async example, see the [`tokio`](https://github.com/fjall-rs/fjall/tree/main/examples/tokio) example.

## Memory usage

Generally, memory for loaded data, indexes etc. is managed on a per-block basis, and capped by the block cache capacity.
Note that this also applies to returned values: When you hold a `Slice`, it keeps the backing buffer alive (which may be a block).
If you know that you are going to keep a value around for a long time, you may want to copy it out into a new `Vec<u8>`, `Box<[u8]>`, `Arc<[u8]>` or new `Slice` (using `Slice::new`).

> [!NOTE]
> It is recommended to configure the block cache capacity to be ~20-25% of the available memory - or more **if** the data set fits _fully_ into memory.

Additionally, orthogonally to the block cache, each `Keyspace` has its own write buffer (["Memtable"](https://docs.rs/fjall/latest/fjall/struct.KeyspaceCreateOptions.html#method.max_memtable_size)) which is the unit of data flushed back into the "proper" index structure.
The sum of all write buffers are capped by the database-wide [`max_write_buffer_size`](https://docs.rs/fjall/latest/fjall/struct.DatabaseBuilder.html#method.max_write_buffer_size).

## Error handling

Fjall returns an [error enum](https://docs.rs/fjall/latest/fjall/enum.Error.html), however these variants are mostly used for debugging and tracing purposes, so your application is not expected to handle specific errors.

It's best to let the application crash and restart, which is the [safest way to recover from transient I/O errors](https://ramalagappan.github.io/pdfs/papers/cuttlefs.pdf).

## Transactional modes

The backing store (`lsm-tree`) is a MVCC key-value store, allowing repeatable snapshot reads.
However this isolation level can not do read-modify-write operations without the chance of lost updates.
Also, `WriteBatch` does not allow reading the intermediary state back as you would expect from a proper transaction.
For that reason, if you need transactional semantics, you need to use one of the transactional database implementation (`OptimisticTransactionDatabase` or `SingleWriterTransactionDatabase`).

TL;DR: Fjall supports both transactional and non-transactional workloads.
Chances are you want to use a transactional database, unless you know your workload does not need serializable transaction semantics.

### Single writer

Opens a transactional database for single-writer (serialized) transactions.
Single writer means only a single **write** transaction can run at a time.
This is trivially serializable because it _literally_ serializes write transactions.

### Optimistic

Opens a transactional database for multi-writer, serializable transactions.
Conflict checking is done using optimistic concurrency control, meaning transactions can conflict and may have to be rerun.

## Feature flags

### lz4

Allows using `LZ4` compression, powered by [`lz4_flex`](https://github.com/PSeitz/lz4_flex).

*Enabled by default.*

### bytes_1

Uses [`bytes`](https://github.com/tokio-rs/bytes) 1.x as the underlying `Slice` type.
Otherwise, [`byteview`](https://github.com/fjall-rs/byteview) is used instead.

*Disabled by default.*

## Stable disk format

Future breaking changes will result in a major version bump and a migration path.

For the underlying LSM-tree implementation, see: <https://crates.io/crates/lsm-tree>.

## Examples

[See here](https://github.com/fjall-rs/fjall/tree/main/examples) for practical examples.

## Contributing

How can you help?

- [Ask a question](https://github.com/fjall-rs/fjall/discussions/new?category=q-a)
  - or join the Discord server: [https://discord.com/invite/HvYGp4NFFk](https://discord.com/invite/HvYGp4NFFk)
- [Post benchmarks and things you created](https://github.com/fjall-rs/fjall/discussions/new?category=show-and-tell)
- [Open a PR](https://github.com/fjall-rs/fjall/compare), 
  - [See open issues to pick up here](https://github.com/search?q=org%3Afjall-rs+label%3A%22help+wanted%22+state%3Aopen+&type=issues)
- [Open an issue](https://github.com/fjall-rs/fjall/issues/new) (bug report, weirdness)

## License

All source code is licensed under MIT OR Apache-2.0.

All contributions are to be licensed as MIT OR Apache-2.0.