Skip to main content
Version: 1.0 (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.

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.

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

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.

Create a collection named "Book"
defradb client collection add '
  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.

Create documents of a given <type> with the function add_<type>. For example, use add_Book to create documents in the Book collection.

Create two new documents of type "Book", returning their title and unique ID
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
    }
  }
'
Result
{
  "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 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).

Retrieve all documents of type Book, returning title and plot
defradb client query '
{
  Book {
    title
    plot
  }
}
'
Result
{
  "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"
      }
    ]
  }
}

The DefraDB Query Language (DQL) is a rich GraphQL-based language supporting relationships, filtering, limiting, sorting, and grouping.

Example query – Filter books by genre and author's name; return 3 ordered by title
{
  Book(
    filter: {
      genre: { _eq: "Fiction" },
      author: { name: { _eq: "George Orwell" } }
    },
    limit: 3,
    order: { "title": ASC }
  ) {
    title
    plot
    author {
      name
    }
  }
}

-> More information on querying documents

Next steps​

Quickstart
Edit this page