Skip to main content
Version: 1.0 RC1 (Latest)

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.

For more background on the local-first paradigm, see The Edge-First Awakening: Redefining the Foundations of Modern Computing.

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 DefraBD in a few different ways. Most actions can be run with all tools, but some are not available on all options.

The client CLI commands allow to interact with an instance from the command line.

Add collections​

Collections are the types into which documents fit, like tables in SQL. Because every document belongs to a collection, you need to create collections before you can insert any data. A collection has a name (ex. Book) and a number of typed fields (ex. title: String).

You can create a collection with the CLI command defradb client collection add.

defradb client collection add '
  type Book {
    title: String!
    plot: String
    rating: Float
  }
'

-> More information on collections

Create documents​

To create documents of type <type>, use the mutation add_<type> via the CLI command defradb client query. For example, to create a document in the Book collection, use add_Book.

Every add_<type> mutation must return some of the inserted information. Because GraphQL queries only return the exact fields requested, you have to provide a list of return fields (there is no equivalent of the SQL SELECT * syntax).

Create a new document of type Book
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
    }) {
      _docID
      title
    }
    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
    }) {
      _docID
      title
    }
  }
'
Result
{
  "data": {
    "b1": [
      {
        "_docID": "bae-546ae840-77c7-51a5-ab0a-b5a893bfa546",
        "title": "1984"
      }
    ],
    "b2": [
      {
        "_docID": "bae-6c91c35c-e548-58f8-86a6-d60ab5174072",
        "title": "Lord of the Flies"
      }
    ]
  }
}

_docID is the document's unique identifier, determined by the collection it belongs to and the data it is initialized with.

-> More information on creating documents

Query documents​

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. _docID, title, plot).

You can run a query via the CLI command defradb client query.

Retrieve all documents of type Book, returning docID, title, plot
defradb client query '
{
  Book {
    _docID
    title
    plot
  }
}
'
Result
{
  "data": {
    "Book": [
      {
        "_docID": "bae-526a42c6-c147-57e4-89e0-875d27a1532d",
        "plot": "A masterpiece of rebellion and imprisonment where war is peace, freedom is slavery, and Big Brother is watching.",
        "title": "1984"
      },
      {
        "_docID": "bae-9579541e-f15d-506e-a74a-63d00cb3ab56",
        "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

Quickstart
Edit this page