LDB Tool - RocksDB

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

Simple put

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

Put with hex encoding

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

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

Delete single key

ldb --db=/tmp/mydb delete mykey

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

Option	Description
`--db=<path>`	Database directory path (required)
`--secondary_path=<path>`	Open as secondary instance for read-only access
`--try_load_options`	Try loading options from OPTIONS file
`--create_if_missing`	Create database if it doesn’t exist
`--column_family=<name>`	Operate on specific column family

Data Encoding Options

Option	Description
`--hex`	Use hex encoding for both keys and values
`--key_hex`	Use hex encoding for keys only
`--value_hex`	Use hex encoding for values only

Environment Options

Option	Description
`--env_uri=<uri>`	URI of underlying environment
`--fs_uri=<uri>`	URI of underlying filesystem

Working with Hex Encoding

Why Use Hex?

Binary data

When keys or values contain non-printable binary data:

ldb --db=/tmp/mydb --hex scan

Precise byte sequences

When you need exact byte control:

ldb --db=/tmp/mydb --key_hex get 0x000102030405

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

Open as secondary

Open production DB safely without interfering:

ldb --db=/prod/db --secondary_path=/tmp/secondary get problem_key

Check key existence

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

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

​Overview

​Basic Usage

​Opening a Database

​Key Commands

​Get - Read a Single Key

​Put - Write a Single Key

​Scan - Iterate Through Keys

​Delete - Remove Keys

​Database Information Commands

​Dump - Export Database Contents

​Load - Import Database Contents

​Manifest Dump - Inspect MANIFEST File

​List Column Families

​Column Family Operations

​Working with Column Families

​Create and Drop Column Families

​Advanced Commands

​WAL Dump - Inspect Write-Ahead Log

​Compaction

​Reduce DB Levels

​Check Consistency

​Approximate Size

​Common Options

​Database Opening Options

​Data Encoding Options

​Environment Options

​Working with Hex Encoding

​Why Use Hex?

​TTL Databases

​Transaction Databases

​Blob Index Decoding

​Practical Examples

​Debug Production Issue

​Database Migration

​Examine LSM Tree Structure

​Cleanup Old Keys

​Query Tool (Interactive Mode)

​Internal Commands

​Internal Dump

​SST File Dumper

​Performance Considerations

​Source Reference

​Getting Help

Overview

Basic Usage

Opening a Database

Key Commands

Get - Read a Single Key

Put - Write a Single Key

Scan - Iterate Through Keys

Delete - Remove Keys

Database Information Commands

Dump - Export Database Contents

Load - Import Database Contents

Manifest Dump - Inspect MANIFEST File

List Column Families

Column Family Operations

Working with Column Families

Create and Drop Column Families

Advanced Commands

WAL Dump - Inspect Write-Ahead Log

Compaction

Reduce DB Levels

Check Consistency

Approximate Size

Common Options

Database Opening Options

Data Encoding Options

Environment Options

Working with Hex Encoding

Why Use Hex?

TTL Databases

Transaction Databases

Blob Index Decoding

Practical Examples

Debug Production Issue

Database Migration

Examine LSM Tree Structure

Cleanup Old Keys

Query Tool (Interactive Mode)

Internal Commands

Internal Dump

SST File Dumper

Performance Considerations

Source Reference

Getting Help