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

> Explore Dragonboat storage engines: Pebble, Tan, and custom configurations. Learn how to set up your Raft logs with NodeHostConfig Expert for optimal performance.

- Repository: [lni/dragonboat](https://github.com/lni/dragonboat)
- Tags: how-to-guide
- Published: 2026-03-06

---

**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.

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

```

The Pebble implementation resides in [`raftio/pebble.go`](https://github.com/lni/dragonboat/blob/main/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`:

```go
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`](https://github.com/lni/dragonboat/blob/main/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`](https://github.com/lni/dragonboat/blob/main/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:

```go
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:

```go
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`](https://github.com/lni/dragonboat/blob/main/raftio/logdb.go)** — Defines the `ILogDB` interface that all storage engines must satisfy.
- **[`raftio/pebble.go`](https://github.com/lni/dragonboat/blob/main/raftio/pebble.go)** — Default Pebble implementation used automatically.
- **[`raftio/tan/tan.go`](https://github.com/lni/dragonboat/blob/main/raftio/tan/tan.go)** — Next-generation Tan engine implementation.
- **[`nodehost.go`](https://github.com/lni/dragonboat/blob/main/nodehost.go)** — Constructs `NodeHost` and wires the `LogDBFactory` from `ExpertConfig`.
- **[`docs/storage.md`](https://github.com/lni/dragonboat/blob/main/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.