README
¶
TreeDB geth ethdb adapter
This nested module provides a reusable adapter from TreeDB to go-ethereum's
ethdb.KeyValueStore / ethdb.Batch interfaces without adding a go-ethereum
dependency to gomap's root module or core TreeDB packages.
Package
import gethethdb "github.com/snissn/gomap/TreeDB/integration/gethethdb"
Primary APIs:
Open(path string, options *OpenOptions) (*Database, error)OpenWithOptions(opts treedb.Options) (*Database, error)Wrap(db *treedb.DB) *Database
Open(nil options) defaults to treedb.ProfileCommandWALDurable. Writable
opens reject non-command-WAL TreeDB options; this adapter is intended for geth
persistent hot-KV durability/recovery through TreeDB command WAL. When callers
leave command-WAL growth knobs at zero, the adapter uses a 256 MiB command-WAL
frame cap, a 256 MiB active-segment rotation target, and a 512 MiB
auto-checkpoint byte trigger. The frame cap lets geth's large beacon
skeleton-header batches fit in one durable frame; the separate rotation and
checkpoint knobs keep active command-WAL growth bounded, including read-only
inspection of an existing command-WAL directory.
Semantics
- No adapter-side key codec is used. TreeDB's native raw-KV parity handles empty keys, nil point keys, and nil values.
- DB-level
DeleteRangecalls publicTreeDB.DB.DeleteRangedirectly. - Nil range bounds remain unbounded; empty range bounds remain concrete empty byte-string bounds.
NewIterator(prefix, start)iteratesprefixkeys starting atprefix || start.SyncKeyValuemaps toTreeDB.DB.Checkpoint().Compact(nil, nil)maps to TreeDB's high-levelCompactStoragefull-storage compaction sequence.- Bounded
Compact(start, limit)calls with non-nillimitare accepted as advisory no-ops because TreeDB does not currently expose geth-style range-scoped compaction. A nillimitalso handles the final tail range in geth's 16/256-range compaction sweeps and runs one full TreeDB storage compaction.
Validation
Run from this directory:
go test ./... -count=1
go test ./... -run 'TestCommandWALReopen|TestDatabaseSuite' -count=1
go test ./... -bench 'BenchmarkAdapterVsDirect/(Put|Get|BatchWrite|Iterator|DeleteRange|BatchDeleteRange)' -benchtime=100x -count=1
Dependency strategy
The module pins resolvable requirements at their declared module paths:
github.com/ethereum/go-ethereumfor the standardethdbinterfaces.github.com/snissn/gomapfor TreeDB.
No replace directive is required for normal consumers. When this adapter is
imported from a geth fork whose module path is github.com/ethereum/go-ethereum
(such as snissn/go-ethereum-nitro), the fork's main module supplies the
ethdb package. If a downstream experiment needs a local gomap checkout or a
newer untagged gomap commit, add the github.com/snissn/gomap replace in that
experiment's main module or Go workspace rather than relying on this module to
propagate replaces.
Documentation
¶
Overview ¶
Package gethethdb adapts TreeDB to go-ethereum's ethdb.KeyValueStore.
The adapter is intentionally kept in an integration submodule so gomap's root module and core TreeDB packages do not depend on go-ethereum. It uses TreeDB's native raw-KV byte-string semantics: nil point keys are canonicalized by TreeDB to empty keys, nil values to zero-length values, and nil range bounds remain unbounded.
Index ¶
- Constants
- Variables
- type Batch
- func (b *Batch) Close()
- func (b *Batch) Delete(key []byte) error
- func (b *Batch) DeleteRange(start, end []byte) error
- func (b *Batch) Put(key []byte, value []byte) error
- func (b *Batch) Replay(w ethdb.KeyValueWriter) error
- func (b *Batch) Reset()
- func (b *Batch) ValueSize() int
- func (b *Batch) Write() error
- type Database
- func (d *Database) Close() error
- func (d *Database) Compact(start []byte, limit []byte) error
- func (d *Database) Delete(key []byte) error
- func (d *Database) DeleteRange(start, end []byte) error
- func (d *Database) Get(key []byte) ([]byte, error)
- func (d *Database) Has(key []byte) (bool, error)
- func (d *Database) NewBatch() ethdb.Batch
- func (d *Database) NewBatchWithSize(size int) ethdb.Batch
- func (d *Database) NewIterator(prefix []byte, start []byte) ethdb.Iterator
- func (d *Database) Put(key []byte, value []byte) error
- func (d *Database) Stat() (string, error)
- func (d *Database) SyncKeyValue() error
- func (d *Database) TreeDB() *treedb.DB
- type Iterator
- type OpenOptions
Constants ¶
const ( // EnvReadIntegrity selects value-log read checksum verification for the geth // TreeDB adapter. Empty preserves the selected profile/default. Use // "unsafe-skip-checksums" only for explicitly labeled benchmark ceilings. EnvReadIntegrity = "TREEDB_GETH_READ_INTEGRITY" // EnvReadIntegrityFallback is a generic alias honored when EnvReadIntegrity is unset. EnvReadIntegrityFallback = "TREEDB_READ_INTEGRITY" )
Variables ¶
var ( ErrClosed = treedb.ErrClosed ErrNotFound = treedb.ErrKeyNotFound )
Adapter errors are aliases to TreeDB errors so callers can use errors.Is.
Functions ¶
This section is empty.
Types ¶
type Batch ¶
type Batch struct {
// contains filtered or unexported fields
}
Batch implements ethdb.Batch.
func (*Batch) Close ¶
func (b *Batch) Close()
Close releases the underlying TreeDB batch when present. It matches newer geth ethdb.Batch interfaces and is harmless as an extra method for older geth versions where Batch has no Close method.
func (*Batch) DeleteRange ¶
DeleteRange records a range deletion in [start, end).
func (*Batch) Replay ¶
func (b *Batch) Replay(w ethdb.KeyValueWriter) error
Replay replays the batch contents in submitted order. TreeDB's internal batch replay may compact or sort point-only batches, so the adapter keeps a small copied operation log specifically for ethdb Replay semantics.
type Database ¶
type Database struct {
// contains filtered or unexported fields
}
Database implements ethdb.KeyValueStore on top of TreeDB.
func Open ¶
func Open(path string, options *OpenOptions) (*Database, error)
Open opens a TreeDB-backed ethdb.KeyValueStore at path.
func OpenWithOptions ¶
OpenWithOptions opens TreeDB with caller-supplied options and wraps it as an ethdb.KeyValueStore. Writable options must enable TreeDB command WAL. When WALMaxSegmentBytes and command-WAL growth knobs are left at zero, the adapter applies geth-sized defaults before open so command-WAL activation from persisted format config also uses the larger cap.
func Wrap ¶
Wrap adapts an already-open TreeDB handle. The caller owns the handle through the returned Database; Close closes the wrapped TreeDB handle.
func (*Database) Compact ¶
Compact accepts geth ethdb compaction requests.
TreeDB currently has no range-scoped compaction equivalent to geth's LevelDB/Pebble range compaction. Bounded ranges are therefore treated as advisory no-ops so geth range sweeps do not multiply full-storage compaction cost. A nil limit represents either geth's whole-DB request (nil, nil) or the final tail range in geth range sweeps, and runs TreeDB's high-level storage compaction entrypoint.
func (*Database) DeleteRange ¶
DeleteRange deletes all keys in [start, end). Nil bounds remain unbounded; empty bounds are passed through as concrete empty byte-string bounds.
func (*Database) NewBatch ¶
NewBatch creates a write-only batch. After Database.Close it still returns a batch object so geth's operations-after-close expectations are preserved; that batch accepts queued mutations but Write returns ErrClosed.
func (*Database) NewBatchWithSize ¶
NewBatchWithSize creates a write-only batch with a best-effort size hint.
func (*Database) NewIterator ¶
NewIterator creates a binary-alphabetical iterator over keys with prefix, starting at prefix||start.
func (*Database) SyncKeyValue ¶
SyncKeyValue forces a TreeDB checkpoint/durability boundary for pending raw-KV command-WAL writes.
type Iterator ¶
type Iterator struct {
// contains filtered or unexported fields
}
Iterator implements ethdb.Iterator.
type OpenOptions ¶
type OpenOptions struct {
// Profile selects a public TreeDB profile. Empty defaults to
// treedb.ProfileCommandWALDurable. Non-command-WAL write profiles are
// rejected because this adapter is intended for geth/Nitro persistent KV
// durability through TreeDB command WAL.
Profile treedb.Profile
// Options, when non-nil, supplies TreeDB options to use. Open copies the
// struct, forces Dir to the Open path when path is non-empty, applies
// ReadOnly/KeepRecent/MemtableMode overrides below, applies geth-safe WAL
// sizing defaults for zero-valued knobs, and still requires CommandWAL for
// writable opens.
Options *treedb.Options
// ReadOnly opens the TreeDB directory read-only.
ReadOnly bool
// KeepRecent and MemtableMode are optional TreeDB knobs useful for downstream
// integrations. Zero/empty leave the selected profile defaults intact.
KeepRecent uint64
MemtableMode string
}
OpenOptions configures Open.
func DefaultOpenOptions ¶
func DefaultOpenOptions() OpenOptions
DefaultOpenOptions returns the production-oriented adapter defaults.
Source Files