Skip to content

Commit 1481dc1

Browse files
docs: add README to AccountsDB (#357)
<!-- greptile_comment --> ## Greptile Summary Added a new README.md file documenting the AccountsDB component, which provides essential documentation for the database's features and API methods. <!-- /greptile_comment --> closes gh-330 --------- Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
1 parent dccc8c3 commit 1481dc1

File tree

1 file changed

+43
-0
lines changed

1 file changed

+43
-0
lines changed

magicblock-accounts-db/README.md

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Accounts Database Manager
2+
3+
The AccountsDB is a crucial component of the Magicblock Validator. It handles
4+
the storage, retrieval, and management of account data. It's highly optimized
5+
to provide efficient account search and retrieval, using memory mapped storage,
6+
while still being persisted to disk.
7+
8+
## Features
9+
10+
- **Account Storage**: Efficient storage of account records, with support for
11+
both owned and borrowed account data. By default accounts are read directly
12+
from memory mapping without any deserialization and/or allocation, as
13+
consequence it allows for direct memory modification in situ in the database,
14+
avoiding read modify write overhead. But this imposes a strict requirement, that
15+
no two threads have access to the same account at the same time for
16+
modification, which is naturally achieved with account locking when executing
17+
transactions. But any other way to hold onto borrowed state of account is
18+
prohibited, as it will inevitably cause an undefined behavior.
19+
- **Index Management**: Fast index-based lookups for account data.
20+
LMDB is used for the purposes of indexing, where several different mappings
21+
are maintained to support database integrity.
22+
- **Snapshot Management**: Automated snapshot creation to enable rollbacks to
23+
previous states of the database if necessary.
24+
- **Concurrency Control**: Uses a "Stop the World" lock to ensure data
25+
consistency during critical operations like snapshotting. This prevents any
26+
writes to the database while it's being manipulated at the OS level.
27+
- **Program Account Scanning**: Retrieve and filter accounts associated with a
28+
specific program, the scanning happens without deserializing anything from the
29+
database.
30+
31+
## Main API methods
32+
33+
- **Initialization**: Use `AccountsDb::new` to create or open an accounts
34+
database instance.
35+
- **Account Operations**: Use `get_account`, `insert_account`,
36+
`contains_account` to read, write, or check the existence of accounts.
37+
- **Snapshot Operations**: Schedule and manage snapshots with `set_slot`, which
38+
might trigger snapshot operation, which in turn involves locking everything
39+
down, thus snapshot frequency should be set to sane value. And retrieve
40+
snapshot slots using `get_latest_snapshot_slot` and
41+
`get_oldest_snapshot_slot`.
42+
- **Database Integrity**: Use `ensure_at_most` to ensure database state up to a
43+
specific slot, with rollback to previously taken snapshot if needed.

0 commit comments

Comments
 (0)