Skip to main content

​
Overview

LDB (LevelDB Tool) is RocksDB’s interactive command-line utility for database inspection, debugging, and administrative operations. It provides a rich set of commands for reading, writing, scanning, and analyzing RocksDB databases without writing custom code.
LDB is particularly useful for debugging production issues, examining database contents, and performing one-off administrative tasks.

​
Basic Usage

LDB follows this general syntax: 
ldb --db=<database_path> [common_options] <command> [command_options] [arguments]

​
Opening a Database

All LDB commands require specifying the database path: 
ldb --db=/tmp/mydb get mykey

​
Key Commands

​
Get - Read a Single Key

Retrieve the value for a specific key: 
ldb --db=/tmp/mydb get mykey
With hex encoding: 
ldb --db=/tmp/mydb --key_hex --value_hex get 0x6b6579

​
Put - Write a Single Key

1

Simple put

ldb --db=/tmp/mydb put mykey myvalue
2

Put with hex encoding

ldb --db=/tmp/mydb --key_hex --value_hex \
  put 0x6b6579 0x76616c7565
3

Batch put

Insert multiple keys from a file:
ldb --db=/tmp/mydb batchput < keys.txt
Format: one key-value pair per line (key and value separated by space)

​
Scan - Iterate Through Keys

Scan all keys in the database: 
ldb --db=/tmp/mydb scan
Scan with range limits: 
ldb --db=/tmp/mydb scan --from=key001 --to=key999
Limit number of keys: 
ldb --db=/tmp/mydb scan --max_keys=100
Scan without printing values (keys only): 
ldb --db=/tmp/mydb scan --no_value

​
Delete - Remove Keys

1

Delete single key

ldb --db=/tmp/mydb delete mykey
2

Delete range

Delete all keys in a range:
ldb --db=/tmp/mydb deleterange start_key end_key

​
Database Information Commands

​
Dump - Export Database Contents

Export entire database to a text file: 
ldb --db=/tmp/mydb dump --dump_location=/tmp/db_dump.txt
Dump with hex encoding: 
ldb --db=/tmp/mydb dump \
  --dump_location=/tmp/db_dump.txt \
  --hex

​
Load - Import Database Contents

Import from a dump file: 
ldb --db=/tmp/mydb load --dump_location=/tmp/db_dump.txt

​
Manifest Dump - Inspect MANIFEST File

Examine database metadata and LSM tree structure: 
ldb --db=/tmp/mydb manifest_dump
Verbose output with detailed file information: 
ldb --db=/tmp/mydb manifest_dump --verbose

​
List Column Families

Show all column families in a database: 
ldb --db=/tmp/mydb list_column_families

​
Column Family Operations

RocksDB supports multiple column families. LDB can operate on specific column families:

​
Working with Column Families

# Get from specific column family
ldb --db=/tmp/mydb --column_family=metadata get mykey

# Scan specific column family
ldb --db=/tmp/mydb --column_family=metadata scan

# Put to specific column family
ldb --db=/tmp/mydb --column_family=metadata put key1 value1

​
Create and Drop Column Families

# Create new column family
ldb --db=/tmp/mydb create_column_family new_cf

# Drop column family
ldb --db=/tmp/mydb drop_column_family old_cf

​
Advanced Commands

​
WAL Dump - Inspect Write-Ahead Log

Examine WAL files for debugging: 
ldb --db=/tmp/mydb dump_wal
Filter by sequence numbers: 
ldb --db=/tmp/mydb dump_wal --seq_from=1000 --seq_to=2000

​
Compaction

Manually trigger compaction: 
ldb --db=/tmp/mydb compact
Compact specific key range: 
ldb --db=/tmp/mydb compact --from=key001 --to=key999

​
Reduce DB Levels

Change the number of levels in the LSM tree: 
ldb --db=/tmp/mydb reduce_levels --new_levels=4
Reducing levels requires careful consideration of your data size and can trigger significant compaction work.

​
Check Consistency

Verify database integrity: 
ldb --db=/tmp/mydb checkconsistency

​
Approximate Size

Estimate size of key range: 
ldb --db=/tmp/mydb approxsize --from=key001 --to=key999

​
Common Options

​
Database Opening Options

OptionDescription
--db=<path>Database directory path (required)
--secondary_path=<path>Open as secondary instance for read-only access
--try_load_optionsTry loading options from OPTIONS file
--create_if_missingCreate database if it doesn’t exist
--column_family=<name>Operate on specific column family

​
Data Encoding Options

OptionDescription
--hexUse hex encoding for both keys and values
--key_hexUse hex encoding for keys only
--value_hexUse hex encoding for values only

​
Environment Options

OptionDescription
--env_uri=<uri>URI of underlying environment
--fs_uri=<uri>URI of underlying filesystem

​
Working with Hex Encoding

​
Why Use Hex?

1

Binary data

When keys or values contain non-printable binary data:
ldb --db=/tmp/mydb --hex scan
2

Precise byte sequences

When you need exact byte control:
ldb --db=/tmp/mydb --key_hex get 0x000102030405
3

Debugging binary formats

When inspecting internal key formats:
ldb --db=/tmp/mydb --hex dump_wal

​
TTL Databases

LDB supports databases with Time-To-Live (TTL): 
# Show timestamps with values
ldb --db=/tmp/mydb --ttl scan --timestamp

# Filter by time range
ldb --db=/tmp/mydb --ttl scan \
  --start_time=1234567890 \
  --end_time=1234567999

​
Transaction Databases

Work with TransactionDB: 
ldb --db=/tmp/mydb --use_txn get mykey

​
Blob Index Decoding

For databases using blob files, decode blob references: 
ldb --db=/tmp/mydb scan --decode_blob_index

​
Practical Examples

​
Debug Production Issue

1

Open as secondary

Open production DB safely without interfering:
ldb --db=/prod/db --secondary_path=/tmp/secondary get problem_key
2

Check key existence

ldb --db=/prod/db --secondary_path=/tmp/secondary \
  scan --from=problem_key --max_keys=1
3

Inspect nearby keys

ldb --db=/prod/db --secondary_path=/tmp/secondary \
  scan --from=problem_key --max_keys=10

​
Database Migration

# Export from old database
ldb --db=/old/db dump --dump_location=/tmp/export.txt

# Import to new database
ldb --db=/new/db load --dump_location=/tmp/export.txt

​
Examine LSM Tree Structure

# View manifest with file details
ldb --db=/tmp/mydb manifest_dump --verbose

# Check number of files per level
ldb --db=/tmp/mydb manifest_dump | grep -c "level "

​
Cleanup Old Keys

# Delete keys older than certain prefix
ldb --db=/tmp/mydb deleterange old_prefix_000 old_prefix_999

# Compact to reclaim space
ldb --db=/tmp/mydb compact

​
Query Tool (Interactive Mode)

Use db_queryer for interactive database exploration: 
ldb --db=/tmp/mydb db_queryer
Once in interactive mode: 
> get mykey
> put newkey newvalue
> scan --max_keys=10
> exit

​
Internal Commands

​
Internal Dump

Dump internal key format with sequence numbers: 
ldb --db=/tmp/mydb idump --max_keys=100

​
SST File Dumper

Examine individual SST files: 
ldb --db=/tmp/mydb dump_live_files

​
Performance Considerations

When working with large databases, use --max_keys to limit output:
ldb --db=/tmp/mydb scan --max_keys=1000
Use --secondary_path when accessing production databases to avoid write locks and ensure safety.

​
Source Reference

LDB is implemented across several files:
  • include/rocksdb/ldb_tool.h:22-47 - Public API interface
  • include/rocksdb/utilities/ldb_cmd.h:31-200 - Command definitions and argument constants
  • tools/ldb_cmd.cc:61-400 - Command implementations
  • tools/ldb.cc - Main entry point
Build LDB: 
make ldb

​
Getting Help

Display available commands and options: 
ldb --help
Get help for specific command: 
ldb --db=/tmp/mydb scan --help

Build docs developers (and LLMs) love

Get started for freeTalk to us