Skip to content

kv.md

Latest commit

 

History

History
89 lines (66 loc) · 2.11 KB

kv.md

File metadata and controls

89 lines (66 loc) · 2.11 KB

Key-Value Store (KV)

The Key-Value Store (KV) is the main interface for interacting with BlockchainDB. It provides a simple key-value database implementation optimized for blockchain applications.

Overview

The KV component combines several underlying components to provide efficient storage and retrieval:

  • Uses BFile for value storage
  • Uses KFile for key management
  • Optionally uses HistoryFile for maintaining historical data

Structure

type KV struct {
    Directory   string
    vFile       *BFile
    kFile       *KFile
    HistoryFile *HistoryFile
    UseHistory  bool
}

Key Features

  • Fixed-size 32-byte keys
  • Variable-length values
  • Optional history tracking
  • Efficient storage with separate files for keys and values

Basic Operations

Creating a New KV Store

// Create a new KV store with history enabled
kv, err := blockchainDB.NewKV(
    true,           // Enable history
    "/path/to/db",  // Directory path
    1024,           // Number of offset entries
    10000,          // Key limit before history push
    100,            // Max cached blocks
)

Opening an Existing KV Store

// Open an existing KV store
kv, err := blockchainDB.OpenKV("/path/to/db")

Storing Data

// Create a 32-byte key
var key [32]byte
// Fill key with data...

// Store a value
err := kv.Put(key, []byte("value data"))

Retrieving Data

// Retrieve a value using its key
value, err := kv.Get(key)

Closing the Store

// Close the KV store
err := kv.Close()

Implementation Details

The KV store separates keys and values into different files:

  • Keys are stored in a structured KFile that enables efficient lookups
  • Values are stored in a BFile with their offsets referenced by the keys
  • When history tracking is enabled, older versions of keys can be preserved

Performance Considerations

  • The separation of keys and values optimizes for blockchain use cases where keys are frequently accessed
  • The buffered file implementation reduces disk I/O operations
  • The Compress() method can be used to reclaim space from deleted or updated values