ECHO Database
ECHO Database
ECHO (The Eventually Consistent Hierarhical Object store) is a peer-to-peer graph database written in TypeScript.
- Secure, P2P data replication based on CRDTs.
- No servers or central authority, all the data is with the clients.
- Connectivity with peers via WebRTC.
- Support for multiple concurrent writers.
- Collaboration on key-value objects, bodies of text, and other "custom data models".
- Support for offline writes and conflict resolution when peers rejoin the network.
Tell us what you think
Join our Discord and talk to us about the kind of database you are looking for.
Spaces
Spaces are units of sharing and access control in ECHO. They are equivalent to "collections" in a document store.
A space
is an instance of an ECHO database which can be replicated by a number of peers.
A given peer is typically a part of many spaces at any given time.
There are several steps to establishing a space between peers:
- Peer A listens on the peer network for peers intereseted in a specific invite code it generated.
- Peer B obtains the invite code and locates the listening Peer A via the signaling network.
- Peer A and Peer B establish a secure connection via Diffie Hellmann key exchange.
- Peer A generates an authorization code and sends it to Peer B via another safe channel (i.e.: shows a QR code).
- Finally, Peer B provides the authorization code back to Peer A over the new connection.
This verifies that the connection is secure, and the identities of peers are mutually confirmed.
Tip
If you're using react
, DXOS provides a simple UI flow that implements generating and accepting invitations to spaces.
Next steps:
- Create or join a space in TypeScript
- Create or join a space in React
Objects
Units of data are referred to as objects
(like documents or rows in other databases). Objects
always belong to a space. Objects can have fields with values, and strong relationships to other objects to form trees or graphs.
Glossary
See the glossary for definitions of other terms you'll find in this guide.
How to use ECHO
- Install the appropriate npm package
@dxos/client
or@dxos/react-client
- Create a Client (or a ClientProvider in react)
- Set up an identity with HALO
- Create or Join a Space
- Query objects (in react)
- Create objects (in react)
- Mutate objects (in react)
Local Vault Topology
ECHO is uniquely organized to give control over information to the end-user and their devices.
Browsers isolate web apps running on different domains, and this property is used to isolate the main vault
of storage to a specific domain. By default that's HALO on halo.dxos.org
but developers are free to operate their own copies of HALO on their local machine (e.g. using KUBE), their local network, or any other domain.
The vault domain is responsible for holding end-user identity (keys, credentials, metadata, ..., etc.) and all ECHO data in persistent browser or disk storage. It exposes this data to applications via an API over postMessage
.
A service worker and the CRDT-based architecture of ECHO enable both offline and real-time collaboration.
This means that when apps request the user's identity (ask to log in), they are in fact obtaining a secure identifier from the local HALO application directly, without making any network calls. Any reads and writes end up storing data in a database owned by the halo.dxos.com
application, which serves as an identity wallet and data vault where specific devices or applications can be revoked from accessing user data at any time.
Note
For Node.js applications, the vault is implemented by an in-process storage engine that persists to files on disk, and is not isolated from the consuming application the way it is in browser.
Note
The vault relies on worker ES modules and as such is not yet functional in Firefox. The feature is currently under development however, currently behind the about:config
preference dom.workers.modules.enabled
. The hope and expectation is that this should be enabled by default in the not-too-distant future.
Next steps
- If using
react
see the React guide - Otherwise, follow the TypeScript guide