Dragonboat Storage Engines: Pebble, Tan, and Custom Configuration Guide

Dragonboat supports three storage engines for Raft logs: Pebble (default), Tan (next-generation), and custom implementations via the ILogDB interface, each configured through NodeHostConfig.Expert settings.

Dragonboat is a high-performance Go implementation of the Raft consensus protocol that persists Raft logs through a pluggable LogDB storage layer. Understanding the available storage engines and their configuration options is essential for optimizing durability and performance in production deployments.

Built-in Storage Engines in Dragonboat

Dragonboat ships with two production-ready storage backends and supports custom implementations through a factory pattern.

Pebble: The Default Production Engine

Pebble is the default storage engine used automatically when creating a NodeHost instance. No explicit configuration is required—Dragonboat instantiates a Pebble-based LogDB internally.

// Minimal configuration - Pebble is used automatically.
nhc := dragonboat.Config{
    // other options …
}
nodeHost, err := dragonboat.NewNodeHost(nhc)

The Pebble implementation resides in raftio/pebble.go and handles all Raft log persistence, including entry storage and retrieval.

Tan: The Next-Generation Engine

Tan is a newer storage engine designed to eventually replace Pebble as the default. It offers improved performance characteristics and is currently available as an opt-in feature.

To enable Tan, configure the LogDBFactory field in ExpertConfig:

import (
    "github.com/lni/dragonboat/v4"
    "github.com/lni/dragonboat/v4/raftio/tan"
)

nhc := dragonboat.Config{
    // … other fields …
    Expert: dragonboat.ExpertConfig{
        // Replace the default Pebble factory with Tan.
        LogDBFactory: func(cfg dragonboat.LogDBConfig) dragonboat.LogDB {
            return tan.NewLogDB(cfg) // Tan implements the LogDB interface.
        },
    },
}
nodeHost, err := dragonboat.NewNodeHost(nhc)

The Tan implementation is located in raftio/tan/tan.go. When Dragonboat makes Tan the default engine, existing configurations will continue to function without modification.

Configuring Custom Storage Engines

Dragonboat allows you to implement custom storage backends by satisfying the ILogDB interface defined in raftio/logdb.go.

Implementing the ILogDB Interface

Create a type that implements all required methods of the ILogDB interface, including Append, GetEntry, Sync, and others:

type MyLogDB struct {
    // embed any state you need …
}

// Ensure MyLogDB conforms to the ILogDB interface.
var _ dragonboat.ILogDB = (*MyLogDB)(nil)

// Implement required methods (Append, GetEntry, Sync, etc.) …

func myLogDBFactory(cfg dragonboat.LogDBConfig) dragonboat.LogDB {
    return &MyLogDB{/* init from cfg … */}
}

Registering Your Custom Engine

Pass your factory function through the NodeHostConfig.Expert.LogDBFactory field:

nhc := dragonboat.Config{
    // … other fields …
    Expert: dragonboat.ExpertConfig{
        LogDBFactory: myLogDBFactory,
    },
}
nodeHost, err := dragonboat.NewNodeHost(nhc)

This pattern enables integration with any underlying storage system—whether RocksDB, Badger, or a proprietary solution—provided it implements the ILogDB contract.

Key Source Files and Architecture

Understanding the source layout helps when debugging or extending storage functionality:

• raftio/logdb.go — Defines the ILogDB interface that all storage engines must satisfy.
• raftio/pebble.go — Default Pebble implementation used automatically.
• raftio/tan/tan.go — Next-generation Tan engine implementation.
• nodehost.go — Constructs NodeHost and wires the LogDBFactory from ExpertConfig.
• docs/storage.md — High-level documentation on storage engine selection.

The pluggable architecture ensures that storage engine selection is transparent to Raft state machine logic, allowing performance optimization without application changes.

Summary

• Pebble is the default storage engine requiring no configuration—Dragonboat automatically instantiates it when creating a NodeHost.
• Tan is the next-generation engine enabled by setting Expert.LogDBFactory to a factory function returning tan.NewLogDB().
• Custom engines implement the ILogDB interface and register via Expert.LogDBFactory for integration with alternative storage systems.
• The RocksDB backend was removed in v3.4, leaving Pebble and Tan as the built-in options.

Frequently Asked Questions

What happened to RocksDB support in Dragonboat?

RocksDB was removed as a built-in storage engine in Dragonboat v3.4. The project now focuses on Pebble as the stable default and Tan as the next-generation replacement. If you require RocksDB, you must implement a custom ILogDB wrapper around the RocksDB Go bindings and register it via Expert.LogDBFactory.

Which storage engine should I use for production workloads?

Pebble is currently recommended for production deployments because it is the default, battle-tested engine used automatically by Dragonboat. Tan is available for testing and offers performance improvements, but you should validate it thoroughly in your specific workload before production deployment. Monitor the Dragonboat release notes for announcements regarding Tan becoming the default.

How do I migrate from Pebble to Tan?

Migration requires configuring the Expert.LogDBFactory field to return a Tan instance instead of accepting the default Pebble backend. However, because Raft log storage contains persistent state, you cannot simply switch engines on an existing data directory. You must either start with fresh nodes using Tan or implement a custom migration tool that reads from Pebble and writes to Tan via the ILogDB interface methods.

Can I use Redis or PostgreSQL as a custom storage engine?

Yes, any storage system that can satisfy the ILogDB interface requirements—including Append, GetEntry, Sync, and other Raft log operations—can be used as a custom engine. You would create a wrapper type that translates Dragonboat's log operations into Redis or PostgreSQL calls, then register your factory function via Expert.LogDBFactory. Note that latency and durability characteristics of external databases may impact Raft performance compared to embedded engines like Pebble or Tan.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}