database

README

database

Package database provides a block and metadata storage database.

Please note that this package is intended to enable pod to support different database backends and is not something that a client can directly access as onlyone entity can have the database open at a time (for most database backends), and that entity will be pod.

When a client wants programmatic access to the data provided by pod, they'll likely want to use the rpcclient package which makes use of the JSON-RPC API.

However, this package could be extremely useful for any applications requiring Bitcoin block storage capabilities.

The default backend, ffldb, has a strong focus on speed, efficiency, and robustness. It makes use of leveldb for the metadata, flat files for blockstorage, and strict checksums in key areas to ensure data integrity.

Feature Overview

• Key/value metadata store

• Bitcoin block storage

• Efficient retrieval of block headers and regions (transactions, scripts, etc)

• Read-only and read-write transactions with both manual and managed modes

• Nested buckets

• Iteration support including cursors with seek capability

• Supports registration of backend databases

• Comprehensive test coverage

Installation and Updating

$ go get -u github.com/p9c/pod/database

Examples

• Basic Usage Example
  Demonstrates creating a new database and using a managed read-write transaction to store and retrieve metadata.

• Block Storage and Retrieval Example
  Demonstrates creating a new database, using a managed read-write transaction to store a block, and then using a managed read-only transaction to fetch the block.

License

Package database is licensed under the copyfree ISC License.

Documentation

Overview

Package database provides a block and metadata storage database.

Overview

As of Feb 2016, there are over 400,000 blocks in the Bitcoin block chain and and over 112 million transactions (which turns out to be over 60GB of data). This package provides a database layer to store and retrieve this data in a simple and efficient manner.

The default backend, ffldb, has a strong focus on speed, efficiency, and robustness. It makes use leveldb for the metadata, flat files for block storage, and strict checksums in key areas to ensure data integrity. A quick overview of the features database provides are as follows:

• Key/value metadata store

• Bitcoin block storage

• Efficient retrieval of block headers and regions (transactions, scripts, etc)

• Read-only and read-write transactions with both manual and managed modes

• Nested buckets

• Supports registration of backend databases

• Comprehensive test coverage

Database

The main entry point is the DB interface. It exposes functionality for transactional-based access and storage of metadata and block data. It is obtained via the Create and Open functions which take a database type string that identifies the specific database driver (backend) to use as well as arguments specific to the specified driver. The interface provides facilities for obtaining transactions (the Tx interface) that are the basis of all database reads and writes. Unlike some database interfaces that support reading and writing without transactions, this interface requires transactions even when only reading or writing a single key. The Begin function provides an unmanaged transaction while the View and Update functions provide a managed transaction. These are described in more detail below.

Transactions

The Tx interface provides facilities for rolling back or committing changes that took place while the transaction was active. It also provides the root metadata bucket under which all keys, values, and nested buckets are stored. A transaction can either be read-only or read-write and managed or unmanaged.

Managed versus Unmanaged Transactions

A managed transaction is one where the caller provides a function to execute within the context of the transaction and the commit or rollback is handled automatically depending on whether or not the provided function returns an error. Attempting to manually call Rollback or Commit on the managed transaction will result in a panic.

An unmanaged transaction, on the other hand, requires the caller to manually call Commit or Rollback when they are finished with it. Leaving transactions open for long periods of time can have several adverse effects, so it is recommended that managed transactions are used instead.

Buckets

The Bucket interface provides the ability to manipulate key/value pairs and nested buckets as well as iterate through them.

The Get, Put, and Delete functions work with key/value pairs, while the Bucket, CreateBucket, CreateBucketIfNotExists, and DeleteBucket functions work with buckets. The ForEach function allows the caller to provide a function to be called with each key/value pair and nested bucket in the current bucket.

Metadata Bucket

As discussed above, all of the functions which are used to manipulate key/value pairs and nested buckets exist on the Bucket interface. The root metadata bucket is the upper-most bucket in which data is stored and is created at the same time as the database. Use the Metadata function on the Tx interface to retrieve it.

Nested Buckets

The CreateBucket and CreateBucketIfNotExists functions on the Bucket interface provide the ability to create an arbitrary number of nested buckets. It is a good idea to avoid a lot of buckets with little data in them as it could lead to poor page utilization depending on the specific driver in use.

Example (BasicUsage)

This example demonstrates creating a new database and using a managed read-write transaction to store and retrieve metadata.

package main

import (
	"bytes"
	"fmt"
	"os"
	"path/filepath"

	"github.com/p9c/pod/pkg/chain/wire"
	database "github.com/p9c/pod/pkg/db"

	_ "github.com/p9c/pod/pkg/db/ffldb"
)

func main() {
	// This example assumes the ffldb driver is imported.
	//
	// import (
	// 	"github.com/p9c/pod/pkg/db"
	// 	_ "github.com/p9c/pod/pkg/db/ffldb"
	// )
	//
	// Create a database and schedule it to be closed and removed on exit. Typically you wouldn't want to remove the
	// database right away like this, nor put it in the temp directory, but it's done here to ensure the example cleans
	// up after itself.
	dbPath := filepath.Join(os.TempDir(), "exampleusage")
	db, err := database.Create("ffldb", dbPath, wire.MainNet)
	if err != nil {
		database.Error(err)
		return
	}
	defer func() {
		if err := os.RemoveAll(dbPath); database.Check(err) {
		}
	}()
	defer func() {
		if err := db.Close(); database.Check(err) {
		}
	}()
	// Use the Update function of the database to perform a managed read-write transaction. The transaction will
	// automatically be rolled back if the supplied inner function returns a non-nil error.
	err = db.Update(func(tx database.Tx) error {
		// Store a key/value pair directly in the metadata bucket. Typically a nested bucket would be used for a given
		// feature, but this example is using the metadata bucket directly for simplicity.
		key := []byte("mykey")
		value := []byte("myvalue")
		if err := tx.Metadata().Put(key, value); err != nil {
			return err
		}
		// Read the key back and ensure it matches.
		if !bytes.Equal(tx.Metadata().Get(key), value) {
			return fmt.Errorf("unexpected value for key '%s'", key)
		}
		// Create a new nested bucket under the metadata bucket.
		nestedBucketKey := []byte("mybucket")
		nestedBucket, err := tx.Metadata().CreateBucket(nestedBucketKey)
		if err != nil {
			return err
		}
		// The key from above that was set in the metadata bucket does not exist in this new nested bucket.
		if nestedBucket.Get(key) != nil {
			return fmt.Errorf("key '%s' is not expected nil", key)
		}
		return nil
	})
	if err != nil {
		database.Error(err)
		return
	}
}

Index

• func Check(err error) bool
• func Debug(a ...interface{})
• func Debugc(fn func() string)
• func Debugf(format string, a ...interface{})
• func Debugs(a interface{})
• func Error(a ...interface{})
• func Errorc(fn func() string)
• func Errorf(format string, a ...interface{})
• func Errors(a interface{})
• func Fatal(a ...interface{})
• func Fatalc(fn func() string)
• func Fatalf(format string, a ...interface{})
• func Fatals(a interface{})
• func Info(a ...interface{})
• func Infoc(fn func() string)
• func Infof(format string, a ...interface{})
• func Infos(a interface{})
• func RegisterDriver(driver Driver) error
• func SupportedDrivers() []string
• func Trace(a ...interface{})
• func Tracec(fn func() string)
• func Tracef(format string, a ...interface{})
• func Traces(a interface{})
• func Warn(a ...interface{})
• func Warnc(fn func() string)
• func Warnf(format string, a ...interface{})
• func Warns(a interface{})
• type BlockRegion
• type Bucket
• type Cursor
• type DB
  • func Create(dbType string, args ...interface{}) (DB, error)
  • func Open(dbType string, args ...interface{}) (DB, error)
• type DBError
  • func (e DBError) Error() string
• type Driver
• type ErrorCode
  • func (e ErrorCode) String() string
• type Tx

Examples

• Package (BasicUsage)
• Create

Functions

func Check

func Check(err error) bool

func Debug

func Debug(a ...interface{})

func Debugc

func Debugc(fn func() string)

func Debugf

func Debugf(format string, a ...interface{})

func Debugs

func Debugs(a interface{})

func Error

func Error(a ...interface{})

func Errorc

func Errorc(fn func() string)

func Errorf

func Errorf(format string, a ...interface{})

func Errors

func Errors(a interface{})

func Fatal

func Fatal(a ...interface{})

func Fatalc

func Fatalc(fn func() string)

func Fatalf

func Fatalf(format string, a ...interface{})

func Fatals

func Fatals(a interface{})

func Info

func Info(a ...interface{})

func Infoc

func Infoc(fn func() string)

func Infof

func Infof(format string, a ...interface{})

func Infos

func Infos(a interface{})

func RegisterDriver

func RegisterDriver(driver Driver) error

RegisterDriver adds a backend database driver to available interfaces. ErrDbTypeRegistered will be returned if the database type for the driver has already been registered.

func SupportedDrivers

func SupportedDrivers() []string

SupportedDrivers returns a slice of strings that represent the database drivers that have been registered and are therefore supported.

func Trace

func Trace(a ...interface{})

func Tracec

func Tracec(fn func() string)

func Tracef

func Tracef(format string, a ...interface{})

func Traces

func Traces(a interface{})

func Warn

func Warn(a ...interface{})

func Warnc

func Warnc(fn func() string)

func Warnf

func Warnf(format string, a ...interface{})

func Warns

func Warns(a interface{})

Types

type BlockRegion

type BlockRegion struct {
	Hash   *chainhash.Hash
	Offset uint32
	Len    uint32
}

BlockRegion specifies a particular region of a block identified by the specified hash, given an offset and length.

type Bucket

type Bucket interface {
	// Bucket retrieves a nested bucket with the given key. Returns nil if the bucket does not exist.
	Bucket(key []byte) Bucket
	// CreateBucket creates and returns a new nested bucket with the given key.
	//
	// The interface contract guarantees at least the following errors will be returned (other implementation-specific
	// errors are possible):
	//
	//   - ErrBucketExists if the bucket already exists
	//
	//   - ErrBucketNameRequired if the key is empty
	//
	//   - ErrIncompatibleValue if the key is otherwise invalid for the particular implementation
	//
	//   - ErrTxNotWritable if attempted against a read-only transaction
	//
	//   - ErrTxClosed if the transaction has already been closed
	CreateBucket(key []byte) (Bucket, error)
	// CreateBucketIfNotExists creates and returns a new nested bucket with the given key if it does not already exist.
	//
	// The interface contract guarantees at least the following errors will be returned (other implementation-specific
	// errors are possible):
	//
	//   - ErrBucketNameRequired if the key is empty
	//
	//   - ErrIncompatibleValue if the key is otherwise invalid for the particular implementation
	//
	//   - ErrTxNotWritable if attempted against a read-only transaction
	//
	//   - ErrTxClosed if the transaction has already been closed
	CreateBucketIfNotExists(key []byte) (Bucket, error)
	// DeleteBucket removes a nested bucket with the given key. This also includes removing all nested buckets and keys
	// under the bucket being deleted.
	//
	// The interface contract guarantees at least the following errors will be returned (other implementation-specific
	// errors are possible):
	//
	//   - ErrBucketNotFound if the specified bucket does not exist
	//
	//   - ErrTxNotWritable if attempted against a read-only transaction
	//
	//   - ErrTxClosed if the transaction has already been closed
	DeleteBucket(key []byte) error
	// ForEach invokes the passed function with every key/value pair in the bucket. This does not include nested buckets
	// or the key/value pairs within those nested buckets.
	//
	// WARNING: It is not safe to mutate data while iterating with this method. Doing so may cause the underlying cursor
	// to be invalidated and return unexpected keys and/or values.
	//
	// The interface contract guarantees at least the following errors will be returned (other implementation-specific
	// errors are possible):
	//
	//   - ErrTxClosed if the transaction has already been closed
	//
	// NOTE: The slices returned by this function are only valid during a transaction. Attempting to access them after a
	// transaction has ended results in undefined behavior. Additionally, the slices must NOT be modified by the caller.
	// These constraints prevent additional data copies and allows support for memory-mapped database implementations.
	ForEach(func(k, v []byte) error) error
	// ForEachBucket invokes the passed function with the key of every nested bucket in the current bucket. This does
	// not include any nested buckets within those nested buckets.
	//
	// WARNING: It is not safe to mutate data while iterating with this method. Doing so may cause the underlying cursor
	// to be invalidated and return unexpected keys and/or values.
	//
	// The interface contract guarantees at least the following errors will be returned (other implementation-specific
	// errors are possible):
	//
	//   - ErrTxClosed if the transaction has already been closed
	//
	// NOTE: The keys returned by this function are only valid during a transaction. Attempting to access them after a
	// transaction has ended results in undefined behavior. This constraint prevents additional data copies and allows
	// support for memory-mapped database implementations.
	ForEachBucket(func(k []byte) error) error
	// Cursor returns a new cursor, allowing for iteration over the bucket's key/value pairs and nested buckets in
	// forward or backward order.
	//
	// You must seek to a position using the First, Last, or Seek functions before calling the Next, Prev, Key, or value
	// functions. Failure to do so will result in the same return values as an exhausted cursor, which is false for the
	// Prev and Next functions and nil for Key and value functions.
	Cursor() Cursor
	// Writable returns whether or not the bucket is writable.
	Writable() bool
	// Put saves the specified key/value pair to the bucket. Keys that do not already exist are added and keys that
	// already exist are overwritten.
	//
	// The interface contract guarantees at least the following errors will be returned (other implementation-specific
	// errors are possible):
	//
	//   - ErrKeyRequired if the key is empty
	//
	//   - ErrIncompatibleValue if the key is the same as an existing bucket
	//
	//   - ErrTxNotWritable if attempted against a read-only transaction
	//
	//   - ErrTxClosed if the transaction has already been closed
	//
	// NOTE: The slices passed to this function must NOT be modified by the caller. This constraint prevents the
	// requirement for additional data copies and allows support for memory-mapped database implementations.
	Put(key, value []byte) error
	// Get returns the value for the given key. Returns nil if the key does not exist in this bucket. An empty slice is
	// returned for keys that exist but have no value assigned.
	//
	// NOTE: The value returned by this function is only valid during a transaction. Attempting to access it after a
	// transaction has ended results in undefined behavior. Additionally, the value must NOT be modified by the caller.
	//
	// These constraints prevent additional data copies and allows support for memory-mapped database implementations.
	Get(key []byte) []byte
	// Delete removes the specified key from the bucket. Deleting a key that does not exist does not return an error.
	//
	// The interface contract guarantees at least the following errors will be returned (other implementation-specific
	// errors are possible):
	//
	//   - ErrKeyRequired if the key is empty
	//
	//   - ErrIncompatibleValue if the key is the same as an existing bucket
	//
	//   - ErrTxNotWritable if attempted against a read-only transaction
	//
	//   - ErrTxClosed if the transaction has already been closed
	Delete(key []byte) error
}

Bucket represents a collection of key/value pairs.

type Cursor

type Cursor interface {
	// Bucket returns the bucket the cursor was created for.
	Bucket() Bucket
	// Delete removes the current key/value pair the cursor is at without invalidating the cursor.
	//
	// The interface contract guarantees at least the following errors will be returned (other implementation-specific
	// errors are possible):
	//
	//   - ErrIncompatibleValue if attempted when the cursor points to a nested bucket
	//
	//   - ErrTxNotWritable if attempted against a read-only transaction
	//
	//   - ErrTxClosed if the transaction has already been closed
	Delete() error
	// First positions the cursor at the first key/value pair and returns whether or not the pair exists.
	First() bool
	// Last positions the cursor at the last key/value pair and returns whether or not the pair exists.
	Last() bool
	// Next moves the cursor one key/value pair forward and returns whether or not the pair exists.
	Next() bool
	// Prev moves the cursor one key/value pair backward and returns whether or not the pair exists.
	Prev() bool
	// Seek positions the cursor at the first key/value pair that is greater than or equal to the passed seek key.
	// Returns whether or not the pair exists.
	Seek(seek []byte) bool
	// Key returns the current key the cursor is pointing to.
	Key() []byte
	// Value returns the current value the cursor is pointing to. This will be nil for nested buckets.
	Value() []byte
}

Cursor represents a cursor over key/value pairs and nested buckets of a bucket.

Note that open cursors are not tracked on bucket changes and any modifications to the bucket, with the exception of Cursor.Delete, invalidates the cursor. After invalidation, the cursor must be repositioned, or the keys and values returned may be unpredictable.

type DB

type DB interface {
	// Type returns the database driver type the current database instance was created with.
	Type() string
	// Begin starts a transaction which is either read-only or read-write depending on the specified flag. Multiple
	// read-only transactions can be started simultaneously while only a single read-write transaction can be started at
	// a time. The call will block when starting a read-write transaction when one is already open.
	//
	// NOTE: The transaction must be closed by calling Rollback or Commit on it when it is no longer needed. Failure to
	// do so can result in unclaimed memory and/or inablity to close the database due to locks depending on the specific
	// database implementation.
	Begin(writable bool) (Tx, error)
	// View invokes the passed function in the context of a managed read-only transaction. Any errors returned from the
	// user-supplied function are returned from this function.
	//
	// Calling Rollback or Commit on the transaction passed to the user-supplied function will result in a panic.
	View(fn func(tx Tx) error) error
	// Update invokes the passed function in the context of a managed read-write transaction. Any errors returned from
	// the user-supplied function will cause the transaction to be rolled back and are returned from this function.
	// Otherwise, the transaction is committed when the user-supplied function returns a nil error.
	//
	// Calling Rollback or Commit on the transaction passed to the user-supplied function will result in a panic.
	Update(fn func(tx Tx) error) error
	// Close cleanly shuts down the database and syncs all data. It will block until all database transactions have been
	// finalized (rolled back or committed).
	Close() error
}

DB provides a generic interface that is used to store bitcoin blocks and related metadata. This interface is intended to be agnostic to the actual mechanism used for backend data storage. The RegisterDriver function can be used to add a new backend data storage method.

This interface is divided into two distinct categories of functionality.

The first category is atomic metadata storage with bucket support. This is accomplished through the use of database transactions.

The second category is generic block storage. This functionality is intentionally separate because the mechanism used for block storage may or may not be the same mechanism used for metadata storage. For example, it is often more efficient to store the block data as flat files while the metadata is kept in a database. However, this interface aims to be generic enough to support blocks in the database too, if needed by a particular backend.

func Create

func Create(dbType string, args ...interface{}) (DB, error)

Create initializes and opens a database for the specified type. The arguments are specific to the database type driver. See the documentation for the database driver for further details. ErrDbUnknownType will be returned if the the database type is not registered.

Example

This example demonstrates creating a new database.

package main

import (
	"os"
	"path/filepath"

	"github.com/p9c/pod/pkg/chain/wire"
	database "github.com/p9c/pod/pkg/db"

	_ "github.com/p9c/pod/pkg/db/ffldb"
)

func main() {
	// This example assumes the ffldb driver is imported.
	//
	// import (
	// 	"github.com/p9c/pod/pkg/db"
	// 	_ "github.com/p9c/pod/pkg/db/ffldb"
	// )
	//
	// Create a database and schedule it to be closed and removed on exit. Typically you wouldn't want to remove the
	// database right away like this, nor put it in the temp directory, but it's done here to ensure the example cleans
	// up after itself.
	dbPath := filepath.Join(os.TempDir(), "examplecreate")
	db, err := database.Create("ffldb", dbPath, wire.MainNet)
	if err != nil {
		database.Error(err)
		return
	}
	defer func() {
		if err := os.RemoveAll(dbPath); database.Check(err) {
		}
	}()
	defer func() {
		if err := db.Close(); database.Check(err) {
		}
	}()
}

func Open

func Open(dbType string, args ...interface{}) (DB, error)

Open opens an existing database for the specified type. The arguments are specific to the database type driver. See the documentation for the database driver for further details. ErrDbUnknownType will be returned if the the database type is not registered.

type DBError

type DBError struct {
	ErrorCode   ErrorCode // Describes the kind of error
	Description string    // Human readable description of the issue
	Err         error     // Underlying error
}

DBError provides a single type for errors that can happen during database operation. It is used to indicate several types of failures including errors with caller requests such as specifying invalid block regions or attempting to access data against closed database transactions, driver errors, errors retrieving data, and errors communicating with database servers.

The caller can use type assertions to determine if an error is an DBError and access the ErrorCode field to ascertain the specific reason for the failure.

The ErrDriverSpecific error code will also have the Err field set with the underlying error. Depending on the backend driver, the Err field might be set to the underlying error for other error codes as well.

func (DBError) Error

func (e DBError) Error() string

DBError satisfies the error interface and prints human-readable errors.

type Driver

type Driver struct {
	// DbType is the identifier used to uniquely identify a specific database driver. There can be only one driver with
	// the same name.
	DbType string
	// Create is the function that will be invoked with all user-specified arguments to create the database. This
	// function must return ErrDbExists if the database already exists.
	Create func(args ...interface{}) (DB, error)
	// Open is the function that will be invoked with all user-specified arguments to open the database. This function
	// must return ErrDbDoesNotExist if the database has not already been created.
	Open func(args ...interface{}) (DB, error)
	// UseLogger uses a specified Logger to output package logging info.
	UseLogger func(logger log.Logger)
}

Driver defines a structure for backend drivers to use when they registered themselves as a backend which implements the DB interface.

type ErrorCode

type ErrorCode int

ErrorCode identifies a kind of error.

const (
	// ErrDbTypeRegistered indicates two different database drivers attempt to
	// register with the name database type.
	ErrDbTypeRegistered ErrorCode = iota
	// ErrDbUnknownType indicates there is no driver registered for the specified
	// database type.
	ErrDbUnknownType
	// ErrDbDoesNotExist indicates open is called for a database that does not
	// exist.
	ErrDbDoesNotExist
	// ErrDbExists indicates create is called for a database that already exists.
	ErrDbExists
	// ErrDbNotOpen indicates a database instance is accessed before it is opened
	// or after it is closed.
	ErrDbNotOpen
	// ErrDbAlreadyOpen indicates open was called on a database that is already
	// open.
	ErrDbAlreadyOpen
	// ErrInvalid indicates the specified database is not valid.
	ErrInvalid
	// ErrCorruption indicates a checksum failure occurred which invariably means
	// the database is corrupt.
	ErrCorruption
	// ErrTxClosed indicates an attempt was made to commit or rollback a
	// transaction that has already had one of those operations performed.
	ErrTxClosed
	// ErrTxNotWritable indicates an operation that requires write access to the
	// database was attempted against a read-only transaction.
	ErrTxNotWritable
	// ErrBucketNotFound indicates an attempt to access a bucket that has not
	// been created yet.
	ErrBucketNotFound
	// ErrBucketExists indicates an attempt to create a bucket that already
	// exists.
	ErrBucketExists
	// ErrBucketNameRequired indicates an attempt to create a bucket with a blank
	// name.
	ErrBucketNameRequired
	// ErrKeyRequired indicates at attempt to insert a zero-length key.
	ErrKeyRequired
	// ErrKeyTooLarge indicates an attmempt to insert a key that is larger than
	// the max allowed key size. The max key size depends on the specific backend
	// driver being used. As a general rule, key sizes should be relatively, so
	// this should rarely be an issue.
	ErrKeyTooLarge
	// ErrValueTooLarge indicates an attmpt to insert a value that is larger than
	// max allowed value size. The max key size depends on the specific backend
	// driver being used.
	ErrValueTooLarge
	// ErrIncompatibleValue indicates the value in question is invalid for the
	// specific requested operation. For example, trying create or delete a
	// bucket with an existing non-bucket key, attempting to create or delete a
	// non-bucket key with an existing bucket key, or trying to delete a value
	// via a cursor when it points to a nested bucket.
	ErrIncompatibleValue
	// ErrBlockNotFound indicates a block with the provided hash does not exist
	// in the database.
	ErrBlockNotFound
	// ErrBlockExists indicates a block with the provided hash already exists in
	// the database.
	ErrBlockExists
	// ErrBlockRegionInvalid indicates a region that exceeds the bounds of the
	// specified block was requested. When the hash provided by the region does
	// not correspond to an existing block, the error will be ErrBlockNotFound
	// instead.
	ErrBlockRegionInvalid
	// ErrDriverSpecific indicates the Err field is a driver-specific error. This
	// provides a mechanism for drivers to plug-in their own custom errors for
	// any situations which aren't already covered by the error codes provided by
	// this package.
	ErrDriverSpecific
)

These constants are used to identify a specific database DBError.

func (ErrorCode) String

func (e ErrorCode) String() string

String returns the ErrorCode as a human-readable name.

type Tx

type Tx interface {
	// Metadata returns the top-most bucket for all metadata storage.
	Metadata() Bucket
	// StoreBlock stores the provided block into the database. There are no checks to ensure the block connects to a
	// previous block, contains double spends, or any additional functionality such as transaction indexing. It simply
	// stores the block in the database.
	//
	// The interface contract guarantees at least the following errors will be returned (other implementation-specific
	// errors are possible):
	//
	//   - ErrBlockExists when the block hash already exists
	//
	//   - ErrTxNotWritable if attempted against a read-only transaction
	//
	//   - ErrTxClosed if the transaction has already been closed
	//
	// Other errors are possible depending on the implementation.
	StoreBlock(block *util.Block) error
	// HasBlock returns whether or not a block with the given hash exists in the database.
	//
	// The interface contract guarantees at least the following errors will be returned (other implementation-specific
	// errors are possible):
	//
	//   - ErrTxClosed if the transaction has already been closed
	//
	// Other errors are possible depending on the implementation.
	HasBlock(hash *chainhash.Hash) (bool, error)
	// HasBlocks returns whether or not the blocks with the provided hashes
	// exist in the database.
	//
	// The interface contract guarantees at least the following errors will
	// be returned (other implementation-specific errors are possible):
	//
	//   - ErrTxClosed if the transaction has already been closed
	//
	// Other errors are possible depending on the implementation.
	HasBlocks(hashes []chainhash.Hash) ([]bool, error)
	// FetchBlockHeader returns the raw serialized bytes for the block header identified by the given hash. The raw
	// bytes are in the format returned by Serialize on a wire.BlockHeader.
	//
	// It is highly recommended to use this function (or FetchBlockHeaders) to obtain block headers over the
	// FetchBlockRegion(s) functions since it provides the backend drivers the freedom to perform very specific
	// optimizations which can result in significant speed advantages when working with headers.
	//
	// The interface contract guarantees at least the following errors will be returned (other implementation-specific
	// errors are possible):
	//
	//   - ErrBlockNotFound if the requested block hash does not exist
	//
	//   - ErrTxClosed if the transaction has already been closed
	//
	//   - ErrCorruption if the database has somehow become corrupted
	//
	// NOTE: The data returned by this function is only valid during a database transaction. Attempting to access it
	// after a transaction has ended results in undefined behavior. This constraint prevents additional data copies and
	// allows support for memory-mapped database implementations.
	FetchBlockHeader(hash *chainhash.Hash) ([]byte, error)
	// FetchBlockHeaders returns the raw serialized bytes for the block headers identified by the given hashes. The raw
	// bytes are in the format returned by Serialize on a wire.BlockHeader.
	//
	// It is highly recommended to use this function (or FetchBlockHeader) to obtain block headers over the
	// FetchBlockRegion(s) functions since it provides the backend drivers the freedom to perform very specific
	// optimizations which can result in significant speed advantages when working with headers.
	//
	// Furthermore, depending on the specific implementation, this function can be more efficient for bulk loading
	// multiple block headers than loading them one-by-one with FetchBlockHeader.
	//
	// The interface contract guarantees at least the following errors will be returned (other implementation-specific
	// errors are possible):
	//
	//   - ErrBlockNotFound if any of the request block hashes do not exist
	//
	//   - ErrTxClosed if the transaction has already been closed
	//
	//   - ErrCorruption if the database has somehow become corrupted
	//
	// NOTE: The data returned by this function is only valid during a database transaction. Attempting to access it
	// after a transaction has ended results in undefined behavior. This constraint prevents additional data copies and
	// allows support for memory-mapped database implementations.
	FetchBlockHeaders(hashes []chainhash.Hash) ([][]byte, error)
	// FetchBlock returns the raw serialized bytes for the block identified by the given hash. The raw bytes are in the
	// format returned by Serialize on a wire.MsgBlock.
	//
	// The interface contract guarantees at least the following errors will be returned (other implementation-specific
	// errors are possible):
	//
	//   - ErrBlockNotFound if the requested block hash does not exist
	//
	//   - ErrTxClosed if the transaction has already been closed
	//
	//   - ErrCorruption if the database has somehow become corrupted
	//
	// NOTE: The data returned by this function is only valid during a database transaction. Attempting to access it
	// after a transaction has ended results in undefined behavior. This constraint prevents additional data copies and
	// allows support for memory-mapped database implementations.
	FetchBlock(hash *chainhash.Hash) ([]byte, error)
	// FetchBlocks returns the raw serialized bytes for the blocks identified by the given hashes. The raw bytes are in
	// the format returned by Serialize on a wire.MsgBlock.
	//
	// The interface contract guarantees at least the following errors will be returned (other implementation-specific
	// errors are possible):
	//
	//   - ErrBlockNotFound if the any of the requested block hashes do not exist
	//
	//   - ErrTxClosed if the transaction has already been closed
	//
	//   - ErrCorruption if the database has somehow become corrupted
	//
	// NOTE: The data returned by this function is only valid during a database transaction. Attempting to access it
	// after a transaction has ended results in undefined behavior. This constraint prevents additional data copies and
	// allows support for memory-mapped database implementations.
	FetchBlocks(hashes []chainhash.Hash) ([][]byte, error)
	// FetchBlockRegion returns the raw serialized bytes for the given block region.
	//
	// For example, it is possible to directly extract Bitcoin transactions and/or scripts from a block with this
	// function. Depending on the backend implementation, this can provide significant savings by avoiding the need to
	// load entire blocks.
	//
	// The raw bytes are in the format returned by Serialize on a wire.MsgBlock and the Offset field in the provided
	// BlockRegion is zero-based and relative to the start of the block (byte 0).
	//
	// The interface contract guarantees at least the following errors will be returned (other implementation-specific
	// errors are possible):
	//
	//   - ErrBlockNotFound if the requested block hash does not exist
	//
	//   - ErrBlockRegionInvalid if the region exceeds the bounds of the
	//   associated block
	//
	//   - ErrTxClosed if the transaction has already been closed
	//
	//   - ErrCorruption if the database has somehow become corrupted
	//
	// NOTE: The data returned by this function is only valid during a database transaction. Attempting to access it
	// after a transaction has ended results in undefined behavior. This constraint prevents additional data copies and
	// allows support for memory-mapped database implementations.
	FetchBlockRegion(region *BlockRegion) ([]byte, error)
	// FetchBlockRegions returns the raw serialized bytes for the given block regions.
	//
	// For example, it is possible to directly extract Bitcoin transactions and/or scripts from various blocks with this
	// function. Depending on the backend implementation, this can provide significant savings by avoiding the need to
	// load entire blocks.
	//
	// The raw bytes are in the format returned by Serialize on a wire.MsgBlock and the Offset fields in the provided
	// BlockRegions are zero-based and relative to the start of the block (byte 0).
	//
	// The interface contract guarantees at least the following errors will be returned (other implementation-specific
	// errors are possible):
	//
	//   - ErrBlockNotFound if any of the requested block hashed do not exist
	//
	//   - ErrBlockRegionInvalid if one or more region exceed the bounds of the associated block
	//
	//   - ErrTxClosed if the transaction has already been closed
	//
	//   - ErrCorruption if the database has somehow become corrupted
	//
	// NOTE: The data returned by this function is only valid during a database transaction. Attempting to access it
	// after a transaction has ended results in undefined behavior. This constraint prevents additional data copies and
	// allows support for memory-mapped database implementations.
	FetchBlockRegions(regions []BlockRegion) ([][]byte, error)
	// Commit commits all changes that have been made to the metadata or block storage. Depending on the backend
	// implementation this could be to a cache that is periodically synced to persistent storage or directly to
	// persistent storage.
	//
	// In any case, all transactions which are started after the commit finishes will include all changes made by this
	// transaction. Calling this function on a managed transaction will result in a panic.
	Commit() error
	// Rollback undoes all changes that have been made to the metadata or block storage. Calling this function on a
	// managed transaction will result in a panic.
	Rollback() error
}

Tx represents a database transaction. It can either by read-only or read-write. The transaction provides a metadata bucket against which all read and writes occur. As would be expected with a transaction, no changes will be saved to the database until it has been committed. The transaction will only provide a view of the database at the time it was created. Transactions should not be long running operations.