github.com/MetalBlockchain/metalgo@v1.11.9/database/database.go (about)

     1  // Copyright (C) 2019-2024, Ava Labs, Inc. All rights reserved.
     2  // See the file LICENSE for licensing terms.
     3  
     4  // For ease of implementation, our database's interface matches Ethereum's
     5  // database implementation. This was to allow use to use Geth code as is for the
     6  // EVM chain.
     7  
     8  package database
     9  
    10  import (
    11  	"io"
    12  
    13  	"github.com/MetalBlockchain/metalgo/api/health"
    14  )
    15  
    16  // KeyValueReader wraps the Has and Get method of a backing data store.
    17  type KeyValueReader interface {
    18  	// Has retrieves if a key is present in the key-value data store.
    19  	//
    20  	// Note: [key] is safe to modify and read after calling Has.
    21  	Has(key []byte) (bool, error)
    22  
    23  	// Get retrieves the given key if it's present in the key-value data store.
    24  	// Returns ErrNotFound if the key is not present in the key-value data store.
    25  	//
    26  	// Note: [key] is safe to modify and read after calling Get.
    27  	// The returned byte slice is safe to read, but cannot be modified.
    28  	Get(key []byte) ([]byte, error)
    29  }
    30  
    31  // KeyValueWriter wraps the Put method of a backing data store.
    32  type KeyValueWriter interface {
    33  	// Put inserts the given value into the key-value data store.
    34  	//
    35  	// Note: [key] and [value] are safe to modify and read after calling Put.
    36  	//
    37  	// If [value] is nil or an empty slice, then when it's retrieved
    38  	// it may be nil or an empty slice.
    39  	//
    40  	// Similarly, a nil [key] is treated the same as an empty slice.
    41  	Put(key []byte, value []byte) error
    42  }
    43  
    44  // KeyValueDeleter wraps the Delete method of a backing data store.
    45  type KeyValueDeleter interface {
    46  	// Delete removes the key from the key-value data store.
    47  	//
    48  	// Note: [key] is safe to modify and read after calling Delete.
    49  	Delete(key []byte) error
    50  }
    51  
    52  // KeyValueReaderWriter allows read/write acccess to a backing data store.
    53  type KeyValueReaderWriter interface {
    54  	KeyValueReader
    55  	KeyValueWriter
    56  }
    57  
    58  // KeyValueWriterDeleter allows write/delete acccess to a backing data store.
    59  type KeyValueWriterDeleter interface {
    60  	KeyValueWriter
    61  	KeyValueDeleter
    62  }
    63  
    64  // KeyValueReaderWriterDeleter allows read/write/delete access to a backing data store.
    65  type KeyValueReaderWriterDeleter interface {
    66  	KeyValueReader
    67  	KeyValueWriter
    68  	KeyValueDeleter
    69  }
    70  
    71  // Compacter wraps the Compact method of a backing data store.
    72  type Compacter interface {
    73  	// Compact the underlying DB for the given key range.
    74  	// Specifically, deleted and overwritten versions are discarded,
    75  	// and the data is rearranged to reduce the cost of operations
    76  	// needed to access the data. This operation should typically only
    77  	// be invoked by users who understand the underlying implementation.
    78  	//
    79  	// A nil start is treated as a key before all keys in the DB.
    80  	// And a nil limit is treated as a key after all keys in the DB.
    81  	// Therefore if both are nil then it will compact entire DB.
    82  	//
    83  	// Note: [start] and [limit] are safe to modify and read after calling Compact.
    84  	Compact(start []byte, limit []byte) error
    85  }
    86  
    87  // Database contains all the methods required to allow handling different
    88  // key-value data stores backing the database.
    89  type Database interface {
    90  	KeyValueReaderWriterDeleter
    91  	Batcher
    92  	Iteratee
    93  	Compacter
    94  	io.Closer
    95  	health.Checker
    96  }