Skip to main content

db

db.go - Overview​

This file implements the core DB struct and its associated methods for interacting with the Badger key-value store. It handles database opening, closing, writing, reading, compaction, and other essential operations.

Detailed Documentation​

badgerPrefix​

var badgerPrefix = []byte("!badger!")
  • Purpose: Prefix for internal keys used by badger.

txnKey​

var txnKey = []byte("!badger!txn")
  • Purpose: For indicating end of entries in txn.

bannedNsKey​

var bannedNsKey = []byte("!badger!banned")
  • Purpose: For storing the banned namespaces.

closers struct​

type closers struct {
	updateSize  *z.Closer
	compactors  *z.Closer
	memtable    *z.Closer
	writes      *z.Closer
	valueGC     *z.Closer
	pub         *z.Closer
	cacheHealth *z.Closer
}
  • Purpose: Holds z.Closer instances for managing the lifecycle of various background goroutines.

lockedKeys struct​

type lockedKeys struct {
	sync.RWMutex
	keys map[uint64]struct{}
}
  • Purpose: Manages a set of locked keys with a read-write mutex for concurrent access.

lockedKeys.add(key uint64)​

func (lk *lockedKeys) add(key uint64)
  • Purpose: Adds a key to the set of locked keys.
  • Parameters:
    • key (uint64): The key to add.
  • Returns: None

lockedKeys.has(key uint64)​

func (lk *lockedKeys) has(key uint64) bool
  • Purpose: Checks if a key exists in the set of locked keys.
  • Parameters:
    • key (uint64): The key to check.
  • Returns:
    • bool: True if the key exists, false otherwise.

lockedKeys.all() []uint64​

func (lk *lockedKeys) all() []uint64
  • Purpose: Returns all keys present in the lockedKeys.
  • Parameters: None
  • Returns:
    • []uint64: Slice containing all keys.

DB struct​

type DB struct {
	testOnlyDBExtensions

	lock sync.RWMutex // Guards list of inmemory tables, not individual reads and writes.

	dirLockGuard *directoryLockGuard
	// nil if Dir and ValueDir are the same
	valueDirGuard *directoryLockGuard

	closers closers

	mt  *memTable   // Our latest (actively written) in-memory table
	imm []*memTable // Add here only AFTER pushing to flushChan.

	// Initialized via openMemTables.
	nextMemFid int

	opt       Options
	manifest  *manifestFile
	lc        *levelsController
	vlog      valueLog
	writeCh   chan *request
	flushChan chan *memTable // For flushing memtables.
	closeOnce sync.Once      // For closing DB only once.

	blockWrites atomic.Int32
	isClosed    atomic.Uint32

	orc              *oracle
	bannedNamespaces *lockedKeys
	threshold        *vlogThreshold

	pub        *publisher
	registry   *KeyRegistry
	blockCache *ristretto.Cache[[]byte, *table.Block]
	indexCache *ristretto.Cache[uint64, *fb.TableIndex]
	allocPool  *z.AllocatorPool
}
  • Purpose: Represents the Badger database. It contains memtables, value log, levels controller, and other components necessary for managing the database.

kvWriteChCapacity constant​

const (
	kvWriteChCapacity = 1000
)
  • Purpose: Defines the capacity of the writeCh channel.

checkAndSetOptions(opt *Options) error​

func checkAndSetOptions(opt *Options) error
  • Purpose: Validates and sets derived options based on user-provided options.
  • Parameters:
    • opt (*Options): Pointer to the options struct.
  • Returns:
    • error: An error if any validation fails.

Open(opt Options) (*DB, error)​

func Open(opt Options) (*DB, error)
  • Purpose: Opens a new Badger database.
  • Parameters:
    • opt (Options): The options for opening the database.
  • Returns:
    • *DB: A pointer to the opened database.
    • error: An error, if any.

DB.initBannedNamespaces() error​

func (db *DB) initBannedNamespaces() error
  • Purpose: Retrieves the banned namespaces from the DB and updates in-memory structure.
  • Parameters: None
  • Returns:
    • error: An error, if any.

DB.MaxVersion() uint64​

func (db *DB) MaxVersion() uint64
  • Purpose: Returns the maximum version of any key in the database.
  • Parameters: None
  • Returns:
    • uint64: The maximum version number.

DB.monitorCache(c *z.Closer)​

func (db *DB) monitorCache(c *z.Closer)
  • Purpose: Periodically monitors the block and index caches and logs warnings if they appear to be undersized.
  • Parameters:
    • c (*z.Closer): A closer to signal when the monitoring goroutine should exit.
  • Returns: None

DB.cleanup()​

func (db *DB) cleanup()
  • Purpose: Stops all goroutines started by badger. This is used in open to cleanup goroutines in case of an error.
  • Parameters: None
  • Returns: None

DB.BlockCacheMetrics() *ristretto.Metrics​

func (db *DB) BlockCacheMetrics() *ristretto.Metrics
  • Purpose: Returns the metrics for the underlying block cache.
  • Parameters: None
  • Returns:
    • *ristretto.Metrics: The metrics for the block cache, or nil if no block cache is configured.

DB.IndexCacheMetrics() *ristretto.Metrics​

func (db *DB) IndexCacheMetrics() *ristretto.Metrics
  • Purpose: Returns the metrics for the underlying index cache.
  • Parameters: None
  • Returns:
    • *ristretto.Metrics: The metrics for the index cache, or nil if no index cache is configured.

DB.Close() error​

func (db *DB) Close() error
  • Purpose: Closes the database, ensuring all pending updates are written to disk.
  • Parameters: None
  • Returns:
    • error: An error, if any.

DB.IsClosed() bool​

func (db *DB) IsClosed() bool
  • Purpose: Denotes if the badger DB is closed or not.
  • Parameters: None
  • Returns:
    • bool: True if the DB is closed, false otherwise.

DB.close() error​

func (db *DB) close() (err error)
  • Purpose: Internal implementation of closing the database.
  • Parameters: None
  • Returns:
    • error: An error, if any.

DB.VerifyChecksum() error​

func (db *DB) VerifyChecksum() error
  • Purpose: Verifies checksum for all tables on all levels.
  • Parameters: None
  • Returns:
    • error: An error if checksum verification fails.

lockFile constant​

const (
	lockFile = "LOCK"
)
  • Purpose: Defines the name of the lock file.

DB.Sync() error​

func (db *DB) Sync() error
  • Purpose: Syncs database content to disk.
  • Parameters: None
  • Returns:
    • error: An error, if any.

DB.getMemTables() ([]*memTable, func())​

func (db *DB) getMemTables() ([]*memTable, func())
  • Purpose: Returns the current memtables and get references.
  • Parameters: None
  • Returns:
    • []*memTable: A slice of memtables.
    • func(): A function to decrement the references of the memtables.

DB.get(key []byte) (y.ValueStruct, error)​

func (db *DB) get(key []byte) (y.ValueStruct, error)
  • Purpose: Returns the value in memtable or disk for given key.
  • Parameters:
    • key ([]byte): The key to search for.
  • Returns:
    • y.ValueStruct: The value struct associated with the key.
    • error: An error, if any.

requestPool variable​

var requestPool = sync.Pool{
	New: func() interface{} {
		return new(request)
	},
}
  • Purpose: Defines a pool of request objects to reduce allocations.

DB.writeToLSM(b *request) error​

func (db *DB) writeToLSM(b *request) error
  • Purpose: Writes the entries from the request to the LSM tree (memtable).
  • Parameters:
    • b (*request): The request containing the entries to write.
  • Returns:
    • error: An error, if any.

DB.writeRequests(reqs []*request) error​

func (db *DB) writeRequests(reqs []*request) error
  • Purpose: Writes multiple requests to the value log and memtable.
  • Parameters:
    • reqs ([]*request): A slice of requests to write.
  • Returns:
    • error: An error, if any.

DB.sendToWriteCh(entries []*Entry) (*request, error)​

func (db *DB) sendToWriteCh(entries []*Entry) (*request, error)
  • Purpose: Sends a slice of entries to the write channel for processing.
  • Parameters:
    • entries ([]*Entry): A slice of entries to write.
  • Returns:
    • *request: The request object, if successful.
    • error: An error, if any.

DB.doWrites(lc *z.Closer)​

func (db *DB) doWrites(lc *z.Closer)
  • Purpose: Goroutine that receives write requests from the writeCh and processes them.
  • Parameters:
    • lc (*z.Closer): A closer to signal when the goroutine should exit.
  • Returns: None

DB.batchSet(entries []*Entry) error​

func (db *DB) batchSet(entries []*Entry) error
  • Purpose: Applies a list of badger.Entry.
  • Parameters:
    • entries ([]*Entry): Slice of entries to be batched.
  • Returns:
    • error: An error, if any.

DB.batchSetAsync(entries []*Entry, f func(error)) error​

func (db *DB) batchSetAsync(entries []*Entry, f func(error)) error
  • Purpose: Asynchronous version of batchSet.
  • Parameters:
    • entries ([]*Entry): Slice of entries to be batched.
    • f (func(error)): Callback function to be called when all sets are complete.
  • Returns:
    • error: An error, if any.

errNoRoom variable​

var errNoRoom = errors.New("No room for write")
  • Purpose: Error returned when there is no room for write in the memtable.

DB.ensureRoomForWrite() error​

func (db *DB) ensureRoomForWrite() error
  • Purpose: Checks if the current memtable is full and attempts to create a new one.
  • Parameters: None
  • Returns:
    • error: An error, if any.

arenaSize(opt Options) int64​

func arenaSize(opt Options) int64
  • Purpose: Calculates the arena size based on the provided options.
  • Parameters:
    • opt (Options): Database options.
  • Returns:
    • int64: Arena size.

buildL0Table(iter y.Iterator, dropPrefixes [][]byte, bopts table.Options) *table.Builder​

func buildL0Table(iter y.Iterator, dropPrefixes [][]byte, bopts table.Options) *table.Builder
  • Purpose: Builds a new table from the memtable iterator.
  • Parameters:
    • iter (y.Iterator): Iterator for the memtable.
    • dropPrefixes ([][]byte): Prefixes to drop from the table.
    • bopts (table.Options): Table building options.
  • Returns:
    • *table.Builder: Table builder.

DB.handleMemTableFlush(mt *memTable, dropPrefixes [][]byte) error​

func (db *DB) handleMemTableFlush(mt *memTable, dropPrefixes [][]byte) error
  • Purpose: Handles flushing a memtable to disk.
  • Parameters:
    • mt (*memTable): The memtable to flush.
    • dropPrefixes ([][]byte): Prefixes to drop during the flush.
  • Returns:
    • error: An error, if any.

DB.flushMemtable(lc *z.Closer)​

func (db *DB) flushMemtable(lc *z.Closer)
  • Purpose: Goroutine that receives memtables from the flushChan and flushes them to disk.
  • Parameters:
    • lc (*z.Closer): A closer to signal when the goroutine should exit.
  • Returns: None

exists(path string) (bool, error)​

func exists(path string) (bool, error)
  • Purpose: Checks if a file or directory exists.
  • Parameters:
    • path (string): The path to check.
  • Returns:
    • bool: True if the path exists, false otherwise.
    • error: An error, if any.

DB.calculateSize()​

func (db *DB) calculateSize()
  • Purpose: Calculates the size of lsm and value log files and stores it in y.LSMSize and y.VlogSize.
  • Parameters: None
  • Returns: None

DB.updateSize(lc *z.Closer)​

func (db *DB) updateSize(lc *z.Closer)
  • Purpose: Goroutine that periodically updates the database size metrics.
  • Parameters:
    • lc (*z.Closer): A closer to signal when the goroutine should exit.
  • Returns: None

DB.RunValueLogGC(discardRatio float64) error​

func (db *DB) RunValueLogGC(discardRatio float64) error
  • Purpose: Triggers a value log garbage collection.
  • Parameters:
    • discardRatio (float64): The discard ratio for determining which log files to rewrite.
  • Returns:
    • error: An error, if any.

DB.Size() (lsm, vlog int64)​

func (db *DB) Size() (lsm, vlog int64)
  • Purpose: Returns the size of lsm and value log files in bytes.
  • Parameters: None
  • Returns:
    • lsm (int64): LSM size.
    • vlog (int64): Value log size.

Sequence struct​

type Sequence struct {
	lock      sync.Mutex
	db        *DB
	key       []byte
	next      uint64
	leased    uint64
	bandwidth uint64
}
  • Purpose: Represents a Badger sequence.

Sequence.Next() (uint64, error)​

func (seq *Sequence) Next() (uint64, error)
  • Purpose: Returns the next integer in the sequence, updating the lease by running a transaction if needed.
  • Parameters: None
  • Returns:
    • uint64: Next integer.
    • error: An error, if any.

Sequence.Release() error​

func (seq *Sequence) Release() error
  • Purpose: Releases the leased sequence to avoid wasted integers.
  • Parameters: None
  • Returns:
    • error: An error, if any.

Sequence.updateLease() error​

func (seq *Sequence) updateLease() error
  • Purpose: Updates the lease for the sequence.
  • Parameters: None
  • Returns:
    • error: An error, if any.

DB.GetSequence(key []byte, bandwidth uint64) (*Sequence, error)​

func (db *DB) GetSequence(key []byte, bandwidth uint64) (*Sequence, error)
  • Purpose: Initiates a new sequence object.
  • Parameters:
    • key ([]byte): Key for sequence.
    • bandwidth (uint64): Size of the lease.
  • Returns:
    • *Sequence: The Sequence object.
    • error: An error, if any.

DB.Tables() []TableInfo​

func (db *DB) Tables() []TableInfo
  • Purpose: Gets the TableInfo objects from the level controller.
  • Parameters: None
  • Returns:
    • []TableInfo: TableInfo objects.

DB.Levels() []LevelInfo​

func (db *DB) Levels() []LevelInfo
  • Purpose: Gets the LevelInfo.
  • Parameters: None
  • Returns:
    • []LevelInfo: LevelInfo.

DB.EstimateSize(prefix []byte) (uint64, uint64)​

func (db *DB) EstimateSize(prefix []byte) (uint64, uint64)
  • Purpose: Can be used to get rough estimate of data size for a given prefix.
  • Parameters:
    • prefix ([]byte): The prefix to estimate size for.
  • Returns:
    • uint64: On disk size
    • uint64: Uncompressed size

DB.Ranges(prefix []byte, numRanges int) []*keyRange​

func (db *DB) Ranges(prefix []byte, numRanges int) []*keyRange
  • Purpose: Can be used to get rough key ranges to divide up iteration over the DB.
  • Parameters:
    • prefix ([]byte): Key prefix.
    • numRanges (int): Number of ranges.
  • Returns:
    • []*keyRange: Slices of key ranges.

DB.MaxBatchCount() int64​

func (db *DB) MaxBatchCount() int64
  • Purpose: Returns max possible entries in batch
  • Parameters: None
  • Returns:
    • int64: Max batch count.

DB.MaxBatchSize() int64​

func (db *DB) MaxBatchSize() int64
  • Purpose: Returns max possible batch size
  • Parameters: None
  • Returns:
    • int64: Max batch size.

DB.stopMemoryFlush()​

func (db *DB) stopMemoryFlush()
  • Purpose: Stops memtable flushes.
  • Parameters: None
  • Returns: None

DB.stopCompactions()​

func (db *DB) stopCompactions()
  • Purpose: Stops compactions.
  • Parameters: None
  • Returns: None

DB.startCompactions()​

func (db *DB) startCompactions()
  • Purpose: Resume compactions.
  • Parameters: None
  • Returns: None

DB.startMemoryFlush()​

func (db *DB) startMemoryFlush()
  • Purpose: Start memory fluhser.
  • Parameters: None
  • Returns: None

DB.Flatten(workers int) error​

func (db *DB) Flatten(workers int) error
  • Purpose: Can be used to force compactions on the LSM tree so all the tables fall on the same level.
  • Parameters:
    • workers (int): Number of workers for compaction.
  • Returns:
    • error: An error, if any.

DB.blockWrite() error​

func (db *DB) blockWrite() error
  • Purpose: Blocks incoming writes.
  • Parameters: None
  • Returns:
    • error: An error, if any.

DB.unblockWrite()​

func (db *DB) unblockWrite()
  • Purpose: Unblocks incoming writes.
  • Parameters: None
  • Returns: None

DB.prepareToDrop() (func(), error)​

func (db *DB) prepareToDrop() (func(), error)
  • Purpose: Prepares the database for dropping all data.
  • Parameters: None
  • Returns:
    • func(): A function to resume writes after dropping.
    • error: An error, if any.

DB.DropAll() error​

func (db *DB) DropAll() error
  • Purpose: Would drop all the data stored in Badger.
  • Parameters: None
  • Returns:
    • error: An error, if any.

DB.dropAll() (func(), error)​

func (db *DB) dropAll() (func(), error)
  • Purpose: Internal implementation for dropping all data.
  • Parameters: None
  • Returns:
    • func(): A function to resume operations after dropping.
    • error: An error, if any.

DB.DropPrefix(prefixes ...[]byte) error​

func (db *DB) DropPrefix(prefixes ...[]byte) error
  • Purpose: Would drop all the keys with the provided prefix.
  • Parameters:
    • prefixes (...[]byte): Prefixes to drop.
  • Returns:
    • error: An error, if any.

DB.filterPrefixesToDrop(prefixes [][]byte) ([][]byte, error)​

func (db *DB) filterPrefixesToDrop(prefixes [][]byte) ([][]byte, error)
  • Purpose: Filters the prefixes for which the data already exist.
  • Parameters:
    • prefixes ([][]byte): Prefixes to drop.
  • Returns:
    • [][]byte: The filtered prefixes to drop.
    • error: An error, if any.

DB.isBanned(key []byte) error​

func (db *DB) isBanned(key []byte) error
  • Purpose: Checks if the key is banned.
  • Parameters:
    • key ([]byte): Key to check.
  • Returns:
    • error: Returns ErrBannedKey if the key belongs to any of the banned namepspaces, else it returns nil.

DB.BanNamespace(ns uint64) error​

func (db *DB) BanNamespace(ns uint64) error
  • Purpose: Bans a namespace.
  • Parameters:
    • ns (uint64): Namespace to ban.
  • Returns:
    • error: An error, if any.

DB.BannedNamespaces() []uint64​

func (db *DB) BannedNamespaces() []uint64
  • Purpose: Returns the list of prefixes banned for DB.
  • Parameters: None
  • Returns:
    • []uint64: A slice of banned namespaces.

KVList type​

type KVList = pb.KVList
  • Purpose: Type alias for pb.KVList.

DB.Subscribe(ctx context.Context, cb func(kv *KVList) error, matches []pb.Match) error​

func (db *DB) Subscribe(ctx context.Context, cb func(kv *KVList) error, matches []pb.Match) error
  • Purpose: Can be used to watch key changes for the given key prefixes and the ignore string.
  • Parameters:
    • ctx (context.Context): Context for cancellation.
    • cb (func(kv *KVList) error): Callback function.
    • matches ([]pb.Match): Slice of matches.
  • Returns:
    • error: An error, if any.

DB.syncDir(dir string) error​

func (db *DB) syncDir(dir string) error
  • Purpose: Syncs directory content to disk.
  • Parameters:
    • dir (string): Directory path.
  • Returns:
    • error: An error, if any.

createDirs(opt Options) error​

func createDirs(opt Options) error
  • Purpose: Creates directories if they don't exist.
  • Parameters:
    • opt (Options): The options containing the directory paths.
  • Returns:
    • error: An error, if any.

DB.StreamDB(outOptions Options) error​

func (db *DB) StreamDB(outOptions Options) error
  • Purpose: Stream the contents of this DB to a new DB with options outOptions that will be created in outDir.
  • Parameters:
    • outOptions (Options): Options for the output database.
  • Returns:
    • error: An error, if any.

DB.Opts() Options​

func (db *DB) Opts() Options
  • Purpose: Returns a copy of the DB options.
  • Parameters: None
  • Returns:
    • Options: A copy of the database options.

CacheType type​

type CacheType int
  • Purpose: Represents the type of cache.

BlockCache constant​

const (
	BlockCache CacheType = iota
	IndexCache
)
  • Purpose: Represents Block Cache type.

IndexCache constant​

const (
	BlockCache CacheType = iota
	IndexCache
)
  • Purpose: Represents Index Cache type.

DB.CacheMaxCost(cache CacheType, maxCost int64) (int64, error)​

func (db *DB) CacheMaxCost(cache CacheType, maxCost int64) (int64, error)
  • Purpose: Updates the max cost of the given cache (either block or index cache).
  • Parameters:
    • cache (CacheType): Type of cache.
    • maxCost (int64): Maximum cost.
  • Returns:
    • int64: The maximum cost set.
    • error: An error, if any.

DB.LevelsToString() string​

func (db *DB) LevelsToString() string
  • Purpose: String representation of the levels in DB.
  • Parameters: None
  • Returns:
    • string: String containing level information.

Code Examples​

Example of opening a database:

package main

import (
	"log"

	badger "github.com/dgraph-io/badger/v4"
)

func main() {
	opts := badger.DefaultOptions("/tmp/badger")
	db, err := badger.Open(opts)
	if err != nil {
		log.Fatal(err)
	}
	defer db.Close()
	// Your code here…
}

Getting Started Relevance​