mirror of
https://github.com/matrix-construct/construct
synced 2024-11-05 05:18:54 +01:00
52 lines
2.4 KiB
Markdown
52 lines
2.4 KiB
Markdown
## IRCd Database
|
|
|
|
The database is an object store built from the primitives of `cell`, `column`, and `row`.
|
|
|
|
#### Columns
|
|
While a simple key-value store could naively store a JSON document as a textual
|
|
value, we provide additional structure schematized before opening a database:
|
|
Every member of a JSON object is a `column` in this database. To address members
|
|
within nested objects, we specify a `column` with a "foo.bar.baz" path syntax. This
|
|
puts all columns at the same level in our code, even though they may represent
|
|
deeply nested values.
|
|
|
|
#### Rows
|
|
Since `columns` are technically independent key-value stores (they have their own
|
|
index), when an index key is the same between columns we call this a `row`. For basic
|
|
object storage the schema is such that we use the same keys between all columns. For
|
|
example, an index would be a username in a user database. The user database itself
|
|
takes the form of a single JSON object and any member lookup happens on a user's row.
|
|
|
|
#### Cells
|
|
A `cell` is a single value in a `column` indexed by a key that should be able to form
|
|
a `row` between columns. Consider the following near-json expression:
|
|
|
|
users["root"] = {"password", "foobar"};
|
|
|
|
In the users database, we find the `column` "password" and the `row` for "root" and
|
|
set that `cell` to "foobar"
|
|
|
|
Consider these expressions for objects at some depth:
|
|
|
|
users["root"] = {"password.plaintext", "foobar"};
|
|
users["root"] = {"password", {"plaintext, "foobar"}};
|
|
|
|
The column is always found as "password.plaintext". We find it (and can iterate its members
|
|
if it were an object) by string-manipulating these full paths which all sit in a single map
|
|
and are always open, even if the cell is empty for some row.
|
|
|
|
### Important notes
|
|
|
|
!!!
|
|
The database system is plugged into the userspace context system to facilitate IO. This means
|
|
that an expensive database call (mostly on the read side) that has to do disk IO will suspend
|
|
your userspace context. Remember that when your userspace context resumes on the other side
|
|
of the call, the state of IRCd and even the database itself may have changed. We have a suite
|
|
of tools to mitigate this.
|
|
!!!
|
|
|
|
* While the database schema is modifiable at runtime (we can add and remove columns on
|
|
the fly) the database is very picky about opening the exact same way it last closed.
|
|
This means, for now, we have the full object schema explicitly specified when the DB
|
|
is first opened. All columns exist for the lifetime of the DB, whether or not you have
|
|
a handle to them.
|