Skip to main content

options.go

options.go - Overview​

This file defines the Options struct and related functions for configuring a BadgerDB instance. It includes default option settings, methods for modifying options, and functions for parsing and generating option flags.

Detailed Documentation​

Options​

type Options struct {
    testOnlyOptions

    // Required options.

    Dir      string
    ValueDir string

    // Usually modified options.

    SyncWrites        bool
    NumVersionsToKeep int
    ReadOnly          bool
    Logger            Logger
    Compression       options.CompressionType
    InMemory          bool
    MetricsEnabled    bool
    // Sets the Stream.numGo field
    NumGoroutines int

    // Fine tuning options.

    MemTableSize        int64
    BaseTableSize       int64
    BaseLevelSize       int64
    LevelSizeMultiplier int
    TableSizeMultiplier int
    MaxLevels           int

    VLogPercentile float64
    ValueThreshold int64
    NumMemtables   int
    // Changing BlockSize across DB runs will not break badger. The block size is
    // read from the block index stored at the end of the table.
    BlockSize          int
    BloomFalsePositive float64
    BlockCacheSize     int64
    IndexCacheSize     int64

    NumLevelZeroTables      int
    NumLevelZeroTablesStall int

    ValueLogFileSize   int64
    ValueLogMaxEntries uint32

    NumCompactors        int
    CompactL0OnClose     bool
    LmaxCompaction       bool
    ZSTDCompressionLevel int

    // When set, checksum will be validated for each entry read from the value log file.
    VerifyValueChecksum bool

    // Encryption related options.
    EncryptionKey                 []byte        // encryption key
    EncryptionKeyRotationDuration time.Duration // key rotation duration

    // BypassLockGuard will bypass the lock guard on badger. Bypassing lock
    // guard can cause data corruption if multiple badger instances are using
    // the same directory. Use this options with caution.
    BypassLockGuard bool

    // ChecksumVerificationMode decides when db should verify checksums for SSTable blocks.
    ChecksumVerificationMode options.ChecksumVerificationMode

    // DetectConflicts determines whether the transactions would be checked for
    // conflicts. The transactions can be processed at a higher rate when
    // conflict detection is disabled.
    DetectConflicts bool

    // NamespaceOffset specifies the offset from where the next 8 bytes contains the namespace.
    NamespaceOffset int

    // Magic version used by the application using badger to ensure that it doesn't open the DB
    // with incompatible data format.
    ExternalMagicVersion uint16

    // Transaction start and commit timestamps are managed by end-user.
    // This is only useful for databases built on top of Badger (like Dgraph).
    // Not recommended for most users.
    managedTxns bool

    // 4. Flags for testing purposes
    // ------------------------------
    maxBatchCount int64 // max entries in batch
    maxBatchSize  int64 // max batch size in bytes

    maxValueThreshold float64
}
  • Purpose: Defines the configuration options for a BadgerDB instance.
  • Parameters:
    • testOnlyOptions: Unclear.
    • Dir: string - Path to the directory for key data.
    • ValueDir: string - Path to the directory for value data.
    • SyncWrites: bool - If true, Badger calls msync after writes.
    • NumVersionsToKeep: int - Maximum number of versions to keep per key.
    • ReadOnly: bool - If true, the DB is opened in read-only mode.
    • Logger: Logger - Logger interface for logging.
    • Compression: options.CompressionType - Compression type to use.
    • InMemory: bool - If true, data is stored in memory only.
    • MetricsEnabled: bool - If true, metrics are enabled.
    • NumGoroutines: int - Number of goroutines to be used in Stream.
    • MemTableSize: int64 - Maximum size in bytes for memtable table.
    • BaseTableSize: int64 - Maximum size in bytes for LSM table in the base level.
    • BaseLevelSize: int64 - Maximum size target for the base level.
    • LevelSizeMultiplier: int - Ratio between the maximum sizes of contiguous levels in the LSM.
    • TableSizeMultiplier: int - Unclear.
    • MaxLevels: int - Maximum number of levels of compaction allowed in the LSM.
    • VLogPercentile: float64 - Percentile of values to be stored in the LSM tree.
    • ValueThreshold: int64 - Threshold to decide whether a value is stored in the LSM tree or value log.
    • NumMemtables: int - Maximum number of tables to keep in memory before stalling.
    • BlockSize: int - Size of any block in SSTable.
    • BloomFalsePositive: float64 - False positive probability of the bloom filter in any SSTable.
    • BlockCacheSize: int64 - How much data cache should hold in memory.
    • IndexCacheSize: int64 - How much memory should be used by table indices.
    • NumLevelZeroTables: int - Maximum number of Level 0 tables before compaction starts.
    • NumLevelZeroTablesStall: int - Number of Level 0 tables that cause the DB to stall until compaction succeeds.
    • ValueLogFileSize: int64 - Maximum size of a single value log file.
    • ValueLogMaxEntries: uint32 - Maximum number of entries a value log file can hold approximately.
    • NumCompactors: int - Number of compaction workers to run concurrently.
    • CompactL0OnClose: bool - If true, Level 0 should be compacted before closing the DB.
    • LmaxCompaction: bool - Unclear.
    • ZSTDCompressionLevel: int - ZSTD compression level.
    • VerifyValueChecksum: bool - If true, checksum will be verified for every entry read from the value log.
    • EncryptionKey: []byte - Encryption key.
    • EncryptionKeyRotationDuration: time.Duration - Key rotation duration.
    • BypassLockGuard: bool - If true, badger will not acquire a lock on the directory.
    • ChecksumVerificationMode: options.ChecksumVerificationMode - Indicates when the db should verify checksums for SSTable blocks.
    • DetectConflicts: bool - Determines if the transactions would be checked for conflicts.
    • NamespaceOffset: int - Specifies the offset from where the next 8 bytes contains the namespace.
    • ExternalMagicVersion: uint16 - Magic version used by the application.
    • managedTxns: bool - If true, transaction start and commit timestamps are managed by end-user.
    • maxBatchCount: int64 - Unclear.
    • maxBatchSize: int64 - Unclear.
    • maxValueThreshold: float64 - Unclear.
  • Returns: None

DefaultOptions​

func DefaultOptions(path string) Options
  • Purpose: Sets a list of recommended options for good performance.
  • Parameters:
    • path: string - The path for the database directory.
  • Returns: Options - An Options struct with default values set.

buildTableOptions​

func buildTableOptions(db *DB) table.Options
  • Purpose: Builds table options from the DB options.
  • Parameters:
    • db: *DB - A pointer to the DB instance.
  • Returns: table.Options - The table options.

LSMOnlyOptions​

func LSMOnlyOptions(path string) Options
  • Purpose: Sets options optimized for LSM tree usage, with a higher ValueThreshold.
  • Parameters:
    • path: string - The path for the database directory.
  • Returns: Options - An Options struct with LSM-optimized values set.

parseCompression​

func parseCompression(cStr string) (options.CompressionType, int, error)
  • Purpose: Parses a compression string of the format compression-type:compression-level.
  • Parameters:
    • cStr: string - The compression string to parse.
  • Returns:
    • options.CompressionType - The compression type.
    • int - The compression level.
    • error - An error if parsing fails.

generateSuperFlag​

func generateSuperFlag(options Options) string
  • Purpose: Generates an identical SuperFlag string from the provided Options.
  • Parameters:
    • options: Options - The options to generate the superflag from.
  • Returns: string - The generated superflag string.

(*Options) FromSuperFlag​

func (opt Options) FromSuperFlag(superflag string) Options
  • Purpose: Fills Options fields from a superflag string.
  • Parameters:
    • superflag: string - The superflag string to parse.
  • Returns: Options - The modified Options struct.

(*Options) WithDir​

func (opt Options) WithDir(val string) Options
  • Purpose: Returns a new Options value with Dir set to the given value.
  • Parameters:
    • val: string - The directory path.
  • Returns: Options - A new Options struct with the Dir field updated.

(*Options) WithValueDir​

func (opt Options) WithValueDir(val string) Options
  • Purpose: Returns a new Options value with ValueDir set to the given value.
  • Parameters:
    • val: string - The value directory path.
  • Returns: Options - A new Options struct with the ValueDir field updated.

(*Options) WithSyncWrites​

func (opt Options) WithSyncWrites(val bool) Options
  • Purpose: Returns a new Options value with SyncWrites set to the given value.
  • Parameters:
    • val: bool - Whether to enable synchronous writes.
  • Returns: Options - A new Options struct with the SyncWrites field updated.

(*Options) WithNumVersionsToKeep​

func (opt Options) WithNumVersionsToKeep(val int) Options
  • Purpose: Returns a new Options value with NumVersionsToKeep set to the given value.
  • Parameters:
    • val: int - The number of versions to keep.
  • Returns: Options - A new Options struct with the NumVersionsToKeep field updated.

(*Options) WithNumGoroutines​

func (opt Options) WithNumGoroutines(val int) Options
  • Purpose: Returns a new Options value with NumGoroutines set to the given value.
  • Parameters:
    • val: int - The number of goroutines to use.
  • Returns: Options - A new Options struct with the NumGoroutines field updated.

(*Options) WithReadOnly​

func (opt Options) WithReadOnly(val bool) Options
  • Purpose: Returns a new Options value with ReadOnly set to the given value.
  • Parameters:
    • val: bool - Whether to open the database in read-only mode.
  • Returns: Options - A new Options struct with the ReadOnly field updated.

(*Options) WithMetricsEnabled​

func (opt Options) WithMetricsEnabled(val bool) Options
  • Purpose: Returns a new Options value with MetricsEnabled set to the given value.
  • Parameters:
    • val: bool - Whether to enable metrics.
  • Returns: Options - A new Options struct with the MetricsEnabled field updated.

(*Options) WithLogger​

func (opt Options) WithLogger(val Logger) Options
  • Purpose: Returns a new Options value with Logger set to the given value.
  • Parameters:
    • val: Logger - The logger to use.
  • Returns: Options - A new Options struct with the Logger field updated.

(*Options) WithLoggingLevel​

func (opt Options) WithLoggingLevel(val loggingLevel) Options
  • Purpose: Returns a new Options value with logging level of the default logger set to the given value.
  • Parameters:
    • val: loggingLevel - The logging level to set.
  • Returns: Options - A new Options struct with the logging level updated.

(*Options) WithBaseTableSize​

func (opt Options) WithBaseTableSize(val int64) Options
  • Purpose: Returns a new Options value with BaseTableSize set to the given value.
  • Parameters:
    • val: int64 - The base table size.
  • Returns: Options - A new Options struct with the BaseTableSize field updated.

(*Options) WithLevelSizeMultiplier​

func (opt Options) WithLevelSizeMultiplier(val int) Options
  • Purpose: Returns a new Options value with LevelSizeMultiplier set to the given value.
  • Parameters:
    • val: int - The level size multiplier.
  • Returns: Options - A new Options struct with the LevelSizeMultiplier field updated.

(*Options) WithMaxLevels​

func (opt Options) WithMaxLevels(val int) Options
  • Purpose: Returns a new Options value with MaxLevels set to the given value.
  • Parameters:
    • val: int - The maximum number of levels.
  • Returns: Options - A new Options struct with the MaxLevels field updated.

(*Options) WithValueThreshold​

func (opt Options) WithValueThreshold(val int64) Options
  • Purpose: Returns a new Options value with ValueThreshold set to the given value.
  • Parameters:
    • val: int64 - The value threshold.
  • Returns: Options - A new Options struct with the ValueThreshold field updated.

(*Options) WithVLogPercentile​

func (opt Options) WithVLogPercentile(t float64) Options
  • Purpose: Returns a new Options value with VLogPercentile set to given value.
  • Parameters:
    • t: float64 - The vlog percentile.
  • Returns: Options - A new Options struct with the VLogPercentile field updated.

(*Options) WithNumMemtables​

func (opt Options) WithNumMemtables(val int) Options
  • Purpose: Returns a new Options value with NumMemtables set to the given value.
  • Parameters:
    • val: int - The number of memtables.
  • Returns: Options - A new Options struct with the NumMemtables field updated.

(*Options) WithMemTableSize​

func (opt Options) WithMemTableSize(val int64) Options
  • Purpose: Returns a new Options value with MemTableSize set to the given value.
  • Parameters:
    • val: int64 - The memtable size.
  • Returns: Options - A new Options struct with the MemTableSize field updated.

(*Options) WithBloomFalsePositive​

func (opt Options) WithBloomFalsePositive(val float64) Options
  • Purpose: Returns a new Options value with BloomFalsePositive set to the given value.
  • Parameters:
    • val: float64 - The bloom filter false positive probability.
  • Returns: Options - A new Options struct with the BloomFalsePositive field updated.

(*Options) WithBlockSize​

func (opt Options) WithBlockSize(val int) Options
  • Purpose: Returns a new Options value with BlockSize set to the given value.
  • Parameters:
    • val: int - The block size.
  • Returns: Options - A new Options struct with the BlockSize field updated.

(*Options) WithNumLevelZeroTables​

func (opt Options) WithNumLevelZeroTables(val int) Options
  • Purpose: Returns a new Options value with NumLevelZeroTables set to the given value.
  • Parameters:
    • val: int - The number of level zero tables.
  • Returns: Options - A new Options struct with the NumLevelZeroTables field updated.

(*Options) WithNumLevelZeroTablesStall​

func (opt Options) WithNumLevelZeroTablesStall(val int) Options
  • Purpose: Returns a new Options value with NumLevelZeroTablesStall set to the given value.
  • Parameters:
    • val: int - The number of level zero tables stall.
  • Returns: Options - A new Options struct with the NumLevelZeroTablesStall field updated.

(*Options) WithBaseLevelSize​

func (opt Options) WithBaseLevelSize(val int64) Options
  • Purpose: Returns a new Options value with BaseLevelSize set to the given value.
  • Parameters:
    • val: int64 - The base level size.
  • Returns: Options - A new Options struct with the BaseLevelSize field updated.

(*Options) WithValueLogFileSize​

func (opt Options) WithValueLogFileSize(val int64) Options
  • Purpose: Returns a new Options value with ValueLogFileSize set to the given value.
  • Parameters:
    • val: int64 - The value log file size.
  • Returns: Options - A new Options struct with the ValueLogFileSize field updated.

(*Options) WithValueLogMaxEntries​

func (opt Options) WithValueLogMaxEntries(val uint32) Options
  • Purpose: Returns a new Options value with ValueLogMaxEntries set to the given value.
  • Parameters:
    • val: uint32 - The value log max entries.
  • Returns: Options - A new Options struct with the ValueLogMaxEntries field updated.

(*Options) WithNumCompactors​

func (opt Options) WithNumCompactors(val int) Options
  • Purpose: Returns a new Options value with NumCompactors set to the given value.
  • Parameters:
    • val: int - The number of compactors.
  • Returns: Options - A new Options struct with the NumCompactors field updated.

(*Options) WithCompactL0OnClose​

func (opt Options) WithCompactL0OnClose(val bool) Options
  • Purpose: Returns a new Options value with CompactL0OnClose set to the given value.
  • Parameters:
    • val: bool - Whether to compact L0 on close.
  • Returns: Options - A new Options struct with the CompactL0OnClose field updated.

(*Options) WithEncryptionKey​

func (opt Options) WithEncryptionKey(key []byte) Options
  • Purpose: Returns a new Options value with EncryptionKey set to the given value.
  • Parameters:
    • key: []byte - The encryption key.
  • Returns: Options - A new Options struct with the EncryptionKey field updated.

(*Options) WithEncryptionKeyRotationDuration​

func (opt Options) WithEncryptionKeyRotationDuration(d time.Duration) Options
  • Purpose: Returns new Options value with the duration set to the given value.
  • Parameters:
    • d: time.Duration - The key rotation duration.
  • Returns: Options - A new Options struct with the EncryptionKeyRotationDuration field updated.

(*Options) WithCompression​

func (opt Options) WithCompression(cType options.CompressionType) Options
  • Purpose: Returns a new Options value with Compression set to the given value.
  • Parameters:
    • cType: options.CompressionType - The compression type.
  • Returns: Options - A new Options struct with the Compression field updated.

(*Options) WithVerifyValueChecksum​

func (opt Options) WithVerifyValueChecksum(val bool) Options
  • Purpose: Returns a new Options value with VerifyValueChecksum set to the given value.
  • Parameters:
    • val: bool - Whether to verify value checksum.
  • Returns: Options - A new Options struct with the VerifyValueChecksum field updated.

(*Options) WithChecksumVerificationMode​

func (opt Options) WithChecksumVerificationMode(cvMode options.ChecksumVerificationMode) Options
  • Purpose: Returns a new Options value with ChecksumVerificationMode set to the given value.
  • Parameters:
    • cvMode: options.ChecksumVerificationMode - The checksum verification mode.
  • Returns: Options - A new Options struct with the ChecksumVerificationMode field updated.

(*Options) WithBlockCacheSize​

func (opt Options) WithBlockCacheSize(size int64) Options
  • Purpose: Returns a new Options value with BlockCacheSize set to the given value.
  • Parameters:
    • size: int64 - The block cache size.
  • Returns: Options - A new Options struct with the BlockCacheSize field updated.

(*Options) WithInMemory​

func (opt Options) WithInMemory(b bool) Options
  • Purpose: Returns a new Options value with InMemory mode set to the given value.
  • Parameters:
    • b: bool - Whether to enable in-memory mode.
  • Returns: Options - A new Options struct with the InMemory field updated.

(*Options) WithZSTDCompressionLevel​

func (opt Options) WithZSTDCompressionLevel(cLevel int) Options
  • Purpose: Returns a new Options value with ZSTDCompressionLevel set to the given value.
  • Parameters:
    • cLevel: int - The ZSTD compression level.
  • Returns: Options - A new Options struct with the ZSTDCompressionLevel field updated.

(*Options) WithBypassLockGuard​

func (opt Options) WithBypassLockGuard(b bool) Options
  • Purpose: Returns a new Options value with BypassLockGuard set to the given value.
  • Parameters:
    • b: bool - Whether to bypass the lock guard.
  • Returns: Options - A new Options struct with the BypassLockGuard field updated.

(*Options) WithIndexCacheSize​

func (opt Options) WithIndexCacheSize(size int64) Options
  • Purpose: Returns a new Options value with IndexCacheSize set to the given value.
  • Parameters:
    • size: int64 - The index cache size.
  • Returns: Options - A new Options struct with the IndexCacheSize field updated.

(*Options) WithDetectConflicts​

func (opt Options) WithDetectConflicts(b bool) Options
  • Purpose: Returns a new Options value with DetectConflicts set to the given value.
  • Parameters:
    • b: bool - Whether to detect conflicts.
  • Returns: Options - A new Options struct with the DetectConflicts field updated.

(*Options) WithNamespaceOffset​

func (opt Options) WithNamespaceOffset(offset int) Options
  • Purpose: Returns a new Options value with NamespaceOffset set to the given value.
  • Parameters:
    • offset: int - The namespace offset.
  • Returns: Options - A new Options struct with the NamespaceOffset field updated.

(*Options) WithExternalMagic​

func (opt Options) WithExternalMagic(magic uint16) Options
  • Purpose: Returns a new Options value with ExternalMagicVersion set to the given value.
  • Parameters:
    • magic: uint16 - The external magic version.
  • Returns: Options - A new Options struct with the ExternalMagicVersion field updated.

(*Options) getFileFlags​

func (opt Options) getFileFlags() int
  • Purpose: Gets file flags based on options.
  • Parameters: None
  • Returns: int - The file flags.

Code Examples​

// Example of creating default options:
options := DefaultOptions("/path/to/db")

// Example of modifying options:
options = options.WithSyncWrites(true).WithCompression(options.Snappy)

Getting Started Relevance​