Understanding vault.db and raft.db in Vault Integrated Storage

Avatar
Jason Lopez
  • Updated

The information contained in this article has been verified as up‑to‑date on the date of the original publication of the article. HashiCorp endeavors to keep this information up‑to‑date and correct, but it makes no representations or warranties of any kind, express or implied, about the ongoing completeness, accuracy, reliability, or suitability of the information provided.

All information contained in this article is for general information purposes only. Any reliance you place on such information as it applies to your use of your HashiCorp product is therefore strictly at your own risk.

Introduction

Vault Enterprise’s Integrated Storage backend uses the Raft consensus protocol to replicate data, ensure consistency, and maintain high availability. Each Vault node persists its portion of state locally using the BoltDB storage engine.

This local state is split across two distinct files:

  • vault.db — encrypted Vault operational data
  • raft.db — Raft consensus metadata and coordination state

Understanding what these files contain, how they relate to one another, and why they exist is essential for operating and maintaining healthy Vault Enterprise clusters.

This article provides a clear conceptual explanation of both files and how they interact within Vault’s Integrated Storage architecture

Minimal Data Directory Structure

A typical Integrated Storage data directory looks like:

/opt/vault/data/
├── raft/
│   ├── raft.db
│   └── snapshots/
└── vault.db

Where:

  • vault.db contains encrypted Vault operational data
  • raft/raft.db contains Raft consensus metadata
  • raft/snapshots/ holds compacted state snapshots used during Raft log compaction and node synchronization

1. What Is vault.db?

Vault Operational Data (Encrypted)

vault.db stores Vault’s application-layer data, including, but not limited to:

  • Auth method configuration
  • Policies and ACL metadata
  • Tokens and identity metadata
  • Leases (dynamic and renewable)
  • Mount table
  • Secrets engine data (KV, PKI, database, transit, etc.)
  • Internal system metadata

Key Characteristics

Property Description
Encrypted? Yes, Vault encrypts all values before writing them
Distributed? Yes, indirectly via Raft log replication
Writable by operators? No, Vault controls all writes
Rebuilt during joins? Yes, recreated via log replay & snapshots

vault.db represents the node’s local copy of Vault’s current operational state.

2. What Is raft.db?

Raft Consensus Metadata (Cluster Coordination)

raft.db stores Raft consensus metadata, which governs how nodes participate in the Raft algorithm. This file is not encrypted because it contains coordination metadata, not secrets.

It includes:

  • Peer configuration
  • Current Raft term
  • Commit index and last applied index
  • Membership change operations
  • Election metadata
  • Raft log metadata
  • Snapshot metadata

Key Characteristics

Property Description
Encrypted? No, stores consensus metadata, not secrets
Distributed? Yes, derived from replicated Raft logs
Writable by operators? No, managed purely by Raft
Rebuilt during joins? Yes, reconstructed from the leader
raft.db represents the node’s local view of cluster membership, Raft state progression, and log position.

3. How vault.db and raft.db Work Together

Normal Raft Operation

  1. A Vault mutation occurs (e.g., writing a secret, updating a policy). 
  2. The leader writes the mutation as a Raft log entry. 
  3. The leader replicates this entry to followers. Once committed, followers apply the entry to vault.db. raft.db tracks term, indices, cluster membership, and Raft progression. Raft snapshots compact older log entries into raft/snapshots/ to reduce storage and speed up joins.

Mental Model

  • raft/raft.db = Raft coordination metadata
  • vault.db = Vault’s operational data

Both files are required for the node to function and must stay synchronized with the leader’s committed Raft log. Neither file should ever be manually edited or modified.

4. When Removal of Local State May Be Required:

Although this article does not provide troubleshooting procedures, it is important to understand why local state sometimes must be removed in separate operational workflows.

Local state removal may be necessary when:

  • A node has been removed from cluster membership (Autopilot or operator action)
  • A node’s local state reflects an outdated Raft term, index, or membership view
  • A node has disk corruption affecting its BoltDB files
  • A node attempts to operate with stale or invalid Raft metadata

In such scenarios, the node’s local vault.db and raft.db no longer reflect the correct state of the cluster. The files must be cleared so the node can safely rebuild its state from the leader using the current snapshot and Raft logs.

Conclusion

vault.db and raft.db are foundational components of Vault’s Integrated Storage backend:

  • vault.db contains encrypted operational Vault data
  • raft.db contains Raft consensus metadata
  • Both work together to maintain consistency, durability, and coordination across Vault cluster nodes
  • Raft snapshots and log replication ensure all nodes converge to the same operational state

Understanding these files and the distinct roles they play, helps operators maintain healthy clusters, reason about Raft internals, and recognize when local state misalignment may require corrective action (covered in separate articles).

Additional Information:
HashiCorp Documentation

HashiCorp Support & Knowledge Base Articles

Articles in this section

See more

Related articles