gdbx

package module
v0.0.0-...-5bdcda0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 28, 2026 License: MIT Imports: 15 Imported by: 0

README

gdbx

A pure Go implementation of MDBX, the high-performance embedded transactional key-value database. File-format compatible with libmdbx.

Performance

Benchmarks comparing gdbx against mdbx-go (CGO wrapper), BoltDB, and RocksDB on AMD Ryzen 5 3600.

8-byte Keys (uint64)

Common case for database IDs. gdbx uses assembly-optimized binary search with BSWAP+CMP.

Write Operations (ns/op, lower is better)
Operation Entries gdbx mdbx BoltDB RocksDB vs mdbx vs Bolt vs Rocks
SeqPut 10K 131 230 859 2271 1.8x 6.6x 17.3x
RandPut 10K 130 227 862 2106 1.7x 6.6x 16.2x
CursorPut 10K 117 178 867 2264 1.5x 7.4x 19.4x
SeqPut 100K 156 252 875 1979 1.6x 5.6x 12.7x
RandPut 100K 150 263 876 1810 1.8x 5.8x 12.1x
CursorPut 100K 157 175 888 1832 1.1x 5.7x 11.7x
SeqPut 1M 166 284 660 1136 1.7x 4.0x 6.8x
RandPut 1M 165 286 717 1080 1.7x 4.3x 6.5x
CursorPut 1M 160 189 698 1114 1.2x 4.4x 7.0x
Read Operations (ns/op, lower is better)
Operation Entries gdbx mdbx BoltDB RocksDB vs mdbx vs Bolt vs Rocks
SeqRead 10K 31 113 12 189 3.6x 0.4x 6.1x
RandGet 10K 94 212 860 2155 2.3x 9.1x 22.9x
RandSeek 10K 102 196 535 1214 1.9x 5.2x 11.9x
SeqRead 100K 31 114 18 848 3.7x 0.6x 27.4x
RandGet 100K 118 259 1000 2510 2.2x 8.5x 21.3x
RandSeek 100K 125 200 670 2335 1.6x 5.4x 18.7x
SeqRead 1M 37 113 22 925 3.1x 0.6x 25.0x
RandGet 1M 155 259 1121 2258 1.7x 7.2x 14.6x
RandSeek 1M 134 200 744 2718 1.5x 5.6x 20.3x

Note: BoltDB wins sequential reads due to simpler cursor iteration, but gdbx dominates random access.

64-byte Keys

Longer keys use SSE2-optimized binary search comparing 16 bytes at a time.

Write Operations (ns/op, lower is better)
Operation Entries gdbx mdbx BoltDB RocksDB vs mdbx vs Bolt vs Rocks
SeqPut 10K 202 238 565 2316 1.2x 2.8x 11.5x
RandPut 10K 192 242 568 2083 1.3x 3.0x 10.8x
SeqPut 100K 227 261 610 1723 1.2x 2.7x 7.6x
RandPut 100K 231 261 652 1575 1.1x 2.8x 6.8x
SeqPut 1M 268 312 800 1022 1.2x 3.0x 3.8x
RandPut 1M 269 284 901 1032 1.1x 3.3x 3.8x
Read Operations (ns/op, lower is better)
Operation Entries gdbx mdbx BoltDB RocksDB vs mdbx vs Bolt vs Rocks
SeqRead 10K 34 113 23 158 3.3x 0.7x 4.6x
RandGet 10K 110 221 975 1481 2.0x 8.9x 13.5x
RandSeek 10K 155 210 610 674 1.4x 3.9x 4.3x
SeqRead 100K 35 116 20 158 3.3x 0.6x 4.5x
RandGet 100K 145 244 1074 1265 1.7x 7.4x 8.7x
RandSeek 100K 199 216 651 803 1.1x 3.3x 4.0x
SeqRead 1M 42 121 19 283 2.9x 0.5x 6.7x
RandGet 1M 182 274 1082 2311 1.5x 5.9x 12.7x
RandSeek 1M 225 215 665 1588 1.0x 3.0x 7.1x
Big Values (8KB)

Large values use zero-copy reads (direct mmap slice) and in-place overflow page updates.

Write Operations (ns/op)
Operation Entries gdbx mdbx BoltDB RocksDB vs mdbx vs Bolt vs Rocks
SeqPut 100 268 315 525 2810 1.2x 2.0x 10.5x
RandPut 100 290 308 535 3378 1.1x 1.8x 11.6x
SeqPut 1K 340 420 768 4274 1.2x 2.3x 12.6x
RandPut 1K 346 438 776 4061 1.3x 2.2x 11.7x
SeqPut 10K 793 688 832 27834 0.9x 1.0x 35.1x
RandPut 10K 896 690 843 28356 0.8x 0.9x 31.6x
Read Operations (ns/op)
Operation Entries gdbx mdbx BoltDB RocksDB vs mdbx vs Bolt vs Rocks
SeqRead 100 41 126 21 2682 3.1x 0.5x 65.4x
RandGet 100 44 185 473 1533 4.2x 10.7x 34.8x
SeqRead 1K 42 129 77 28679 3.1x 1.8x 683x
RandGet 1K 97 209 921 2310 2.2x 9.5x 23.8x
SeqRead 10K 43 221 112 8605 5.1x 2.6x 200x
RandGet 10K 104 323 1067 10713 3.1x 10.3x 103x

Big value reads use zero-copy (direct mmap slice), achieving 78-200 GB/s throughput.

DBI/Transaction Operations
Operation gdbx mdbx vs mdbx
OpenDBI 27ns 244ns 9.0x faster
BeginTxn (read-only) 139ns 303ns 2.2x faster
BeginTxn (read-write) 2108ns 281ns mdbx faster*

*gdbx uses file-based flock() which has syscall overhead; mdbx uses shared memory locks.

Memory
  • Zero allocations on all Put operations
  • Zero allocations on read-only transactions
  • Zero allocations on OpenDBI
  • Zero allocations on cursor operations

Features

  • 100% pure Go, no CGO
  • File-format compatible with libmdbx
  • ACID transactions with MVCC
  • Memory-mapped I/O
  • B+ tree storage
  • DupSort tables
  • Nested transaction infrastructure (parent page delegation)
  • Zero heap allocations on writes (dirty pages in mmap'd spill buffer)

Implementation Differences vs libmdbx

gdbx is file-format compatible with libmdbx but the implementation differs:

Locking
  • libmdbx: Configurable via MDBX_LOCKING build option. Supports SystemV IPC semaphores (default), POSIX shared mutexes, POSIX-2008 robust mutexes, or Win32 file locking. Lock state stored in shared memory (lock file) with complex handoff protocols.
  • gdbx: Uses file-based flock() for writer lock. Simpler but higher syscall overhead per write transaction.
  • Rationale: flock() is available on all Unix systems and Windows (via syscall), requires no platform-specific code paths, and is simple to reason about. The ~2us overhead per write transaction is acceptable since actual write work dominates. Avoiding IPC semaphores eliminates cleanup issues on process crash.
Reader Registration
  • libmdbx: Lock-free reader slot acquisition using atomic CAS with PID/TID tracking. Supports reader "parking" for long transactions.
  • gdbx: Similar slot-based tracking with atomic operations, but uses LIFO freelist for O(1) slot acquisition. No parking support.
  • Rationale: LIFO freelist gives O(1) slot acquisition in the common case (reusing recently-freed slots), which is cache-friendly. Parking adds complexity for a rare use case - most applications don't hold read transactions for extended periods.
Page Management
  • libmdbx: Complex spill/unspill mechanism to handle dirty pages exceeding RAM. Pages can be temporarily written to disk and reloaded.
  • gdbx: Dirty pages stored in a memory-mapped spill buffer (spill/ package) rather than Go heap. The spill buffer uses a segmented design with multiple mmap regions to allow growth without invalidating existing page slices. Each segment has its own bitmap for O(1) slot allocation. Page lookups use a fibonacci hash map (open addressing with linear probing).
  • Rationale: Storing dirty pages in mmap'd memory eliminates GC pressure entirely - the OS manages paging while Go sees only small slot metadata. The segmented design avoids remapping (which would invalidate existing slices) by simply adding new segments when capacity is exhausted. This achieves zero heap allocations on all write operations while supporting large transactions.
Garbage Collection
  • libmdbx: LIFO page reclamation with "backlog" management. Tracks retired pages per transaction with complex coalescing.
  • gdbx: LIFO reclamation via FreeDBI. Freed pages added to transaction's free list, written to GC tree on commit.
  • Rationale: Both use LIFO for cache efficiency (recently-freed pages are hot). gdbx skips backlog tracking since Go's GC handles memory pressure differently than C. Simpler code with same disk format.
Copy-on-Write
  • libmdbx: Pages marked as "frozen" when read transaction references them. Supports "weak" pages for optimization.
  • gdbx: Simpler COW - dirty pages allocated fresh, old pages freed only when no reader references them. Tracks via reader slot txnid.
  • Rationale: Frozen/weak page tracking optimizes memory in long-running mixed workloads but adds bookkeeping. gdbx relies on the oldest-reader txnid to know when pages are safe to free - same correctness, less state.
Memory Mapping
  • libmdbx: Dynamic geometry adjustment with automatic mmap resize. Supports both read-only and writable mmap modes.
  • gdbx: Pre-extended mmap with manual geometry. WriteMap mode uses writable mmap, otherwise pages copied on write.
  • Rationale: Dynamic mmap resize requires careful coordination between processes. Pre-extending to expected size is simpler and avoids remapping during writes. Most deployments know their size requirements upfront.
Search Optimization
  • libmdbx: Binary search with various optimizations in C.
  • gdbx: Assembly-optimized binary search (amd64/arm64). 8-byte keys use BSWAP+CMP for single-instruction comparison. Longer keys use SSE2 SIMD comparing 16 bytes at a time with PCMPEQB+PMOVMSKB. Full search loop in assembly avoids Go/asm boundary overhead.
  • Rationale: Go function calls have overhead that C doesn't. For the hot path (key comparison during search), keeping the entire binary search loop in assembly eliminates repeated Go/asm transitions. 8-byte keys are common (uint64 IDs) and can be compared in a single operation. SSE2 makes longer keys (64+ bytes) competitive with mdbx.
Nested Transactions
  • libmdbx: Full nested transaction support with parent page shadowing and complex abort handling.
  • gdbx: Infrastructure for nested transactions exists (BeginTxn accepts parent, dirty page reads delegate to parent). The Sub() method currently runs inline without true nesting.
  • Rationale: The parent delegation mechanism provides the foundation for nested transaction support. Full implementation would add commit/abort propagation logic.
What's Identical
  • Page format (20-byte header, entry offsets, node layout)
  • Meta page triple rotation for atomic commits
  • B+ tree structure and algorithms
  • DupSort sub-page/sub-tree handling
  • Overflow page format for large values
  • Lock file format and reader slot layout

Running Benchmarks

# Write operations (8-byte keys)
go test -bench="BenchmarkWriteOps" -benchtime=2s -run=^$ ./benchmarks/

# Read operations (8-byte keys)
go test -bench="BenchmarkReadOps" -benchtime=2s -run=^$ ./benchmarks/

# DBI/Transaction operations
go test -bench="BenchmarkDBI" -benchtime=2s -run=^$ ./benchmarks/

# Big values (8KB)
go test -bench="BenchmarkBigVal" -benchtime=2s -run=^$ ./benchmarks/

# 64-byte keys
go test -bench="BenchmarkReadLong|BenchmarkWriteLong" -benchtime=2s -run=^$ ./benchmarks/

License

MIT

Documentation

Overview

Package gdbx is a pure Go implementation of MDBX, a high-performance embedded transactional key-value database.

gdbx is file-format compatible with libmdbx, allowing existing MDBX databases to be opened and manipulated by this Go implementation.

Key features:

  • B+ tree data structure for efficient key-value storage
  • MVCC (Multi-Version Concurrency Control) for concurrent reads
  • Single writer, multiple readers concurrency model
  • Memory-mapped I/O for high performance
  • ACID transactions with crash recovery
  • Nested transaction infrastructure (parent page delegation)

Basic usage: 

env, err := gdbx.Create()
if err != nil {
    log.Fatal(err)
}
defer env.Close()

err = env.Open("/path/to/db", gdbx.NoSubdir, 0644)
if err != nil {
    log.Fatal(err)
}

// Begin a write transaction
txn, err := env.BeginTxn(nil, 0)
if err != nil {
    log.Fatal(err)
}

// Open the default database
dbi, err := txn.OpenDBI("", gdbx.Create)
if err != nil {
    txn.Abort()
    log.Fatal(err)
}

// Put a key-value pair
err = txn.Put(dbi, []byte("key"), []byte("value"), 0)
if err != nil {
    txn.Abort()
    log.Fatal(err)
}

_, _, err = txn.Commit()
if err != nil {
    log.Fatal(err)
}

Index

Constants

View Source 
const (
	// Magic is a 56-bit prime that identifies MDBX files
	Magic uint64 = 0x59659DBDEF4C11

	// DataVersion is the database file format version
	DataVersion = 3

	// LockVersion is the lock file format version
	LockVersion = 6

	// DataMagic combines magic and version for validation
	DataMagic = (Magic << 8) + DataVersion

	// LockMagic combines magic and lock version
	LockMagic = (Magic << 8) + LockVersion
)

Database format constants - must match libmdbx for file compatibility

View Source 
const (
	// MinPageSize is the minimum allowed page size (256 bytes)
	MinPageSize = 256

	// MaxPageSize is the maximum allowed page size (64KB)
	MaxPageSize = 65536

	// DefaultPageSize is the default page size (4KB)
	DefaultPageSize = 4096
)

Page size constraints

View Source 
const (
	// PageHeaderSize is the fixed page header size (20 bytes)
	PageHeaderSize = 20

	// NodeHeaderSize is the fixed node header size (8 bytes)
	NodeHeaderSize = 8
)

Page header and node sizes

View Source 
const (
	// MaxDBI is the maximum number of named databases
	MaxDBI = 32765

	// MaxDataSize is the maximum size of a data item
	MaxDataSize = 0x7fff0000

	// MaxPageNo is the maximum page number
	MaxPageNo uint32 = 0x7FFFffff

	// NumMetas is the number of meta pages (rotating)
	NumMetas = 3

	// MinPageNo is the first non-meta page number
	MinPageNo = NumMetas

	// CoreDBs is the number of core databases (GC and Main)
	CoreDBs = 2

	// FreeDBI is the handle for the GC/free page database
	FreeDBI = 0

	// MainDBI is the handle for the main database
	MainDBI = 1
)

Database limits

View Source 
const (
	// MinTxnID is the minimum valid transaction ID
	MinTxnID uint64 = 1

	// InitialTxnID is the initial transaction ID for new databases
	InitialTxnID uint64 = MinTxnID + NumMetas - 1

	// InvalidTxnID represents an invalid transaction ID
	InvalidTxnID uint64 = 0xFFFFFFFFFFFFFFFF
)

Transaction ID constants

View Source 
const (
	// EnvDefaults is the default (durable) mode
	EnvDefaults uint = 0

	// Validation enables extra validation of DB structure
	Validation uint = 0x00002000

	// NoSubdir means the path is a filename, not a directory
	NoSubdir uint = 0x00004000

	// ReadOnly opens the environment in read-only mode
	ReadOnly uint = 0x00020000

	// Exclusive opens in exclusive/monopolistic mode
	Exclusive uint = 0x00400000

	// Accede uses existing mode if opened by other processes
	Accede uint = 0x40000000

	// WriteMap maps data with write permission (faster, riskier)
	WriteMap uint = 0x00080000

	// NoStickyThreads allows transactions to move between threads
	NoStickyThreads uint = 0x00200000

	// NoReadAhead disables OS readahead
	NoReadAhead uint = 0x00800000

	// NoMemInit skips zeroing malloc'd memory
	NoMemInit uint = 0x01000000

	// LifoReclaim uses LIFO policy for GC reclamation
	LifoReclaim uint = 0x04000000

	// PagePerturb fills released pages with garbage (debug)
	PagePerturb uint = 0x08000000

	// NoMetaSync skips meta page sync after commit
	NoMetaSync uint = 0x00040000

	// SafeNoSync skips sync but keeps steady commits
	SafeNoSync uint = 0x00010000

	// UtterlyNoSync skips all syncs (dangerous)
	UtterlyNoSync = SafeNoSync | NoMetaSync

	// Durable is an alias for EnvDefaults (mdbx-go compatibility)
	Durable = EnvDefaults

	// Readonly is an alias for ReadOnly (mdbx-go compatibility)
	Readonly = ReadOnly

	// NoTLS is an alias for NoStickyThreads (mdbx-go compatibility)
	NoTLS = NoStickyThreads

	// NoReadahead is an alias for NoReadAhead (mdbx-go compatibility)
	NoReadahead = NoReadAhead
)

Environment flags (untyped uint constants for mdbx-go compatibility)

View Source 
const (
	// TxnReadWrite is the default read-write transaction
	TxnReadWrite uint = 0

	// TxnReadOnly creates a read-only transaction
	TxnReadOnly uint = 0x20000

	// TxnReadOnlyPrepare prepares a read-only transaction
	TxnReadOnlyPrepare = TxnReadOnly | 0x01000000

	// TxnTry attempts a non-blocking write transaction
	TxnTry uint = 0x10000000

	// TxnNoMetaSync skips meta sync for this transaction
	TxnNoMetaSync uint = 0x00040000

	// TxnNoSync skips sync for this transaction
	TxnNoSync uint = 0x00010000
)

Transaction flags (untyped uint constants for mdbx-go compatibility)

View Source 
const (
	TxRW         = TxnReadWrite
	TxRO         = TxnReadOnly
	TxNoSync     = TxnNoSync
	TxNoMetaSync = TxnNoMetaSync
)

Transaction flag aliases (mdbx-go short naming convention)

View Source 
const (
	// DBDefaults uses default comparison and features
	DBDefaults uint = 0

	// ReverseKey uses reverse string comparison for keys
	ReverseKey uint = 0x02

	// DupSort allows multiple values per key (sorted)
	DupSort uint = 0x04

	// IntegerKey uses uint32/uint64 keys in native byte order
	IntegerKey uint = 0x08

	// DupFixed uses fixed-size values in DUPSORT tables
	DupFixed uint = 0x10

	// IntegerDup uses fixed-size integer values in DUPSORT
	IntegerDup uint = 0x20

	// ReverseDup uses reverse comparison for values
	ReverseDup uint = 0x40

	// Create creates the database if it doesn't exist
	Create uint = 0x40000

	// DBAccede opens with unknown flags
	DBAccede uint = 0x40000000
)

Database flags (untyped uint constants for mdbx-go compatibility)

View Source 
const (
	// Upsert is the default insert-or-update mode
	Upsert uint = 0

	// NoOverwrite returns error if key exists
	NoOverwrite uint = 0x10

	// NoDupData returns error if key-value pair exists (DUPSORT)
	NoDupData uint = 0x20

	// Current overwrites current item (cursor put)
	Current uint = 0x40

	// AllDups replaces all duplicates for key
	AllDups uint = 0x80

	// Reserve reserves space without copying data
	Reserve uint = 0x10000

	// Append assumes data is being appended
	Append uint = 0x20000

	// AppendDup assumes duplicate data is being appended
	AppendDup uint = 0x40000

	// Multiple stores multiple data items (DUPFIXED)
	Multiple uint = 0x80000
)

Put flags (untyped uint constants for mdbx-go compatibility)

View Source 
const (
	// CopyDefaults performs a standard copy
	CopyDefaults uint = 0

	// CopyCompact compacts the database during copy
	CopyCompact uint = 0x01
)

Copy flags

View Source 
const (
	// WarmupDefault is the default warmup behavior
	WarmupDefault uint = 0

	// WarmupForce forces warmup even if already done
	WarmupForce uint = 0x01

	// WarmupOomSafe uses OOM-safe warmup (slower but safer)
	WarmupOomSafe uint = 0x02

	// WarmupLock holds lock during warmup
	WarmupLock uint = 0x04

	// WarmupTouchLimit limits pages touched during warmup
	WarmupTouchLimit uint = 0x08

	// WarmupRelease releases pages after warmup
	WarmupRelease uint = 0x10
)

Warmup flags (mdbx-go compatibility)

View Source 
const (
	// DataFileName is the data file name in an environment directory
	DataFileName = "mdbx.dat"

	// LockFileName is the lock file name in an environment directory
	LockFileName = "mdbx.lck"

	// LockSuffix is appended when NoSubdir is used
	LockSuffix = "-lck"
)

File names

View Source 
const (
	DbgAssert          uint = 1
	DbgAudit           uint = 2
	DbgJitter          uint = 4
	DbgDump            uint = 8
	DbgLegacyMultiOpen uint = 16
	DbgLegacyTxOverlap uint = 32
	DbgDoNotChange     uint = 0xFFFFFFFF
)

Debug constants (mdbx-go compatibility)

View Source 
const (
	// First positions at the first key
	First uint = iota
	// FirstDup positions at the first duplicate of current key
	FirstDup
	// GetBoth positions at exact key-value pair
	GetBoth
	// GetBothRange positions at key with value >= specified
	GetBothRange
	// GetCurrent returns current key-value
	GetCurrent
	// GetMultiple returns multiple values (DUPFIXED)
	GetMultiple
	// Last positions at the last key
	Last
	// LastDup positions at the last duplicate of current key
	LastDup
	// Next moves to the next key-value
	Next
	// NextDup moves to the next duplicate of current key
	NextDup
	// NextMultiple returns next multiple values (DUPFIXED)
	NextMultiple
	// NextNoDup moves to the first value of next key
	NextNoDup
	// Prev moves to the previous key-value
	Prev
	// PrevDup moves to the previous duplicate of current key
	PrevDup
	// PrevNoDup moves to the last value of previous key
	PrevNoDup
	// Set positions at specified key
	Set
	// SetKey positions at key, returns key and value
	SetKey
	// SetRange positions at first key >= specified
	SetRange
	// PrevMultiple returns previous multiple values (DUPFIXED)
	PrevMultiple
	// SetLowerbound positions at first key-value >= specified
	SetLowerbound
	// SetUpperbound positions at first key-value > specified
	SetUpperbound
	// LesserThan positions at the key less than specified
	LesserThan
)

Cursor operation constants (untyped uint for mdbx-go compatibility)

View Source 
const (
	OptMaxDB                        uint = 0
	OptMaxReaders                   uint = 1
	OptSyncBytes                    uint = 2
	OptSyncPeriod                   uint = 3
	OptRpAugmentLimit               uint = 4
	OptLooseLimit                   uint = 5
	OptDpReserveLimit               uint = 6
	OptDpReverseLimit               uint = 6 // Alias for OptDpReserveLimit (mdbx-go typo compatibility)
	OptTxnDpLimit                   uint = 7
	OptTxnDpInitial                 uint = 8
	OptSpillMinDenominator          uint = 9
	OptSpillMaxDenominator          uint = 10
	OptSpillParent4ChildDenominator uint = 11
	OptMergeThreshold16dot16Percent uint = 12
	OptWriteThroughThreshold        uint = 13
	OptPreFaultWriteEnable          uint = 14
	OptPreferWafInsteadofBalance    uint = 15
	OptGCTimeLimit                  uint = 16
)

Option constants for GetOption/SetOption (mdbx-go compatibility)

View Source 
const (
	// Major is the major version number
	Major = 0

	// Minor is the minor version number
	Minor = 1

	// Patch is the patch version number
	Patch = 0
)

Version constants

View Source 
const AllowTxOverlap = DbgLegacyTxOverlap

AllowTxOverlap allows overlapping transactions (mdbx-go compatibility)

View Source 
const CursorStackSize = 32

CursorStackSize is the maximum tree depth supported

View Source 
const InvalidPageNo uint32 = 0xFFFFFFFF

InvalidPageNo represents an invalid page number (empty tree marker)

View Source 
const LoggerDoNotChange = LogLvlDoNotChange

LoggerDoNotChange is an alias for LogLvlDoNotChange (mdbx-go compatibility)

View Source 
const MapFull = ErrMapFull

MapFull is an alias for ErrMapFull (mdbx-go compatibility)

View Source 
const MaxDbi = MaxDBI

MaxDbi is the maximum number of named databases (mdbx-go compatibility alias)

Variables

View Source 
var (
	ErrKeyExistError            = NewError(ErrKeyExist)
	ErrNotFoundError            = NewError(ErrNotFound)
	ErrPageNotFoundError        = NewError(ErrPageNotFound)
	ErrCorruptedError           = NewError(ErrCorrupted)
	ErrPanicError               = NewError(ErrPanic)
	ErrVersionMismatchError     = NewError(ErrVersionMismatch)
	ErrInvalidError             = NewError(ErrInvalid)
	ErrMapFullError             = NewError(ErrMapFull)
	ErrDBsFullError             = NewError(ErrDBsFull)
	ErrReadersFullError         = NewError(ErrReadersFull)
	ErrTxnFullError             = NewError(ErrTxnFull)
	ErrCursorFullError          = NewError(ErrCursorFull)
	ErrPageFullError            = NewError(ErrPageFull)
	ErrUnableExtendMapsizeError = NewError(ErrUnableExtendMapsize)
	ErrIncompatibleError        = NewError(ErrIncompatible)
	ErrBadRSlotError            = NewError(ErrBadRSlot)
	ErrBadTxnError              = NewError(ErrBadTxn)
	ErrBadValSizeError          = NewError(ErrBadValSize)
	ErrBadDBIError              = NewError(ErrBadDBI)
	ErrProblemError             = NewError(ErrProblem)
	ErrBusyError                = NewError(ErrBusy)
)

Common error variables for convenience

View Source 
var CorruptErrorBacktraceRecommendations = "Otherwise - please create issue in Application repo."

CorruptErrorBacktraceRecommendations is the backtrace recommendation for corruption errors (mdbx-go compatibility)

View Source 
var CorruptErrorHardwareRecommendations = "" /* 403-byte string literal not displayed */

CorruptErrorHardwareRecommendations is the hardware recommendation for corruption errors (mdbx-go compatibility)

View Source 
var CorruptErrorMessage = CorruptErrorHardwareRecommendations + " " + CorruptErrorBacktraceRecommendations + " " + CorruptErrorRecoveryRecommendations

CorruptErrorMessage is the combined error message for corruption errors (mdbx-go compatibility)

View Source 
var CorruptErrorRecoveryRecommendations = "" /* 191-byte string literal not displayed */

CorruptErrorRecoveryRecommendations is the recovery recommendation for corruption errors (mdbx-go compatibility)

View Source 
var DebugCursor = false
View Source 
var DebugPrune = false

DebugPrune enables verbose debug output for cursor refresh operations

View Source 
var ErrBadCursorError = NewError(ErrBadTxn)

ErrBadCursorError indicates an invalid cursor

View Source 
var MapFullErrorMessage = "The allocated database storage size limit has been reached."

MapFullErrorMessage is the error message for MapFull (mdbx-go compatibility)

View Source 
var NotFound = errors.New("key not found")

NotFound is a sentinel error for "key not found" (mdbx-go compatibility). Use IsNotFound() to check for this error.

Functions

func CursorToPool 

func CursorToPool(c *Cursor)

CursorToPool returns a cursor to the pool. The cursor should be unbound (Close() called) before returning.

func FromHex 

func FromHex(s string) []byte

FromHex converts a hex string to bytes.

func GetSysRamInfo 

func GetSysRamInfo() (pageSize, totalPages, availablePages int, err error)

GetSysRamInfo returns system RAM information.

func IsCorrupted 

func IsCorrupted(err error) bool

IsCorrupted returns true if the error indicates database corruption

func IsErrno 

func IsErrno(err error, errno Errno) bool

IsErrno checks if err is a specific Errno.

func IsErrnoFn 

func IsErrnoFn(err error, fn func(error) bool) bool

IsErrnoFn checks if err matches a predicate function.

func IsKeyExist 

func IsKeyExist(err error) bool

IsKeyExist returns true if the error is ErrKeyExist

func IsKeyExists 

func IsKeyExists(err error) bool

IsKeyExists is an alias for IsKeyExist (mdbx-go compatibility)

func IsMapFull 

func IsMapFull(err error) bool

IsMapFull returns true if the error is ErrMapFull (mdbx-go compatibility)

func IsNotExist 

func IsNotExist(err error) bool

IsNotExist returns true if the error indicates a file doesn't exist.

func IsNotFound 

func IsNotFound(err error) bool

IsNotFound returns true if the error is ErrNotFound

func SetDebug 

func SetDebug(flags uint) uint

SetDebug sets debug flags (mdbx-go compatibility). Returns the previous debug flags.

func SetDebugLog 

func SetDebugLog(enabled bool)

SetDebugLog enables or disables debug logging (for debugging only).

func Version 

func Version() string

Version returns the version string of gdbx. Format is similar to mdbx-go for compatibility.

Types

type BuildInfo 

type BuildInfo struct {
	Datetime string
	Target   string
	Options  string
	Compiler string
	Flags    string
}

BuildInfo contains build information (mdbx-go compatibility).

func GetBuildInfo 

func GetBuildInfo() BuildInfo

GetBuildInfo returns build information (mdbx-go compatibility).

type CmpFunc 

type CmpFunc = func(a, b []byte) int

CmpFunc is a comparison function for keys or values.

type CommitLatency 

type CommitLatency struct {
	Preparation time.Duration
	GCWallClock time.Duration
	GCCpuTime   time.Duration
	Audit       time.Duration
	Write       time.Duration
	Sync        time.Duration
	Ending      time.Duration
	Whole       time.Duration
}

CommitLatency contains timing information about a commit operation. For mdbx-go API compatibility.

type Cursor 

type Cursor struct {
	// contains filtered or unexported fields
}

Cursor provides navigation through a database.

func CreateCursor 

func CreateCursor() *Cursor

CreateCursor creates a new unbound cursor.

func CursorFromPool 

func CursorFromPool() *Cursor

CursorFromPool gets a cursor from the pool. The cursor must be bound to a transaction using Bind before use.

func (*Cursor) Bind 

func (c *Cursor) Bind(txn *Txn, dbi DBI) error

Bind binds a cursor to a transaction and database. This is useful for cursor pooling - get a cursor from CursorFromPool(), then bind it to reuse it across transactions.

func (*Cursor) Close 

func (c *Cursor) Close()

Close closes the cursor and returns it to the pool.

func (*Cursor) Count 

func (c *Cursor) Count() (uint64, error)

Count returns the number of values for the current key.

func (*Cursor) DBI 

func (c *Cursor) DBI() DBI

DBI returns the cursor's database handle.

func (*Cursor) Del 

func (c *Cursor) Del(flags uint) error

Del deletes the current key-value pair.

func (*Cursor) EOF 

func (c *Cursor) EOF() bool

EOF returns true if the cursor is at end-of-file.

func (*Cursor) Get 

func (c *Cursor) Get(key, value []byte, op CursorOp) ([]byte, []byte, error)

Get retrieves key-value at the cursor position based on operation.

func (*Cursor) OnFirst 

func (c *Cursor) OnFirst() bool

OnFirst returns true if cursor is at the first key.

func (*Cursor) OnLast 

func (c *Cursor) OnLast() bool

OnLast returns true if cursor is at the last key.

func (*Cursor) Put 

func (c *Cursor) Put(key, value []byte, flags uint) error

Put stores a key-value pair at the cursor position.

func (*Cursor) PutMulti 

func (c *Cursor) PutMulti(key []byte, page []byte, stride int, flags uint) error

Cursor.PutMulti stores multiple values for a key (DUPFIXED).

func (*Cursor) PutReserve 

func (c *Cursor) PutReserve(key []byte, n int, flags uint) ([]byte, error)

Cursor.PutReserve reserves space for a value.

func (*Cursor) PutTree 

func (c *Cursor) PutTree(key, treeData []byte, flags uint) error

PutTree inserts or updates a sub-database entry in the main database. This sets the N_TREE flag on the node, which is required for libmdbx compatibility. The value should be a 48-byte serialized Tree structure.

func (*Cursor) Renew 

func (c *Cursor) Renew(txn *Txn) error

Renew renews a cursor for a new read-only transaction. This is used with cursor pooling to reuse a cursor.

func (*Cursor) SetUserCtx 

func (c *Cursor) SetUserCtx(ctx any)

SetUserCtx sets user context data on the cursor.

func (*Cursor) Txn 

func (c *Cursor) Txn() *Txn

Txn returns the cursor's transaction.

func (*Cursor) Unbind 

func (c *Cursor) Unbind() error

Unbind detaches the cursor from its transaction. The cursor can be re-bound to another transaction using Bind.

func (*Cursor) UserCtx 

func (c *Cursor) UserCtx() any

UserCtx returns the user context data.

type CursorOp 

type CursorOp = uint

CursorOp is for backward compatibility (deprecated, use uint constants directly)

type DBI 

type DBI uint32

DBI is a database handle (index into environment's database array).

type Duration16dot16 

type Duration16dot16 uint32

Duration16dot16 is a 16.16 fixed-point duration (mdbx-go compatibility).

func NewDuration16dot16 

func NewDuration16dot16(d time.Duration) Duration16dot16

NewDuration16dot16 converts a time.Duration to 16.16 fixed-point.

func (Duration16dot16) ToDuration 

func (d Duration16dot16) ToDuration() time.Duration

ToDuration converts 16.16 fixed-point to time.Duration.

type Env 

type Env struct {
	// contains filtered or unexported fields
}

Env represents a database environment.

func NewEnv 

func NewEnv(label Label) (*Env, error)

NewEnv creates a new environment handle. The environment must be opened with Open before use. The label parameter is for identification purposes (mdbx-go compatibility).

func (*Env) BeginTxn 

func (e *Env) BeginTxn(parent *Txn, flags uint) (*Txn, error)

BeginTxn starts a new transaction.

func (*Env) Close 

func (e *Env) Close()

Close closes the environment and releases resources. Waits for all active read transactions to finish before unmapping.

func (*Env) CloseDBI 

func (e *Env) CloseDBI(db DBI)

CloseDBI closes a database handle. This is normally unnecessary as handles are closed when the environment closes.

func (*Env) CloseEx 

func (e *Env) CloseEx(dontSync bool)

CloseEx closes the environment with optional sync control.

func (*Env) Copy 

func (e *Env) Copy(path string, flags uint) error

Copy copies the environment to a path.

func (*Env) CopyFD 

func (e *Env) CopyFD(fd uintptr, flags uint) error

CopyFD copies the environment to a file descriptor.

func (*Env) EnableSpillBuffer 

func (e *Env) EnableSpillBuffer(initialCap uint32) error

EnableSpillBuffer creates a spill buffer for dirty pages. This reduces heap pressure by storing dirty pages in a memory-mapped file instead of Go-allocated memory. Call this after Open() but before starting write transactions. The initialCap parameter specifies the initial capacity in pages. If initialCap is 0, a default value is used.

func (*Env) FD 

func (e *Env) FD() (uintptr, error)

FD returns the file descriptor of the data file.

func (*Env) Flags 

func (e *Env) Flags() (uint, error)

Flags returns the environment flags.

func (*Env) GetOption 

func (e *Env) GetOption(option uint) (uint64, error)

GetOption returns an environment option value.

func (*Env) GetSyncBytes 

func (e *Env) GetSyncBytes() (uint, error)

GetSyncBytes returns the threshold for auto-sync.

func (*Env) GetSyncPeriod 

func (e *Env) GetSyncPeriod() (time.Duration, error)

GetSyncPeriod returns the period for auto-sync.

func (*Env) Info 

func (e *Env) Info(txn *Txn) (*EnvInfo, error)

Info returns information about the environment. The txn parameter is optional and can be nil.

func (*Env) Label 

func (e *Env) Label() Label

Label returns the environment label.

func (*Env) LeafNodeMax 

func (e *Env) LeafNodeMax() int

LeafNodeMax returns the maximum size of a leaf node. This matches libmdbx's leaf_nodemax calculation.

func (*Env) MaxDBs 

func (e *Env) MaxDBs() uint32

MaxDBs returns the maximum number of named databases.

func (*Env) MaxKeySize 

func (e *Env) MaxKeySize() int

MaxKeySize returns the maximum key size for the environment. This matches libmdbx's branch page constraint: BRANCH_NODE_MAX = EVEN_FLOOR((PAGEROOM - indx - node) / 2 - indx) MaxKeySize = BRANCH_NODE_MAX - NODESIZE

func (*Env) MaxReaders 

func (e *Env) MaxReaders() uint32

MaxReaders returns the maximum number of readers.

func (*Env) MaxValSize 

func (e *Env) MaxValSize() int

MaxValSize returns the maximum inline value size. Values larger than this are stored on overflow pages automatically.

func (*Env) Open 

func (e *Env) Open(path string, flags uint, mode os.FileMode) error

Open opens the environment at the given path.

func (*Env) Path 

func (e *Env) Path() string

Path returns the environment path.

func (*Env) PreExtendMmap 

func (e *Env) PreExtendMmap(size int64) error

PreExtendMmap extends the mmap to the specified size. Call this after Open() when using WriteMap mode to avoid heap allocations during write transactions. The size should be large enough to accommodate all pages that will be written during the transaction. NOTE: This should be called before any transactions start, as remapping while transactions are active can cause issues. Returns nil on success, error on failure.

func (*Env) ReaderCheck 

func (e *Env) ReaderCheck() (int, error)

ReaderCheck clears stale entries from the reader lock table. Returns the number of stale readers cleared.

func (*Env) ReaderList 

func (e *Env) ReaderList(fn func(info ReaderInfo) error) error

ReaderList returns information about all active readers.

func (*Env) RunTxn 

func (e *Env) RunTxn(flags uint, fn TxnOp) error

RunTxn runs a transaction with the given flags. The transaction is automatically committed when fn returns nil, or aborted when fn returns an error.

func (*Env) SetCompare 

func (e *Env) SetCompare(dbi DBI, cmp func(a, b []byte) int) error

SetCompare sets a custom key comparison function for a database. Must be called before any data operations on the database.

func (*Env) SetDebug 

func (e *Env) SetDebug(flags uint) error

SetDebug sets debug flags for this environment (mdbx-go compatibility).

func (*Env) SetDupCompare 

func (e *Env) SetDupCompare(dbi DBI, cmp func(a, b []byte) int) error

SetDupCompare sets a custom data comparison function for DUPSORT databases. Must be called before any data operations on the database.

func (*Env) SetEnvFlags 

func (e *Env) SetEnvFlags(flags uint, enable bool) error

SetEnvFlags sets or clears environment flags.

func (*Env) SetFlags 

func (e *Env) SetFlags(flags uint) error

SetFlags sets flags in the environment.

func (*Env) SetGeometry 

func (e *Env) SetGeometry(sizeLower, sizeNow, sizeUpper, growthStep, shrinkThreshold int64, pageSize int) error

SetGeometry sets the database size parameters.

func (*Env) SetGeometryGeo 

func (e *Env) SetGeometryGeo(geo Geometry) error

SetGeometryGeo sets database geometry using Geometry struct (mdbx-go compatibility).

func (*Env) SetGeometrySize 

func (e *Env) SetGeometrySize(sizeLower, sizeNow, sizeUpper, growthStep, shrinkThreshold Size, pageSize int) error

SetGeometrySize sets database geometry using Size types (mdbx-go compatibility).

func (*Env) SetMaxDBs 

func (e *Env) SetMaxDBs(dbs uint32) error

SetMaxDBs sets the maximum number of named databases. Must be called before Open.

func (*Env) SetMaxReaders 

func (e *Env) SetMaxReaders(readers uint32) error

SetMaxReaders sets the maximum number of reader slots. Must be called before Open.

func (*Env) SetOption 

func (e *Env) SetOption(option uint, value uint64) error

SetOption sets an environment option value.

func (*Env) SetPageSize 

func (e *Env) SetPageSize(size uint32) error

SetPageSize sets the page size for a new database. Must be called before Open. Must be a power of 2 between 256 and 65536.

func (*Env) SetStrictThreadMode 

func (e *Env) SetStrictThreadMode(mode bool)

SetStrictThreadMode sets strict thread mode. In gdbx (pure Go), this is a no-op since Go handles threading differently.

func (*Env) SetSyncBytes 

func (e *Env) SetSyncBytes(threshold uint) error

SetSyncBytes sets the threshold for auto-sync.

func (*Env) SetSyncPeriod 

func (e *Env) SetSyncPeriod(period time.Duration) error

SetSyncPeriod sets the period for auto-sync.

func (*Env) SetUserCtx 

func (e *Env) SetUserCtx(ctx any)

SetUserCtx sets user context on the environment.

func (*Env) SpillBuffer 

func (e *Env) SpillBuffer() *spill.Buffer

SpillBuffer returns the spill buffer, or nil if not enabled.

func (*Env) Stat 

func (e *Env) Stat() (*Stat, error)

Stat returns statistics about the environment.

func (*Env) SubPageLimit 

func (e *Env) SubPageLimit() int

SubPageLimit returns the maximum inline sub-page size. When a sub-page exceeds this, it's converted to a sub-tree. This matches libmdbx's subpage_limit calculation.

func (*Env) Sync 

func (e *Env) Sync(force bool, nonblock bool) error

Sync flushes the environment to disk. If force is true, a synchronous flush is performed. If nonblock is true, the function returns immediately if a sync is already in progress.

func (*Env) UnsetFlags 

func (e *Env) UnsetFlags(flags uint) error

UnsetFlags clears flags in the environment.

func (*Env) Update 

func (e *Env) Update(fn TxnOp) error

Update executes a read-write transaction. The transaction is automatically committed when fn returns nil, or aborted when fn returns an error.

func (*Env) UpdateLocked 

func (e *Env) UpdateLocked(fn TxnOp) error

UpdateLocked behaves like Update but does not lock the calling goroutine. Use this if the calling goroutine is already locked to its thread.

func (*Env) UserCtx 

func (e *Env) UserCtx() any

UserCtx returns the user context.

func (*Env) View 

func (e *Env) View(fn TxnOp) error

View executes a read-only transaction. The transaction is automatically committed when fn returns nil, or aborted when fn returns an error.

type EnvInfo 

type EnvInfo struct {
	Geo               EnvInfoGeo
	PageOps           EnvInfoPageOps
	MapSize           int64
	LastPNO           int64 // Alias for LastPgNo (mdbx-go compatibility)
	LastPgNo          int64
	LastTxnID         uint64
	RecentTxnID       uint64
	LatterReaderTxnID uint64
	MaxReaders        uint32
	NumReaders        uint32
	PageSize          uint32
	SystemPageSize    uint32
	MiLastPgNo        uint64
	AutoSyncThreshold uint64
	UnsyncedBytes     uint64
	SinceSync         Duration16dot16
	AutosyncPeriod    Duration16dot16
	SinceReaderCheck  Duration16dot16
	Flags             uint32
	// Legacy fields for backward compatibility
	GeoLower   uint64
	GeoUpper   uint64
	GeoCurrent uint64
	GeoShrink  uint64
	GeoGrow    uint64
}

EnvInfo holds environment information.

type EnvInfoGeo 

type EnvInfoGeo struct {
	Lower   uint64 // Lower limit for datafile size
	Upper   uint64 // Upper limit for datafile size
	Current uint64 // Current datafile size
	Shrink  uint64 // Shrink threshold in bytes
	Grow    uint64 // Growth step in bytes
}

EnvInfoGeo contains geometry information for an environment.

type EnvInfoPageOps 

type EnvInfoPageOps struct {
	Newly    uint64 // Newly allocated pages
	Cow      uint64 // Copy-on-write pages
	Clone    uint64 // Cloned pages
	Split    uint64 // Page splits
	Merge    uint64 // Page merges
	Spill    uint64 // Spilled dirty pages
	Unspill  uint64 // Unspilled pages
	Wops     uint64 // Write operations
	Minicore uint64 // Minicore pages
	Prefault uint64 // Prefaulted pages
	Msync    uint64 // Memory sync operations
	Fsync    uint64 // File sync operations
}

EnvInfoPageOps contains page operation statistics.

type Errno 

type Errno int

Errno is an error type for MDBX error codes (mdbx-go compatibility).

func (Errno) Error 

func (e Errno) Error() string

Error returns the error message for an Errno.

func (Errno) Is 

func (e Errno) Is(target error) bool

Is reports whether e matches target.

type Error 

type Error struct {
	Code    ErrorCode
	Message string
	Err     error // wrapped error
}

Error represents a gdbx error with an error code

func NewError 

func NewError(code ErrorCode) *Error

NewError creates a new Error with the given code

func WrapError 

func WrapError(code ErrorCode, err error) *Error

WrapError creates a new Error wrapping another error

func (*Error) Error 

func (e *Error) Error() string

func (*Error) Unwrap 

func (e *Error) Unwrap() error

type ErrorCode 

type ErrorCode int

ErrorCode represents MDBX-compatible error codes 

const (
	// Success indicates the operation completed successfully
	Success ErrorCode = 0

	// ErrSuccess is an alias for Success (mdbx-go compatibility)
	ErrSuccess = Success

	// ResultFalse is an alias for Success
	ResultFalse = Success

	// ResultTrue indicates success with special meaning
	ResultTrue ErrorCode = -1

	// ErrKeyExist indicates the key/data pair already exists
	ErrKeyExist ErrorCode = -30799

	// ErrNotFound indicates the key/data pair was not found (EOF)
	ErrNotFound ErrorCode = -30798

	// ErrPageNotFound indicates a requested page was not found (corruption)
	ErrPageNotFound ErrorCode = -30797

	// ErrCorrupted indicates the database is corrupted
	ErrCorrupted ErrorCode = -30796

	// ErrPanic indicates a fatal environment error
	ErrPanic ErrorCode = -30795

	// ErrVersionMismatch indicates DB version doesn't match library
	ErrVersionMismatch ErrorCode = -30794

	// ErrInvalid indicates the file is not a valid MDBX file
	ErrInvalid ErrorCode = -30793

	// ErrMapFull indicates the environment mapsize was reached
	ErrMapFull ErrorCode = -30792

	// ErrDBsFull indicates the environment maxdbs was reached
	ErrDBsFull ErrorCode = -30791

	// ErrReadersFull indicates the environment maxreaders was reached
	ErrReadersFull ErrorCode = -30790

	// ErrTxnFull indicates the transaction has too many dirty pages
	ErrTxnFull ErrorCode = -30788

	// ErrCursorFull indicates cursor stack overflow (corruption)
	ErrCursorFull ErrorCode = -30787

	// ErrPageFull indicates a page has no space (internal error)
	ErrPageFull ErrorCode = -30786

	// ErrUnableExtendMapsize indicates mapping couldn't be extended
	ErrUnableExtendMapsize ErrorCode = -30785

	// ErrIncompatible indicates incompatible operation or flags
	ErrIncompatible ErrorCode = -30784

	// ErrBadRSlot indicates reader slot was corrupted or reused
	ErrBadRSlot ErrorCode = -30783

	// ErrBadTxn indicates the transaction is invalid
	ErrBadTxn ErrorCode = -30782

	// ErrBadValSize indicates invalid key or data size
	ErrBadValSize ErrorCode = -30781

	// ErrBadDBI indicates the DBI handle is invalid
	ErrBadDBI ErrorCode = -30780

	// ErrProblem indicates an unexpected internal error
	ErrProblem ErrorCode = -30779

	// ErrBusy indicates another write transaction is running
	ErrBusy ErrorCode = -30778

	// ErrMultiVal indicates the key has multiple associated values
	ErrMultiVal ErrorCode = -30421

	// ErrMultival is an alias for ErrMultiVal (mdbx-go compatibility)
	ErrMultival = ErrMultiVal

	// ErrBadSign indicates bad signature (memory corruption or ABI mismatch)
	ErrBadSign ErrorCode = -30420

	// ErrWannaRecovery indicates recovery is needed but DB is read-only
	ErrWannaRecovery ErrorCode = -30419

	// ErrKeyMismatch indicates key mismatch with cursor position
	ErrKeyMismatch ErrorCode = -30418

	// ErrTooLarge indicates database is too large for system
	ErrTooLarge ErrorCode = -30417

	// ErrThreadMismatch indicates thread attempted to use unowned object
	ErrThreadMismatch ErrorCode = -30416

	// ErrTxnOverlapping indicates overlapping read/write transactions
	ErrTxnOverlapping ErrorCode = -30415

	// ErrBacklogDepleted indicates GC ran out of free pages
	ErrBacklogDepleted ErrorCode = -30414

	// ErrDuplicatedCLK indicates duplicate lock file exists
	ErrDuplicatedCLK ErrorCode = -30413

	// ErrDanglingDBI indicates resources need closing before DBI can be reused
	ErrDanglingDBI ErrorCode = -30412

	// ErrOusted indicates parked transaction was evicted for GC
	ErrOusted ErrorCode = -30411

	// ErrMVCCRetarded indicates parked transaction's snapshot is too old
	ErrMVCCRetarded ErrorCode = -30410
)

Error codes - matching MDBX for compatibility 

const ErrPermissionDenied ErrorCode = -1 // Will use syscall.EACCES

ErrPermissionDenied indicates a write operation on read-only transaction

func Code 

func Code(err error) ErrorCode

Code returns the error code from an error, or ErrProblem if not a gdbx error

type Geometry 

type Geometry struct {
	SizeLower       Size // Lower limit for datafile size
	SizeNow         Size // Current datafile size (use -1 for default)
	SizeUpper       Size // Upper limit for datafile size
	GrowthStep      Size // Growth step in bytes
	ShrinkThreshold Size // Shrink threshold in bytes
	PageSize        int  // Page size in bytes (use -1 for default)
}

Geometry holds database geometry parameters (mdbx-go compatibility).

type HandleSlowReadersFunc 

type HandleSlowReadersFunc func(env *Env, txn *Txn, pid int, tid uint64, laggard uint64, gap uint64, space uint64, retry int) int

HandleSlowReadersFunc is called when slow readers are detected (mdbx-go compatibility).

func SetHandleSlowReaders 

func SetHandleSlowReaders(fn HandleSlowReadersFunc) HandleSlowReadersFunc

SetHandleSlowReaders sets the slow readers handler (mdbx-go compatibility). Returns the previous handler.

type Label 

type Label string

Label is a label for an environment (mdbx-go compatibility) 

const Default Label = "default"

Default is the default environment label (mdbx-go compatibility)

type LogLvl 

type LogLvl int

Log level constants (mdbx-go compatibility) 

const (
	LogLvlFatal       LogLvl = 0
	LogLvlError       LogLvl = 1
	LogLvlWarn        LogLvl = 2
	LogLvlNotice      LogLvl = 3
	LogLvlVerbose     LogLvl = 4
	LogLvlDebug       LogLvl = 5
	LogLvlTrace       LogLvl = 6
	LogLvlExtra       LogLvl = 7
	LogLvlDoNotChange LogLvl = -1
)

func SetLogger 

func SetLogger(logger LoggerFunc, level LogLvl) LogLvl

SetLogger sets the logger function and level (mdbx-go compatibility). Returns the previous log level.

type LoggerFunc 

type LoggerFunc func(msg string, args ...any)

LoggerFunc is a callback function for logging (mdbx-go compatibility).

type Multi 

type Multi struct {
	// contains filtered or unexported fields
}

Multi wraps multi-value pages for DUPFIXED databases.

func WrapMulti 

func WrapMulti(page []byte, stride int) *Multi

WrapMulti wraps a multi-value page.

func (*Multi) Len 

func (m *Multi) Len() int

Len returns the number of values.

func (*Multi) Page 

func (m *Multi) Page() []byte

Page returns the raw page data.

func (*Multi) Size 

func (m *Multi) Size() int

Size returns the total size.

func (*Multi) Stride 

func (m *Multi) Stride() int

Stride returns the stride.

func (*Multi) Val 

func (m *Multi) Val(i int) []byte

Val returns value at index i.

func (*Multi) Vals 

func (m *Multi) Vals() [][]byte

Vals returns all values.

type NodeFlags 

type NodeFlags uint8

NodeFlags define node types within pages 

const (
	// NodeBig indicates data is on a large/overflow page
	NodeBig NodeFlags = 0x01

	// NodeTree indicates data is a B-tree (sub-database)
	NodeTree NodeFlags = 0x02

	// NodeDup indicates data has duplicates
	NodeDup NodeFlags = 0x04
)

type OpError 

type OpError struct {
	Op  string
	Err error
}

OpError wraps an error with operation context (mdbx-go compatibility).

func (*OpError) Error 

func (e *OpError) Error() string

Error returns the error message.

func (*OpError) Is 

func (e *OpError) Is(target error) bool

Is reports whether e matches target.

func (*OpError) Unwrap 

func (e *OpError) Unwrap() error

Unwrap returns the wrapped error.

type PageFlags 

type PageFlags uint16

PageFlags define page types 

const (
	// PageBranch indicates a branch (internal) page
	PageBranch PageFlags = 0x01

	// PageLeaf indicates a leaf page
	PageLeaf PageFlags = 0x02

	// PageLarge indicates a large/overflow page
	PageLarge PageFlags = 0x04

	// PageMeta indicates a meta page
	PageMeta PageFlags = 0x08

	// PageLegacyDirty is a legacy dirty flag (pre v0.10)
	PageLegacyDirty PageFlags = 0x10

	// PageBad is an explicit flag for invalid pages
	PageBad = PageLegacyDirty

	// PageDupfix indicates a DUPFIXED page
	PageDupfix PageFlags = 0x20

	// PageSubP indicates a sub-page for DUPSORT
	PageSubP PageFlags = 0x40

	// PageSpilled indicates a page spilled in parent txn
	PageSpilled PageFlags = 0x2000

	// PageLoose indicates a freed page available for reuse
	PageLoose PageFlags = 0x4000

	// PageFrozen indicates a retired page with known status
	PageFrozen PageFlags = 0x8000
)

type ReaderInfo 

type ReaderInfo struct {
	Slot   int
	TxnID  uint64
	PID    int
	Thread uint64
	Bytes  uint64
	RetxL  uint64
}

ReaderInfo contains information about a reader slot (mdbx-go compatibility).

type Size 

type Size int64

Size is a size type for geometry parameters (mdbx-go compatibility).

type Stat 

type Stat struct {
	PageSize      uint32 // Page size in bytes
	Depth         uint32 // Tree depth
	BranchPages   uint64 // Number of branch pages
	LeafPages     uint64 // Number of leaf pages
	LargePages    uint64 // Number of overflow pages
	OverflowPages uint64 // Alias for LargePages (mdbx-go compat)
	Entries       uint64 // Number of entries
	Root          uint32 // Root page number (for debugging)
	ModTxnID      uint64 // Last modification transaction ID
}

Stat holds database statistics.

type TxInfo 

type TxInfo struct {
	ID             uint64
	ReaderLag      uint64
	SpaceUsed      uint64
	SpaceLimitSoft uint64
	SpaceLimitHard uint64
	SpaceRetired   uint64
	SpaceLeftover  uint64
	SpaceDirty     uint64
	Spill          uint64 // Pages spilled to disk
	Unspill        uint64 // Pages unspilled from disk
}

TxInfo contains transaction information.

type Txn 

type Txn struct {
	// contains filtered or unexported fields
}

Txn represents a database transaction.

func (*Txn) Abort 

func (txn *Txn) Abort()

Abort aborts the transaction.

func (*Txn) CloseDBI 

func (txn *Txn) CloseDBI(dbi DBI) error

CloseDBI closes a database handle.

func (*Txn) Cmp 

func (txn *Txn) Cmp(dbi DBI, a, b []byte) int

Cmp compares two keys using the database's comparator.

func (*Txn) Commit 

func (txn *Txn) Commit() (CommitLatency, error)

Commit commits the transaction and returns latency information. Returns (CommitLatency, error) for mdbx-go API compatibility.

func (*Txn) CreateDBI 

func (txn *Txn) CreateDBI(name string) (DBI, error)

CreateDBI creates a new named database. This is a convenience wrapper around OpenDBI with Create flag.

func (*Txn) DBIFlags 

func (txn *Txn) DBIFlags(dbi DBI) (uint, error)

DBIFlags returns the flags for a database.

func (*Txn) DBIStat 

func (txn *Txn) DBIStat(dbi DBI) (*Stat, error)

DBIStat is an alias for the Stat method for compatibility.

func (*Txn) DCmp 

func (txn *Txn) DCmp(dbi DBI, a, b []byte) int

DCmp compares two values using the database's dup comparator.

func (*Txn) DebugGetPage 

func (txn *Txn) DebugGetPage(pageNum uint32) ([]byte, error)

DebugGetPage returns a page by number (for debugging).

func (*Txn) Del 

func (txn *Txn) Del(dbi DBI, key, value []byte) error

Del deletes a key (and optionally a specific value for DUPSORT).

func (*Txn) Drop 

func (txn *Txn) Drop(dbi DBI, del bool) error

Drop deletes all data in a database, or deletes the database entirely. If del is true, the database is deleted; otherwise it is emptied.

func (*Txn) Env 

func (txn *Txn) Env() *Env

Env returns the transaction's environment.

func (*Txn) EnvWarmup 

func (txn *Txn) EnvWarmup(flags uint, timeout time.Duration) error

EnvWarmup warms up the environment by reading pages.

func (*Txn) Flags 

func (txn *Txn) Flags(dbi DBI) (uint, error)

Flags returns the flags for a database. This is an alias for DBIFlags (mdbx-go compatibility).

func (*Txn) Get 

func (txn *Txn) Get(dbi DBI, key []byte) ([]byte, error)

Get retrieves a value by key. This is optimized to avoid cursor allocation for simple lookups.

func (*Txn) GetTree 

func (txn *Txn) GetTree(dbi DBI) *tree

GetTree returns the tree info for a DBI (for debugging).

func (*Txn) ID 

func (txn *Txn) ID() uint64

ID returns the transaction ID.

func (*Txn) Info 

func (txn *Txn) Info(scanRlt bool) (*TxInfo, error)

Info returns information about the transaction.

func (*Txn) IsReadOnly 

func (txn *Txn) IsReadOnly() bool

IsReadOnly returns true if this is a read-only transaction.

func (*Txn) ListDBI 

func (txn *Txn) ListDBI() ([]string, error)

ListDBI lists all named databases.

func (*Txn) OpenCursor 

func (txn *Txn) OpenCursor(dbi DBI) (*Cursor, error)

OpenCursor opens a cursor on a database.

func (*Txn) OpenDBI 

func (txn *Txn) OpenDBI(name string, flags uint, cmp, dcmp CmpFunc) (DBI, error)

OpenDBI opens a database/table within the transaction. The cmp parameter is the key comparison function (nil for default). The dcmp parameter is the data/value comparison function for DUPSORT (nil for default).

func (*Txn) OpenDBISimple 

func (txn *Txn) OpenDBISimple(name string, flags uint) (DBI, error)

OpenDBISimple opens a database/table within the transaction using default comparators. This is the simple form without custom comparators (mdbx-go compatibility).

func (*Txn) OpenRoot 

func (txn *Txn) OpenRoot(flags uint) (DBI, error)

OpenRoot opens the root/main database.

func (*Txn) Park 

func (txn *Txn) Park(autounpark bool) error

Park parks a read-only transaction, releasing its reader slot.

func (*Txn) Put 

func (txn *Txn) Put(dbi DBI, key, value []byte, flags uint) error

Put stores a key-value pair.

func (*Txn) PutReserve 

func (txn *Txn) PutReserve(dbi DBI, key []byte, n int, flags uint) ([]byte, error)

PutReserve reserves space for a value and returns a slice to write into.

func (*Txn) ReleaseAllCursors 

func (txn *Txn) ReleaseAllCursors(unbind bool) error

ReleaseAllCursors closes all cursors in the transaction.

func (*Txn) Renew 

func (txn *Txn) Renew() error

Renew renews a reset read-only transaction.

func (*Txn) Reset 

func (txn *Txn) Reset()

Reset resets a read-only transaction for reuse.

func (*Txn) RunOp 

func (txn *Txn) RunOp(fn TxnOp, terminate bool) error

RunOp runs a function in the transaction. If terminate is true, the transaction is committed/aborted based on error.

func (*Txn) Sequence 

func (txn *Txn) Sequence(dbi DBI, increment uint64) (uint64, error)

Sequence gets or updates the sequence number for a database. If increment > 0, adds to the sequence and returns the new value. If increment == 0, returns the current value without changing it.

func (*Txn) SetUserCtx 

func (txn *Txn) SetUserCtx(ctx any)

SetUserCtx sets user context on the transaction.

func (*Txn) Stat 

func (txn *Txn) Stat(dbi DBI) (*Stat, error)

Stat returns statistics for a database.

func (*Txn) StatDBI 

func (txn *Txn) StatDBI(dbi DBI) (*Stat, error)

StatDBI returns statistics for a database. This is an alias for Stat (mdbx-go compatibility).

func (*Txn) Sub 

func (txn *Txn) Sub(fn TxnOp) error

Sub runs a nested transaction.

func (*Txn) Unpark 

func (txn *Txn) Unpark(restartIfOusted bool) error

Unpark resumes a parked transaction.

func (*Txn) UserCtx 

func (txn *Txn) UserCtx() any

UserCtx returns the user context.

type TxnOp 

type TxnOp func(txn *Txn) error

TxnOp is a function that operates on a transaction. This is the callback type for View, Update, and RunTxn.

type VersionInfo 

type VersionInfo struct {
	Major    uint8
	Minor    uint8
	Release  uint8
	Revision uint16
	Git      string
	Describe string
	Datetime string
	Tree     string
	Commit   string
	Sourcery string
}

VersionInfo contains version information (mdbx-go compatibility).

func GetVersionInfo 

func GetVersionInfo() VersionInfo

GetVersionInfo returns version information (mdbx-go compatibility).

Source Files

View all Source files

Directories

Path Synopsis
Package fastmap provides a fast hash map for integer keys.
 Package fastmap provides a fast hash map for integer keys.
Package mmap provides cross-platform memory mapping functionality.
 Package mmap provides cross-platform memory mapping functionality.
Package spill provides a memory-mapped spill buffer for dirty pages.
 Package spill provides a memory-mapped spill buffer for dirty pages.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.