Quickstart
DefraDB is the database for local-first applications that prioritizes data ownership, personal privacy, and P2P synchronization. It features data encryption and verification, the ability to travel in time through the history of documents, and a multi-write-master architecture. The DefraDB Query Language (DQL) is based on GraphQL.
Install
Get defradb by downloading the executable appropriate to your system.
Define a secret for DefraDB's keyring and start the local node:
DEFRA_KEYRING_SECRET=<secret> defradb start
To verify the local connection to the node, ping the /health-check HTTP endpoint:
wget -qO- http://localhost:9181/health-check
An online node responds with "Healthy".
-> More information and install options
Interact with the database
You can interact with DefraDB in a few ways. Most actions can be run with all tools, but some are not available on all options.
- CLI
- HTTP API
- GraphQL
- Explorer
The client CLI commands allow to interact with an instance from the command line.
The HTTP API is available at http://localhost:9181/api/v1/.
The versionless endpoint at http://localhost:9181/api/ points to the latest version.
GraphQL clients (ex. Altair) are a popular option to interact with the GraphQL API.
The GraphQL endpoint is available at http://localhost:9181/api/v1/graphql.
The versionless endpoint at http://localhost:9181/api/graphql points to the latest version.
The DefraDB Explorer is a web application available at http://localhost:9181, and also hosted at https://explorer.source.network/. It provides a GraphQL client and an interface to the most common instance management operations.
Add collections
Collections are the types into which documents fit: they describe the database schema. You need to create collections before you can insert any data. A collection has a name and a number of typed fields.
- CLI
- HTTP API
defradb client collection add '
type Book {
title: String!
plot: String
rating: Float
}
'
POST http://localhost:9181/api/v1/collections HTTP/2
accept: application/json
content-type: text/plain
type Book {
title: String!
plot: String
rating: Float
}
-> More information on collections
Create documents
DefraDB stores data in documents. You can think that a document is of a specific type, or that it belongs to a specific collection: they are two sides of the same coin.
- CLI
- HTTP API
- GraphQL
Create documents of a given <type> with the function add_<type>. For example, use add_Book to create documents in the Book collection.
defradb client query '
mutation {
b1:add_Book(input: {
title: "1984",
plot: "A masterpiece of rebellion and imprisonment where war is peace, freedom is slavery, and Big Brother is watching.",
rating: 4.20
}) {
title
plot
}
b2:add_Book(input: {
title: "Lord of the Flies",
plot: "At the dawn of the next world war, a plane crashes on an uncharted island, stranding a group of schoolboys.",
rating: 3.70
}) {
title
plot
}
}
'
{
"data": {
"b1": [
{
"plot": "A masterpiece of rebellion and imprisonment where war is peace, freedom is slavery, and Big Brother is watching.",
"title": "1984"
}
],
"b2": [
{
"plot": "At the dawn of the next world war, a plane crashes on an uncharted island, stranding a group of schoolboys.",
"title": "Lord of the Flies"
}
]
}
}
Create documents of a given <type> via the HTTP endpoint /api/v1/collections/<type>. For example, use /api/v1/collections/Book to create documents in the Book collection.
POST http://localhost:9181/api/v1/collections/Book HTTP/2
accept: application/json
content-type: application/json
[
{
"title": "1984",
"plot": "A masterpiece of rebellion and imprisonment where war is peace, freedom is slavery, and Big Brother is watching.",
"rating": 4.20
},
{
"title": "Lord of the Flies",
"plot": "At the dawn of the next world war, a plane crashes on an uncharted island, stranding a group of schoolboys.",
"rating": 3.70
}
]
Create documents of a given <type> with the function add_<type>. For example, use add_Book to create documents in the Book collection.
mutation {
b1:add_Book(input: {
title: "1984",
plot: "A masterpiece of rebellion and imprisonment where war is peace, freedom is slavery, and Big Brother is watching.",
rating: 4.20
}) {
title
plot
}
b2:add_Book(input: {
title: "Lord of the Flies",
plot: "At the dawn of the next world war, a plane crashes on an uncharted island, stranding a group of schoolboys.",
rating: 3.70
}) {
title
plot
}
}
{
"data": {
"b1": [
{
"plot": "A masterpiece of rebellion and imprisonment where war is peace, freedom is slavery, and Big Brother is watching.",
"title": "1984"
}
],
"b2": [
{
"plot": "At the dawn of the next world war, a plane crashes on an uncharted island, stranding a group of schoolboys.",
"title": "Lord of the Flies"
}
]
}
}
-> More information on creating documents
Query documents
The DefraDB Query Language (DQL) is a rich GraphQL-based language supporting relationships, filtering, limiting, sorting, and grouping.
The basic skeleton of a query is made of the collection you want to fetch from (ex. Book) and the fields you want to return (ex. title, plot).
- CLI
- HTTP API
- GraphQL
defradb client query '
{
Book {
title
plot
}
}
'
{
"data": {
"Book": [
{
"plot": "A masterpiece of rebellion and imprisonment where war is peace, freedom is slavery, and Big Brother is watching.",
"title": "1984"
},
{
"plot": "At the dawn of the next world war, a plane crashes on an uncharted island, stranding a group of schoolboys.",
"title": "Lord of the Flies"
}
]
}
}
POST http://localhost:9181/api/v1/graphql HTTP/2
accept: application/json
content-type: application/json
{
"query": "{ Book { title plot } }"
}
{
"data": {
"Book": [
{
"plot": "A masterpiece of rebellion and imprisonment where war is peace, freedom is slavery, and Big Brother is watching.",
"title": "1984"
},
{
"plot": "At the dawn of the next world war, a plane crashes on an uncharted island, stranding a group of schoolboys.",
"title": "Lord of the Flies"
}
]
}
}
{
Book {
title
plot
}
}
{
"data": {
"Book": [
{
"plot": "A masterpiece of rebellion and imprisonment where war is peace, freedom is slavery, and Big Brother is watching.",
"title": "1984"
},
{
"plot": "At the dawn of the next world war, a plane crashes on an uncharted island, stranding a group of schoolboys.",
"title": "Lord of the Flies"
}
]
}
}
-> More information on querying documents
Explore the history of documents
In DefraDB, each document has a tree of all of its updates: every update creates commits, forming a history of changes that leads to the document's current state. Because commits are linked with cryptographically secure identifiers, the structure of the chain guarantees data integrity by design. The _version field allows you to inspect and navigate to earlier versions of every document.
{
Book(
filter: { title: { _eq: "1984" } }
) {
title
_version {
fieldName
cid
height
links {
fieldName
delta
}
}
}
}
{
"data": {
"Book": [
{
"_version": [
{
"cid": "bafyreicnnmfpjj7gcpzhr7sdtwsyroheuy4ecev4gkaw5zqth7x7ptfyni",
"fieldName": "_C",
"height": 1,
"links": [
{
"delta": "ZDE5ODQ=",
"fieldName": "title"
},
{
"delta": "eHBBIG1hc3RlcnBpZWNlIG9mIHJlYmVsbGlvbiBhbmQgaW1wcmlzb25tZW50IHdoZXJlIHdhciBpcyBwZWFjZSwgZnJlZWRvbSBpcyBzbGF2ZXJ5LCBhbmQgQmlnIEJyb3RoZXIgaXMgd2F0Y2hpbmcu",
"fieldName": "plot"
},
{
"delta": "+0AQzMzMzMzN",
"fieldName": "rating"
}
]
}
],
"title": "1984"
}
]
}
}
-> More information on time traveling queries