DefraDB is a user-centric database that prioritizes data ownership, personal privacy, and information security. Its data model, powered by the convergence of MerkleCRDTs and the content-addressability of IPLD, enables a multi-write-master architecture. It features DQL, a query language compatible with GraphQL but providing extra convenience. By leveraging peer-to-peer networking it can be deployed nimbly in novel topologies. Access control is determined by a relationship-based DSL, supporting document or field-level policies, secured by the SourceHub network. DefraDB is a core part of the Source technologies that enable new paradigms of decentralized data and access-control management, user-centric apps, data trustworthiness, and much more.

Read the documentation on docs.source.network.

Install
Build Requirements
- Prerequisites
- System Resources
- Building on Resource-Constrained Systems
Key Management
Start
Configuration
External port binding
Add a collection
Add a document
Query documents
Obtain document commits
DefraDB Query Language (DQL)
Peer-to-peer data synchronization
Securing the HTTP API with TLS
Access Control System
Supporting CORS
Backing up and restoring
Telemetry
Community
Playground
Licensing
Contributors

DISCLAIMER: The software is provided "as is" and is not guaranteed to be stable, secure, or error-free. We encourage you to experiment with DefraDB and provide feedback, and when you plan to deploy it to production, please thoroughly test your integrations.

Install

Install defradb by downloading an executable or building it locally using the Go toolchain:

git clone https://github.com/sourcenetwork/defradb.git
cd defradb
make install

In the following sections, we assume that defradb is included in your PATH. If you installed it with the Go toolchain, use:

export PATH=$PATH:$(go env GOPATH)/bin

We recommend experimenting with queries using a native GraphQL client. GraphiQL is a popular option - download and install it.

Build Requirements

Building DefraDB from source requires significant system resources. If you encounter out-of-memory errors or build failures, review the requirements below.

Prerequisites

Go 1.24 or later
Rust toolchain (for WASM lens compilation, if running tests)
Git

System Resources

| Resource | Minimum | Recommended | |----------|---------|-------------| | RAM | 2 GB | 4+ GB | | Disk Space | 3 GB | 5+ GB |

The Go compiler requires substantial memory during compilation. Builds with less than 2 GB of available RAM will likely fail with out-of-memory errors.

Building on Resource-Constrained Systems

If you're building on a system with limited RAM (e.g., a small VM or container), you may encounter build failures. Common issues and solutions:

Out of Memory (OOM) errors:

Ensure at least 2 GB of RAM is available
Add swap space if physical RAM is limited
Use -p 1 to limit compiler parallelism: go build -p 1 ./cmd/defradb

/tmp running out of space: On systems where /tmp is a small tmpfs (RAM-backed filesystem), the Go compiler may exhaust available space. Redirect Go's temp directories to a location with more space:

export GOTMPDIR=/path/with/space
export GOCACHE=/path/with/space/go-cache
export GOMODCACHE=/path/with/space/go-mod

Reducing memory usage: For extremely constrained environments, disable optimizations (produces slower binary):

go build -p 1 -gcflags="all=-N -l" ./cmd/defradb

Key Management

DefraDB has a built in keyring that can be used to store private keys securely.

The following keys are loaded from the keyring on start:

peer-key Ed25519 private key (required)
encryption-key AES-128, AES-192, or AES-256 key (optional)
node-identity-key Secp256k1 private key (optional). This key is used for node's identity.

A secret to unlock the keyring is required on start and must be provided via the DEFRA_KEYRING_SECRET environment variable. If a .env file is available in the working directory, the secret can be stored there or via a file at a path defined by the --secret-file flag.

The keys will be randomly generated on the initial start of the node if they are not found.

Alternatively, to randomly generate the required keys, run the following command:

Node identity is an identity assigned to the node. It is used to exchange encryption keys with other nodes.

defradb keyring new

To import externally generated keys, run the following command:

defradb keyring add <name> <private-key-hex>

To learn more about the available options:

defradb keyring --help

Start

Start a node by executing defradb start. Keep the node running while going through the following examples.

Verify the local connection to the node works by executing defradb client collection describe in another terminal.

Configuration

In this document, we use the default configuration, which has the following behavior:

~/.defradb/ is DefraDB's configuration and data directory
client command interacts with the locally running node
The GraphQL endpoint is provided at http://localhost:9181/api/graphql and a versioned API endpoint is provided at http://localhost:9181/api/v1/graphql

The GraphQL endpoint can be used with a GraphQL client (e.g., Altair) to conveniently perform requests (query, mutation) and obtain schema introspection.

External port binding

By default the HTTP API and P2P network will use localhost. If you want to expose the ports externally you need to specify the addresses in the config or command line parameters.

defradb start --p2paddr /ip4/0.0.0.0/tcp/9171 --url 0.0.0.0:9181

Add a collection

Collections are used to structure documents using a type system.

In the following examples, we'll be using a simple User type.

Add it to the database with the following command. By doing so, DefraDB generates the typed GraphQL endpoints for querying, mutation, and introspection.

defradb client collection add '
  type User {
    name: String
    age: Int
    verified: Boolean
    points: Float
  }
'

Find more examples of type definitions in the examples/collection/ folder.

Add a document

Submit a mutation request to add a document of the User type:

defradb client query '
  mutation {
      add_User(input: {age: 31, verified: true, points: 90, name: "Bob"}) {
          _docID
      }
  }
'

Expected response:

{
  "data": {
    "add_User": [
      {
        "_docID": "bae-91171025-ed21-50e3-b0dc-e31bccdfa1ab",
      }
    ]
  }
}

_docID is the document's unique identifier determined by its collection and initial data.

Query documents

Once you have populated your node with data, you can query it:

defradb client query '
  query {
    User {
      _docID
      age
      name
      points
    }
  }
'

This query obtains all users and returns their fields _docID, age, name, points. GraphQL queries only return the exact fields requested.

You can further filter results with the filter argument.

defradb client query '
  query {
    User(filter: {points: {_geq: 50}}) {
      _docID
      age
      name
      points
    }
  }
'

This returns only user documents which have a value for the points field Greater Than or Equal to (_ge) 50.

Obtain document commits

DefraDB's data model is based on MerkleCRDTs. Each document has a graph of all of its updates, similar to Git. The updates are called commits and are identified by cid, a content identifier. Each references its parents by their cids.

To get the most recent commit in the MerkleDAG for the document identified as bae-91171025-ed21-50e3-b0dc-e31bccdfa1ab:

defradb client query '
  query {
    _

Defradb

Install / Use

README

Table of Contents