---
title: RocksDB Backend Setup & Performance
sidebarTitle: RocksDB Backend
description: >-
  Learn how to set up the RocksDB backend for Paxeer nodes to achieve 10-30x
  faster traceBlock iteration performance.
keywords:
  - rocksdb
  - paxeer node
  - state store
  - performance
  - traceBlock
  - archive node
  - rpc
---

> **For AI agents:** the complete documentation index is at [llms.txt](/llms.txt). Append `.md` to any page URL for its markdown version.

## Overview

As Paxeer nodes accumulate more history and state data, iteration-heavy operations - like those performed during `traceBlock` calls - can become significantly slower. This is especially true for archive or RPC nodes where the state store contains millions of versions.

To address this, Paxeer supports **RocksDB** as an alternative backend to PebbleDB. RocksDB provides native **multi-version concurrency control (MVCC)** and **column family support**, which leads to substantial iteration performance improvements as history grows.

## Why RocksDB?

PebbleDB lacks native MVCC support, meaning the node must manually encode versions into keys. This retrofit approach causes iteration time to grow linearly with the amount of stored history. As a result:

- Archive nodes with large state stores experience **slower debug trace latency**.
- Each key lookup may require scanning multiple key versions.
- Iterations (e.g., over Oracle or EVM module keys) become increasingly expensive over time.

By contrast, **RocksDB** supports native user-defined timestamps and optimized column families for versioned data access. This means:

- Iterations over keys at a single version are **much faster**.
- Historical data growth has **minimal effect on iteration cost**.
- The performance advantage **amplifies with larger node history**.

In benchmarks, RocksDB achieved up to **10 - 30× faster traceBlock iteration times** compared to PebbleDB, with even greater benefits observed on archive nodes.

## Setup Instructions

RocksDB only needs to be built once. After that, you can install `paxd` with RocksDB support directly.

### Prerequisites

Ensure your system includes the following packages:

```bash
sudo apt-get update
sudo apt-get install -y build-essential pkg-config cmake git zlib1g-dev \
    libbz2-dev libsnappy-dev liblz4-dev libzstd-dev libjemalloc-dev \
    libgflags-dev liburing-dev
```

### Build & Install

```bash
# Step 1: Build RocksDB (one-time setup)
make build-rocksdb

# Step 2: Install paxd with RocksDB backend
make install-rocksdb
```

Once installed, your `paxd` binary will be built with RocksDB backend support:

```bash
paxd version
# should include "rocksdbBackend" build tag
```

### Configuration

After installation, update your configuration file to enable the RocksDB backend:

```bash
~/.paxeer/config/app.toml
```

Set

```toml
ss-backend = "rocksdb"
```

### Node Setup Notes

- RPC Nodes - must perform a state sync when spinning up a new node configured with RocksDB.
- Archive Nodes - currently, RocksDB is not supported for existing data unless syncing from genesis.

## Summary

| Feature                       | PebbleDB           | RocksDB                               |
| ----------------------------- | ------------------ | ------------------------------------- |
| MVCC Support                  | No                 | Native via user-defined timestamps |
| Column Families               | No                 | Yes                                |
| Iteration Speed (Large State) | Slows with history | Up to 30x faster                   |
| Installation                  | Default            | One-time build (`make build-rocksdb`) |

## TL;DR

- RocksDB backend drastically improves trace iteration and historical query performance.
- Install once, then run:

```bash
make install-rocksdb
```

- Update ~/.paxeer/config/app.toml to use RocksDB:

```toml
ss-backend = "rocksdb"
```

- RPC nodes require state sync; archive nodes must currently sync from genesis
- Expect **10 - 30× faster** trace latencies, especially on archive nodes or long-history setups.