kvdb

Documentation

Index

• Constants
• Variables
• func Batch(db Backend, f func(tx RwTx) error) error
• func ForAll(b RBucket, cb func(k, v []byte) error) error
• func LoggableKeyName(key []byte) string
• func NewBoltFixture(t *testing.T) *boltFixture
• func NewPostgresFixture(dbName string) (postgres.Fixture, error)
• func Prefetch(b RBucket, paths ...[]string)
• func RunTests(m *testing.M)
• func StartEmbeddedPostgres() (func() error, error)
• func StartEtcdTestBackend(path string, clientPort, peerPort uint16, logFile string) (*etcd.Config, func(), error)
• func Update(db Backend, f func(tx RwTx) error, reset func()) error
• func UseLogger(logger slog.Logger)
• func View(db Backend, f func(tx RTx) error, reset func()) error
• type Backend
  • func GetBoltBackend(cfg *BoltBackendConfig) (Backend, error)
  • func GetTestBackend(path, name string) (Backend, func(), error)
• type BoltBackendConfig
• type BoltConfig
• type Driver
• type ExtendedRBucket
• type ExtendedRTx
• type KV
• type RBucket
  • func RootBucket(t RTx) RBucket
• type RCursor
• type RTx
• type RwBucket
• type RwCursor
• type RwTx

Constants

const (
	// DefaultTempDBFileName is the default name of the temporary bolt DB
	// file that we'll use to atomically compact the primary DB file on
	// startup.
	DefaultTempDBFileName = "temp-dont-use.db"

	// LastCompactionFileNameSuffix is the suffix we append to the file name
	// of a database file to record the timestamp when the last compaction
	// occurred.
	LastCompactionFileNameSuffix = ".last-compacted"
)

const (
	// BoltBackendName is the name of the backend that should be passed into
	// kvdb.Create to initialize a new instance of kvdb.Backend backed by a
	// live instance of bolt.
	BoltBackendName = "bdb"

	// EtcdBackendName is the name of the backend that should be passed into
	// kvdb.Create to initialize a new instance of kvdb.Backend backed by a
	// live instance of etcd.
	EtcdBackendName = "etcd"

	// PostgresBackendName is the name of the backend that should be passed
	// into kvdb.Create to initialize a new instance of kvdb.Backend backed
	// by a live instance of postgres.
	PostgresBackendName = "postgres"

	// DefaultBoltAutoCompactMinAge is the default minimum time that must
	// have passed since a bolt database file was last compacted for the
	// compaction to be considered again.
	DefaultBoltAutoCompactMinAge = time.Hour * 24 * 7

	// DefaultDBTimeout specifies the default timeout value when opening
	// the bbolt database.
	DefaultDBTimeout = time.Second * 60
)

const PostgresBackend = false

const TestBackend = BoltBackendName

TestBackend is conditionally set to bdb when the kvdb_etcd build tag is not defined, allowing testing our database code with bolt backend.

Variables

var (
	// ErrBucketNotFound is returned when trying to access a bucket that
	// has not been created yet.
	ErrBucketNotFound = walletdb.ErrBucketNotFound

	// ErrBucketExists is returned when creating a bucket that already
	// exists.
	ErrBucketExists = walletdb.ErrBucketExists

	// ErrDatabaseNotOpen is returned when a database instance is accessed
	// before it is opened or after it is closed.
	ErrDatabaseNotOpen = walletdb.ErrDbNotOpen
)

var Create = walletdb.Create

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 database type is not registered.

var Open = walletdb.Open

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 database type is not registered.

Functions

func Batch

func Batch(db Backend, f func(tx RwTx) error) error

Batch is identical to the Update call, but it attempts to combine several individual Update transactions into a single write database transaction on an optimistic basis. This only has benefits if multiple goroutines call Batch. For etcd Batch simply does an Update since combination is more complex in that case due to STM retries.

func ForAll

func ForAll(b RBucket, cb func(k, v []byte) error) error

ForAll is an optimized version of ForEach with the limitation that no additional queries can be executed within the callback.

func LoggableKeyName

func LoggableKeyName(key []byte) string

LoggableKeyName returns a printable name of the given key.

func NewBoltFixture

func NewBoltFixture(t *testing.T) *boltFixture

func NewPostgresFixture

func NewPostgresFixture(dbName string) (postgres.Fixture, error)

func Prefetch

func Prefetch(b RBucket, paths ...[]string)

Prefetch will attempt to prefetch all values under a path from the passed bucket.

func RunTests

func RunTests(m *testing.M)

RunTests is a helper function to run the tests in a package with initialization and tear-down of a test kvdb backend.

func StartEmbeddedPostgres

func StartEmbeddedPostgres() (func() error, error)

func StartEtcdTestBackend

func StartEtcdTestBackend(path string, clientPort, peerPort uint16,
	logFile string) (*etcd.Config, func(), error)

StartEtcdTestBackend is a stub returning nil, and errEtcdNotAvailable error.

func Update

func Update(db Backend, f func(tx RwTx) error, reset func()) error

Update opens a database read/write transaction and executes the function f with the transaction passed as a parameter. After f exits, if f did not error, the transaction is committed. Otherwise, if f did error, the transaction is rolled back. If the rollback fails, the original error returned by f is still returned. If the commit fails, the commit error is returned. As callers may expect retries of the f closure (depending on the database backend used), the reset function will be called before each retry respectively.

func UseLogger

func UseLogger(logger slog.Logger)

UseLogger uses a specified Logger to output package logging info.

func View

func View(db Backend, f func(tx RTx) error, reset func()) error

View opens a database read transaction and executes the function f with the transaction passed as a parameter. After f exits, the transaction is rolled back. If f errors, its error is returned, not a rollback error (if any occur). The passed reset function is called before the start of the transaction and can be used to reset intermediate state. As callers may expect retries of the f closure (depending on the database backend used), the reset function will be called before each retry respectively.

Types

type Backend

type Backend = walletdb.DB

Backend represents an ACID database. All database access is performed through read or read+write transactions.

func GetBoltBackend

func GetBoltBackend(cfg *BoltBackendConfig) (Backend, error)

GetBoltBackend opens (or creates if doesn't exits) a bbolt backed database and returns a kvdb.Backend wrapping it.

func GetTestBackend

func GetTestBackend(path, name string) (Backend, func(), error)

GetTestBackend opens (or creates if doesn't exist) a bbolt or etcd backed database (for testing), and returns a kvdb.Backend and a cleanup func. Whether to create/open bbolt or embedded etcd database is based on the TestBackend constant which is conditionally compiled with build tag. The passed path is used to hold all db files, while the name is only used for bolt.

type BoltBackendConfig

type BoltBackendConfig struct {
	// DBPath is the directory path in which the database file should be
	// stored.
	DBPath string

	// DBFileName is the name of the database file.
	DBFileName string

	// NoFreelistSync, if true, prevents the database from syncing its
	// freelist to disk, resulting in improved performance at the expense of
	// increased startup time.
	NoFreelistSync bool

	// AutoCompact specifies if a Bolt based database backend should be
	// automatically compacted on startup (if the minimum age of the
	// database file is reached). This will require additional disk space
	// for the compacted copy of the database but will result in an overall
	// lower database size after the compaction.
	AutoCompact bool

	// AutoCompactMinAge specifies the minimum time that must have passed
	// since a bolt database file was last compacted for the compaction to
	// be considered again.
	AutoCompactMinAge time.Duration

	// DBTimeout specifies the timeout value to use when opening the wallet
	// database.
	DBTimeout time.Duration
}

BoltBackendConfig is a struct that holds settings specific to the bolt database backend.

type BoltConfig

type BoltConfig struct {
	NoFreelistSync bool `` /* 274-byte string literal not displayed */

	AutoCompact bool `` /* 365-byte string literal not displayed */

	AutoCompactMinAge time.Duration `` /* 197-byte string literal not displayed */

	DBTimeout time.Duration `long:"dbtimeout" description:"Specify the timeout value used when opening the database."`
}

BoltConfig holds bolt configuration.

type Driver

type Driver = walletdb.Driver

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

type ExtendedRBucket

type ExtendedRBucket interface {
	RBucket

	// Prefetch will attempt to prefetch all values under a path.
	Prefetch(paths ...[]string)

	// ForAll is an optimized version of ForEach.
	//
	// NOTE: ForAll differs from ForEach in that no additional queries can
	// be executed within the callback.
	ForAll(func(k, v []byte) error) error
}

ExtendedRBucket is an extension to walletdb.ReadBucket to allow prefetching of all values inside buckets.

type ExtendedRTx

type ExtendedRTx interface {
	RTx

	// RootBucket returns the "root bucket" which is pseudo bucket used
	// when prefetching (keys from) top level buckets.
	RootBucket() RBucket
}

ExtendedRTx is an extension to walletdb.ReadTx to allow prefetching of keys.

type KV

type KV struct {
	// contains filtered or unexported fields
}

type RBucket

type RBucket = walletdb.ReadBucket

RBucket represents a bucket (a hierarchical structure within the database) that is only allowed to perform read operations.

func RootBucket

func RootBucket(t RTx) RBucket

RootBucket is a wrapper to ExtendedRTx.RootBucket which does nothing if the implementation doesn't have ExtendedRTx.

type RCursor

type RCursor = walletdb.ReadCursor

RCursor represents a bucket cursor that can be positioned at the start or end of the bucket's key/value pairs and iterate over pairs in the bucket. This type is only allowed to perform database read operations.

type RTx

type RTx = walletdb.ReadTx

RTx represents a database transaction that can only be used for reads. If a database update must occur, use a RwTx.

type RwBucket

type RwBucket = walletdb.ReadWriteBucket

RwBucket represents a bucket (a hierarchical structure within the database) that is allowed to perform both read and write operations.

type RwCursor

type RwCursor = walletdb.ReadWriteCursor

RwCursor represents a bucket cursor that can be positioned at the start or end of the bucket's key/value pairs and iterate over pairs in the bucket. This abstraction is allowed to perform both database read and write operations.

type RwTx

type RwTx = walletdb.ReadWriteTx

RwTx represents a database transaction that can be used for both reads and writes. When only reads are necessary, consider using a RTx instead.