Barrel DocDB¶

A document database built in Erlang. Embed it in your app or run it standalone over HTTP.

Sync anywhere. Query anything. Your data, wherever you need it.

Quick Start

Get up and running in 5 minutes with our step-by-step guide

Quick Start Guide
Declarative Queries

Query documents with automatic path indexing and powerful filters

Query Guide
Real-time Changes

Subscribe to changes with MQTT-style path patterns

Changes Feed
P2P Replication

Chain, group, and fanout replication patterns

Replication
Advanced Features

Practical curl examples for replication, federation, and tiered storage

Advanced Guide
Virtual Databases (VDB)

Automatic sharding for horizontal scalability across multiple nodes

VDB Guide
Multi-Datacenter Sharding

Zone-aware deployment across regions with automatic replication

Sharding Guide

What is Barrel DocDB?¶

Barrel DocDB is a production-ready document database built on Erlang/OTP that provides:

Document CRUD with MVCC revision trees and automatic conflict resolution
Declarative Queries with automatic path indexing - no manual index creation needed
Real-time Subscriptions via MQTT-style path patterns and query subscriptions
Peer-to-Peer Replication with configurable patterns (chain, group, fanout)
Federated Queries across multiple databases with merged results
Tiered Storage with automatic TTL/capacity-based migration between hot/warm/cold tiers
Virtual Databases (VDB) for automatic sharding with scatter-gather queries
Multi-Datacenter deployment with zone-aware replication and shard placement
HTTP API with REST endpoints, SSE streaming, and Prometheus metrics

Why Barrel DocDB?¶

Use Cases¶

Edge Computing: Deploy nodes that sync to cloud when connected
Multi-Region: Replicate data across regions with automatic conflict resolution
Tiered Caching: Hot/warm/cold data tiers with automatic migration
Event Distribution: Fan-out patterns for event streaming architectures
Offline-First Apps: Full MVCC support for seamless sync when back online

Quick Example¶

Barrel DocDB can run as a standalone server accessible via HTTP from any language, or be embedded directly into your Erlang/OTP application.

Standalone (HTTP API)Embedded (Erlang API)

Run Barrel as a standalone server and access it from any language via REST:

# Health check
curl http://localhost:8080/health

# Create database
curl -X POST http://localhost:8080/db/mydb

# Put document
curl -X PUT http://localhost:8080/db/mydb/doc1 \
  -H "Content-Type: application/json" \
  -d '{"type": "user", "name": "Alice"}'

# Get document
curl http://localhost:8080/db/mydb/doc1

# Query documents
curl -X POST http://localhost:8080/db/mydb/_find \
  -H "Content-Type: application/json" \
  -d '{"where": [{"path": ["type"], "value": "user"}]}'

# Stream changes (SSE)
curl http://localhost:8080/db/mydb/_changes/stream

Embed Barrel directly into your Erlang/OTP application for maximum performance:

%% Start the application
application:ensure_all_started(barrel_docdb).

%% Create a database
{ok, _} = barrel_docdb:create_db(<<"mydb">>).

%% Save a document
{ok, #{<<"id">> := DocId, <<"rev">> := Rev}} = barrel_docdb:put_doc(<<"mydb">>, #{
    <<"type">> => <<"user">>,
    <<"name">> => <<"Alice">>
}).

%% Fetch the document
{ok, Doc} = barrel_docdb:get_doc(<<"mydb">>, DocId).

%% Query documents
{ok, Users, _Meta} = barrel_docdb:find(<<"mydb">>, #{
    where => [{path, [<<"type">>], <<"user">>}]
}).

%% Subscribe to changes (MQTT-style patterns)
{ok, SubRef} = barrel_docdb:subscribe(<<"mydb">>, <<"type/user/#">>),
receive {barrel_change, _, Change} -> io:format("~p~n", [Change]) end.

Core Features¶

Documents with MVCC¶

Every document maintains a revision tree, enabling automatic conflict detection and resolution during replication. No data loss, even in distributed scenarios.

Declarative Queries¶

Query documents using path-based conditions with automatic indexing. No need to create indexes manually - Barrel handles it for you.

{ok, Results, _} = barrel_docdb:find(<<"mydb">>, #{
    where => [
        {path, [<<"status">>], <<"active">>},
        {'and', [
            {path, [<<"age">>], '>=', 18},
            {path, [<<"role">>], <<"admin">>}
        ]}
    ],
    limit => 100
}).

Replication Policies¶

High-level patterns for common topologies:

Chain: A → B → C (write to head, read from tail)
Group: A ↔ B ↔ C (multi-master sync)
Fanout: A → B, C, D (event distribution)

Federation¶

Query across multiple databases and merge results transparently:

barrel_federation:create(<<"all_users">>, [
    <<"local_db">>,
    <<"http://nodeB:8080/users">>,
    <<"http://nodeC:8080/users">>
]).

{ok, Results, Meta} = barrel_federation:find(<<"all_users">>, #{
    where => [{path, [<<"active">>], true}]
}).

Get Started¶

5 minutes

Add to your Erlang project and start storing documents
```
{deps, [
    {barrel_docdb, "0.3.0"}
]}.
```

HTTP API

Full REST API for any language

# Start server on port 8080
curl http://localhost:8080/health