github.com/amazechain/amc@v0.1.3/modules/ethdb/db_interface.go (about)

     1  // Copyright 2023 The AmazeChain Authors
     2  // This file is part of the AmazeChain library.
     3  //
     4  // The AmazeChain library is free software: you can redistribute it and/or modify
     5  // it under the terms of the GNU Lesser General Public License as published by
     6  // the Free Software Foundation, either version 3 of the License, or
     7  // (at your option) any later version.
     8  //
     9  // The AmazeChain library is distributed in the hope that it will be useful,
    10  // but WITHOUT ANY WARRANTY; without even the implied warranty of
    11  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
    12  // GNU Lesser General Public License for more details.
    13  //
    14  // You should have received a copy of the GNU Lesser General Public License
    15  // along with the AmazeChain library. If not, see <http://www.gnu.org/licenses/>.
    16  
    17  package ethdb
    18  
    19  import (
    20  	"context"
    21  	"errors"
    22  
    23  	"github.com/ledgerwatch/erigon-lib/kv"
    24  )
    25  
    26  // DESCRIBED: For info on database buckets see docs/programmers_guide/db_walkthrough.MD
    27  
    28  // ErrKeyNotFound is returned when key isn't found in the database.
    29  var ErrKeyNotFound = errors.New("db: key not found")
    30  
    31  type TxFlags uint
    32  
    33  const (
    34  	RW TxFlags = 0x00 // default
    35  	RO TxFlags = 0x02
    36  )
    37  
    38  // DBGetter wraps the database read operations.
    39  type DBGetter interface {
    40  	kv.Getter
    41  
    42  	// Get returns the value for a given key if it's present.
    43  	Get(bucket string, key []byte) ([]byte, error)
    44  }
    45  
    46  // Database wraps all database operations. All methods are safe for concurrent use.
    47  type Database interface {
    48  	DBGetter
    49  	kv.Putter
    50  	kv.Deleter
    51  	kv.Closer
    52  
    53  	Begin(ctx context.Context, flags TxFlags) (DbWithPendingMutations, error) // starts db transaction
    54  	Last(bucket string) ([]byte, []byte, error)
    55  
    56  	IncrementSequence(bucket string, amount uint64) (uint64, error)
    57  	ReadSequence(bucket string) (uint64, error)
    58  	RwKV() kv.RwDB
    59  }
    60  
    61  // MinDatabase is a minimalistic version of the Database interface.
    62  type MinDatabase interface {
    63  	Get(bucket string, key []byte) ([]byte, error)
    64  	Put(table string, k, v []byte) error
    65  	Delete(table string, k []byte) error
    66  }
    67  
    68  // DbWithPendingMutations is an extended version of the Database,
    69  // where all changes are first made in memory.
    70  // Later they can either be committed to the database or rolled back.
    71  type DbWithPendingMutations interface {
    72  	Database
    73  
    74  	// Commit - commits transaction (or flush data into underlying db object in case of `mutation`)
    75  	//
    76  	// Common pattern:
    77  	//
    78  	// tx := db.Begin()
    79  	// defer tx.Rollback()
    80  	// ... some calculations on `tx`
    81  	// tx.Commit()
    82  	//
    83  	Commit() error
    84  
    85  	Rollback()
    86  	BatchSize() int
    87  }
    88  
    89  type HasRwKV interface {
    90  	RwKV() kv.RwDB
    91  	SetRwKV(kv kv.RwDB)
    92  }
    93  
    94  type HasTx interface {
    95  	Tx() kv.Tx
    96  }
    97  
    98  type BucketsMigrator interface {
    99  	BucketExists(bucket string) (bool, error) // makes them empty
   100  	ClearBuckets(buckets ...string) error     // makes them empty
   101  	DropBuckets(buckets ...string) error      // drops them, use of them after drop will panic
   102  }
   103  
   104  func GetOneWrapper(dat []byte, err error) ([]byte, error) {
   105  	if err != nil {
   106  		return nil, err
   107  	}
   108  	if dat == nil {
   109  		return nil, ErrKeyNotFound
   110  	}
   111  	return dat, nil
   112  }