How Dialog Works
Dialog is an embeddable database for local-first software. Every peer, such as a laptop or a phone, keeps its own working copy of each repository it uses, called a replica. An app reads and writes its replica directly, with no server in the way. When two replicas can both reach a storage service they share, they exchange what changed through it and end up agreeing.
This guide follows one piece of data through the whole system. It starts when an app writes a fact, follows that fact into a sorted tree of keys and down to the bytes on disk, and then carries it to another device, where it is merged and queried. Each chapter picks up where the previous one left off.
The guide is written for two kinds of readers. If you want to build something that talks to Dialog, or write a second implementation, you should find enough detail here to get started. If you are just curious how a local-first database can work, you can skip the byte tables and still follow the story.
Alice and Bob’s grocery list
Alice and Bob share a grocery list. Alice edits it on her laptop. Bob edits it on his phone. Sometimes they are both offline, and sometimes they edit the same item at the same time.
The same list appears in every chapter, so the same facts, keys and hashes turn up again and again. By the end you will have seen one grocery item as a sentence, as three keys, as a leaf in a tree, as bytes in a block, as an entry in a signed history, and as a row in a query result.
What the guide covers
- Facts: the one shape all data takes.
- Keys: how a fact becomes sortable bytes, three times over.
- The Search Tree: how sorted keys are cut into nodes so that equal data gives equal trees.
- Nodes: the bytes of a single node, and how a node says how to read itself.
- Blocks and Storage: content addressing, and where blocks live.
- Commits and History: versions, the log inside the tree, and signed heads.
- Identity and Capabilities: who may read and write, and how a remote peer checks.
- Sync: how Alice’s and Bob’s replicas converge.
- Queries: how an app asks questions of all this.
How to read the diagrams. Colors mean the same thing in every diagram:
- entity the thing a fact is about
- attribute what is said about it
- value what is said
- hash content addresses, signatures and other machinery
- critical something a reader must understand, or refuse
- Alice and Bob their replicas and everything they write
Bytes are drawn as boxes holding two hexadecimal digits. Where a byte is a printable character, the character is shown and its hex value sits beneath it. A bracket under a run of bytes names the field those bytes make up.
Status. Dialog is experimental. The formats described here, including the node layout, are drafts and may change before a stable release. Where the guide describes something that is still moving, it says so. The implementation lives in the dialog-db repository, and each chapter links to the code it describes.