Google Git
Sign in
chromium/external/github.com/dgraph-io/badger/refs/heads/main
commit
2a001d466f6b71a917319a1db41f99860e16e269
[log]
author
Aditya Jha <aditya.jha8969@gmail.com>
Fri Aug 28 01:05:19 2026
committer
GitHub <noreply@github.com>
Fri Aug 28 01:05:19 2026
tree
6bf4efe725d4171ddf44ed990623f03471040c5e
parent
2cd14d171b7cb645c1d802e3d3044fddae4d5fc2 [diff]
fix(table): return error instead of fatalpanic when opening a corrupt sst (#2333)

**Description**

Fixes [#2201](https://github.com/dgraph-io/badger/issues/2201) 

`db.Open()` crashes with a `runtime.fatalpanic` when an SSTable's footer
is corrupted (e.g. zeroed), instead of returning an error.

Looking at the stack trace of issue description, it looks like following
could be the reason for runtime termination,

An SST footer is laid out as `[index][indexLen][checksum][checksumLen]`,
with the two lengths stored as 4-byte big-endian values. When the footer
is zeroed, `checksumLen` and `indexLen` both read as `0`, so we read
empty checksum and index bytes. The empty protobuf checksum unmarshals
to `Sum = 0`, and the CRC32C of an empty index is also `0`, so the `0 ==
0` verification passes. The code then parses the empty index as
flatbuffers and reads an out-of-bounds offset into a slice, which
panics. `initBiggestAndSmallest` catches that panic, collects debug
info, then deliberately re-panics — and that re-panic escapes the
table-loading goroutine in `newLevelsController` (which has no
`recover()`), so the runtime terminates the process.

Changes:
- `table/table.go`: `initBiggestAndSmallest` returns an error (instead
of re-panicking) after collecting debug info, and `initIndex` validates
the footer's `checksumLen`/`indexLen`, rejecting `<= 0` (an empty
checksum/index false-passes the `0 == 0` checksum check and then panics
parsing empty flatbuffers) and `>= tableSize` (the length can't describe
a region as large as the whole file — it would make the footer's read
offset negative and slice out of bounds).
- `levels.go`: added a `recover()` in the table-loading goroutine as a
safety net for any panic that still escapes the table package.

**Checklist**

- [x] Code compiles correctly and linting passes locally
- [x] Tests added for new functionality, or regression tests for bug
fixes added as applicable

---------

Co-authored-by: Matthew McNeely <matthew.mcneely@gmail.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
6 files changed
tree: 6bf4efe725d4171ddf44ed990623f03471040c5e
  1. .github/
  2. .trunk/
  3. .vscode/
  4. badger/
  5. contrib/
  6. docs/
  7. fb/
  8. images/
  9. integration/
  10. options/
  11. pb/
  12. skl/
  13. table/
  14. trie/
  15. y/
  16. .gitignore
  17. backup.go
  18. backup_test.go
  19. batch.go
  20. batch_test.go
  21. CHANGELOG.md
  22. changes.sh
  23. CODE_OF_CONDUCT.md
  24. compaction.go
  25. CONTRIBUTING.md
  26. db.go
  27. db2_test.go
  28. db_corrupt_test.go
  29. db_test.go
  30. dir_aix.go
  31. dir_other.go
  32. dir_plan9.go
  33. dir_unix.go
  34. dir_windows.go
  35. discard.go
  36. discard_test.go
  37. doc.go
  38. errors.go
  39. go.mod
  40. go.sum
  41. histogram.go
  42. histogram_test.go
  43. iterator.go
  44. iterator_test.go
  45. key_registry.go
  46. key_registry_test.go
  47. l0_backpressure_test.go
  48. l0_blockwrites_regression_test.go
  49. level_handler.go
  50. levels.go
  51. levels_test.go
  52. LICENSE
  53. logger.go
  54. logger_test.go
  55. Makefile
  56. managed_db.go
  57. managed_db_test.go
  58. manifest.go
  59. manifest_test.go
  60. memtable.go
  61. merge.go
  62. merge_test.go
  63. metrics_test.go
  64. options.go
  65. options_test.go
  66. publisher.go
  67. publisher_test.go
  68. README.md
  69. SECURITY.md
  70. stream.go
  71. stream_test.go
  72. stream_writer.go
  73. stream_writer_test.go
  74. structs.go
  75. structs_test.go
  76. test.sh
  77. test_extensions.go
  78. txn.go
  79. txn_test.go
  80. util.go
  81. value.go
  82. value_gc_rewrite_bench_test.go
  83. value_test.go
  84. VERSIONING.md
  85. watermark_edge_test.go
README.md

BadgerDB

Go Reference Go Report Card Sourcegraph ci-badger-tests ci-badger-bank-tests ci-badger-bank-tests-nightly

Badger mascot

BadgerDB is an embeddable, persistent and fast key-value (KV) database written in pure Go. It is the underlying database for Dgraph, a fast, distributed graph database. It's meant to be a performant alternative to non-Go-based key-value stores like RocksDB.

Project Status

Badger is stable and is being used to serve data sets worth hundreds of terabytes. Badger supports concurrent ACID transactions with serializable snapshot isolation (SSI) guarantees. A Jepsen-style bank test runs nightly for 8h, with --race flag and ensures the maintenance of transactional guarantees. Badger has also been tested to work with filesystem level anomalies, to ensure persistence and consistency. Badger is being used by a number of projects which includes Dgraph, Jaeger Tracing, UsenetExpress, and many more.

The list of projects using Badger can be found here.

Please consult the Changelog for more detailed information on releases.

Note: Badger is built with go 1.23 and we refrain from bumping this version to minimize downstream effects of those using Badger in applications built with older versions of Go.

Table of Contents

Getting Started

Installing

To start using Badger, install Go 1.23 or above. Badger v3 and above needs go modules. From your project, run the following command

go get github.com/dgraph-io/badger/v4

This will retrieve the library.

Installing Badger Command Line Tool

Badger provides a CLI tool which can perform certain operations like offline backup/restore. To install the Badger CLI, retrieve the repository and checkout the desired version. Then run

cd badger
go install .

This will install the badger command line utility into your $GOBIN path.

Badger Documentation

Badger Documentation is available at https://badger.dgraph.io

Resources

Blog Posts

  1. Introducing Badger: A fast key-value store written natively in Go
  2. Make Badger crash resilient with ALICE
  3. Badger vs LMDB vs BoltDB: Benchmarking key-value databases in Go
  4. Concurrent ACID Transactions in Badger

Design

Badger was written with these design goals in mind:

  • Write a key-value database in pure Go.
  • Use latest research to build the fastest KV database for data sets spanning terabytes.
  • Optimize for SSDs.

Badger’s design is based on a paper titled WiscKey: Separating Keys from Values in SSD-conscious Storage.

Comparisons

FeatureBadgerRocksDBBoltDB
DesignLSM tree with value logLSM tree onlyB+ tree
High Read throughputYesNoYes
High Write throughputYesYesNo
Designed for SSDsYes (with latest research 1)Not specifically 2No
EmbeddableYesYesYes
Sorted KV accessYesYesYes
Pure Go (no Cgo)YesNoYes
TransactionsYes, ACID, concurrent with SSI3Yes (but non-ACID)Yes, ACID
SnapshotsYesYesYes
TTL supportYesYesNo
3D access (key-value-version)Yes4NoNo

1 The WISCKEY paper (on which Badger is based) saw big wins with separating values from keys, significantly reducing the write amplification compared to a typical LSM tree.

2 RocksDB is an SSD optimized version of LevelDB, which was designed specifically for rotating disks. As such RocksDB‘s design isn’t aimed at SSDs.

3 SSI: Serializable Snapshot Isolation. For more details, see the blog post Concurrent ACID Transactions in Badger

4 Badger provides direct access to value versions via its Iterator API. Users can also specify how many versions to keep per key via Options.

Benchmarks

We have run comprehensive benchmarks against RocksDB, Bolt and LMDB. The benchmarking code, and the detailed logs for the benchmarks can be found in the badger-bench repo. More explanation, including graphs can be found the blog posts (linked above).

Projects Using Badger

Below is a list of known projects that use Badger:

  • Dgraph - Distributed graph database.
  • Jaeger - Distributed tracing platform.
  • go-ipfs - Go client for the InterPlanetary File System (IPFS), a new hypermedia distribution protocol.
  • Riot - An open-source, distributed search engine.
  • emitter - Scalable, low latency, distributed pub/sub broker with message storage, uses MQTT, gossip and badger.
  • OctoSQL - Query tool that allows you to join, analyse and transform data from multiple databases using SQL.
  • Dkron - Distributed, fault tolerant job scheduling system.
  • smallstep/certificates - Step-ca is an online certificate authority for secure, automated certificate management.
  • Sandglass - distributed, horizontally scalable, persistent, time sorted message queue.
  • TalariaDB - Grab's Distributed, low latency time-series database.
  • Sloop - Salesforce's Kubernetes History Visualization Project.
  • Usenet Express - Serving over 300TB of data with Badger.
  • gorush - A push notification server written in Go.
  • 0-stor - Single device object store.
  • Dispatch Protocol - Blockchain protocol for distributed application data analytics.
  • GarageMQ - AMQP server written in Go.
  • RedixDB - A real-time persistent key-value store with the same redis protocol.
  • BBVA - Raft backend implementation using BadgerDB for Hashicorp raft.
  • Fantom - aBFT Consensus platform for distributed applications.
  • decred - An open, progressive, and self-funding cryptocurrency with a system of community-based governance integrated into its blockchain.
  • OpenNetSys - Create useful dApps in any software language.
  • HoneyTrap - An extensible and opensource system for running, monitoring and managing honeypots.
  • Insolar - Enterprise-ready blockchain platform.
  • IoTeX - The next generation of the decentralized network for IoT powered by scalability- and privacy-centric blockchains.
  • go-sessions - The sessions manager for Go net/http and fasthttp.
  • Babble - BFT Consensus platform for distributed applications.
  • Tormenta - Embedded object-persistence layer / simple JSON database for Go projects.
  • BadgerHold - An embeddable NoSQL store for querying Go types built on Badger
  • Goblero - Pure Go embedded persistent job queue backed by BadgerDB
  • Surfline - Serving global wave and weather forecast data with Badger.
  • Cete - Simple and highly available distributed key-value store built on Badger. Makes it easy bringing up a cluster of Badger with Raft consensus algorithm by hashicorp/raft.
  • Volument - A new take on website analytics backed by Badger.
  • KVdb - Hosted key-value store and serverless platform built on top of Badger.
  • Terminotes - Self hosted notes storage and search server - storage powered by BadgerDB
  • Pyroscope - Open source continuous profiling platform built with BadgerDB
  • Veri - A distributed feature store optimized for Search and Recommendation tasks.
  • bIter - A library and Iterator interface for working with the badger.Iterator, simplifying from-to, and prefix mechanics.
  • ld - (Lean Database) A very simple gRPC-only key-value database, exposing BadgerDB with key-range scanning semantics.
  • Souin - A RFC compliant HTTP cache with lot of other features based on Badger for the storage. Compatible with all existing reverse-proxies.
  • Xuperchain - A highly flexible blockchain architecture with great transaction performance.
  • m2 - A simple http key/value store based on the raft protocol.
  • chaindb - A blockchain storage layer used by Gossamer, a Go client for the Polkadot Network.
  • vxdb - Simple schema-less Key-Value NoSQL database with simplest API interface.
  • Opacity - Backend implementation for the Opacity storage project
  • Vephar - A minimal key/value store using hashicorp-raft for cluster coordination and Badger for data storage.
  • gowarcserver - Open-source server for warc files. Can be used in conjunction with pywb
  • flow-go - A fast, secure, and developer-friendly blockchain built to support the next generation of games, apps and the digital assets that power them.
  • Wrgl - A data version control system that works like Git but specialized to store and diff CSV.
  • Loggie - A lightweight, cloud-native data transfer agent and aggregator.
  • raft-badger - raft-badger implements LogStore and StableStore Interface of hashcorp/raft. it is used to store raft log and metadata of hashcorp/raft.
  • DVID - A dataservice for branched versioning of a variety of data types. Originally created for large-scale brain reconstructions in Connectomics.
  • KVS - A library for making it easy to persist, load and query full structs into BadgerDB, using an ownership hierarchy model.
  • LLS - LLS is an efficient URL Shortener that can be used to shorten links and track link usage. Support for BadgerDB and MongoDB. Improved performance by more than 30% when using BadgerDB
  • lakeFS - lakeFS is an open-source data version control that transforms your object storage to Git-like repositories. lakeFS uses BadgerDB for its underlying local metadata KV store implementation
  • Goptivum - Goptivum is a better frontend and API for the Vulcan Optivum schedule program
  • ActionManager - A dynamic entity manager based on rjsf schema and badger db
  • MightyMap - Mightymap: Conveys both robustness and high capability, fitting for a powerful concurrent map.
  • FlowG - A low-code log processing facility
  • Bluefin - Bluefin is a TUNA Proof of Work miner for the Fortuna smart contract on the Cardano blockchain
  • cDNSd - A Cardano blockchain backed DNS server daemon
  • Dingo - A Cardano blockchain data node

If you are using Badger in a project please send a pull request to add it to the list.

Platform Compatibility

Badger uses OS-specific implementations for directory locking and fsync operations. On POSIX-compliant systems (Linux, macOS, BSD), these work as expected.

For non-POSIX platforms, be aware of potential limitations:

PlatformFileNotes
AIXdir_aix.goDirectory fsync not supported; durability on crash may be affected
Windowsdir_windows.goUses different locking mechanism
Plan9dir_plan9.goNo file locking support
WASM/JSdir_other.goNo file locking support

If you encounter issues on these platforms, review the corresponding dir_*.go source file for implementation details.

Contributing

If you're interested in contributing to Badger see CONTRIBUTING.

Contact