Documentation
¶
Overview ¶
Package db provides an abstraction for key-value database operations through the Provider interface. It defines a common interface for database interactions, including setting, retrieving, checking the existence of, and deleting key-value pairs, as well as managing the lifecycle of the database (e.g., closing and destroying).
This package allows for flexible use of different database backends, such as MDBX, while maintaining a consistent API for interacting with the database.
Key components of this package include:
**Provider interface**: Defines the essential methods required for any key-value database implementation, including Set, Get, Exists, Delete, Close, and Destroy.
**Db struct**: A concrete implementation of the Provider interface for managing MDBX-based databases. It handles opening, closing, and interacting with the MDBX environment.
Example usage:
// Initialize a new database using MDBX
db, err := NewDb(ctx, config.MdbxNode{...})
if err != nil {
log.Fatalf("Failed to create MDBX database: %v", err)
}
// Set a key-value pair
err = db.Set([]byte("key"), []byte("value"))
if err != nil {
log.Fatalf("Failed to set key-value pair: %v", err)
}
// Get a value by key
value, err := db.Get([]byte("key"))
if err != nil {
log.Fatalf("Failed to get value: %v", err)
}
// Close the database
err = db.Close()
if err != nil {
log.Fatalf("Failed to close database: %v", err)
}
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BatchWriter ¶
type BatchWriter struct {
// contains filtered or unexported fields
}
BatchWriter handles batch writes with concurrency support and multiple workers.
func NewBatchWriter ¶
func NewBatchWriter(db *Db, maxBatchSize int, flushInterval time.Duration, workers int) *BatchWriter
NewBatchWriter initializes a BatchWriter with a configurable number of workers.
func (*BatchWriter) BufferWrite ¶
func (bw *BatchWriter) BufferWrite(key [32]byte, value []byte)
BufferWrite adds a key-value pair to the batch and writes it to the worker's dedicated channel.
func (*BatchWriter) FlushAndStop ¶
func (bw *BatchWriter) FlushAndStop()
FlushAndStop flushes any remaining data and stops the background workers.
type Db ¶
type Db struct {
// contains filtered or unexported fields
}
Db represents a wrapper around an MDBX database environment. It manages the MDBX environment, database instance (DBI), and provides methods to interact with the database, such as setting, getting, deleting key-value pairs, and closing or destroying the database.
func (*Db) Close ¶
Close closes the MDBX environment and releases any resources held by the database.
Example usage:
err := db.Close()
if err != nil {
log.Fatalf("Failed to close MDBX database: %v", err)
}
Returns:
error: Returns an error if the environment cannot be closed.
func (*Db) Delete ¶
Delete removes a key-value pair from the MDBX database.
Example usage:
err := db.Delete([]byte("key"))
if err != nil {
log.Fatalf("Failed to delete key-value pair: %v", err)
}
Parameters:
key ([]byte): The key to remove from the database.
Returns:
error: Returns an error if the key cannot be deleted.
func (*Db) Destroy ¶
Destroy removes the MDBX database files and cleans up the environment. This method first closes the database environment and then deletes the database files.
Example usage:
err := db.Destroy()
if err != nil {
log.Fatalf("Failed to destroy MDBX database: %v", err)
}
Returns:
error: Returns an error if the database files cannot be removed or the environment fails to close.
func (*Db) Exists ¶
Exists checks if a key exists in the MDBX database.
Example usage:
exists, err := db.Exists([]byte("key"))
if err != nil {
log.Fatalf("Failed to check key existence: %v", err)
}
Parameters:
key ([]byte): The key to check for existence.
Returns:
bool: True if the key exists, false otherwise. error: Returns an error if the existence check fails.
func (*Db) Get ¶
Get retrieves the value associated with the given key from the MDBX database.
Example usage:
value, err := db.Get([]byte("key"))
if err != nil {
log.Fatalf("Failed to get value: %v", err)
}
Parameters:
key ([]byte): The key to retrieve the value for.
Returns:
[]byte: The value associated with the key. error: Returns an error if the key is not found or the retrieval fails.
func (*Db) GetDBI ¶
GetDBI returns the MDBX database instance handle.
Example usage:
dbi := db.GetDBI()
Returns:
mdbx.DBI: The MDBX database instance handle.
func (*Db) GetEnv ¶
GetEnv returns the MDBX environment associated with this database instance.
Example usage:
env := db.GetEnv()
Returns:
*mdbx.Env: The MDBX environment handle.
func (*Db) Set ¶
Set stores a key-value pair in the MDBX database. This method starts a transaction to insert or update the value associated with the given key.
Example usage:
err := db.Set([]byte("key"), []byte("value"))
if err != nil {
log.Fatalf("Failed to set key-value pair: %v", err)
}
Parameters:
key ([]byte): The key to store in the database. value ([]byte): The value to associate with the key.
Returns:
error: Returns an error if the key-value pair cannot be stored.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager is responsible for managing multiple MDBX database instances based on the provided configuration. It allows easy access to different databases by name and handles the lifecycle operations such as opening, closing, and managing individual database instances.
The Manager uses the MDBX configuration to set up the databases and manages the connections throughout the application's lifetime.
func NewManager ¶
NewManager creates a new Manager instance that manages multiple MDBX database instances based on the configuration provided. It initializes the databases if MDBX is enabled and stores them in the Manager.
Example usage:
mdbxManager, err := NewManager(ctx, config.Mdbx)
if err != nil {
log.Fatalf("Failed to create MDBX manager: %v", err)
}
Parameters:
ctx (context.Context): The context used for managing the database's lifecycle. opts (config.Mdbx): The MDBX configuration specifying the database nodes.
Returns:
*Manager: A new Manager instance that manages the MDBX databases. error: Returns an error if any database initialization fails.
func (*Manager) Close ¶
Close gracefully closes all managed databases in the Manager. It iterates through all the databases and calls their respective Close methods to ensure proper resource cleanup.
Example usage:
err := mdbxManager.Close()
if err != nil {
log.Fatalf("Failed to close MDBX manager: %v", err)
}
Returns:
error: Returns an error if any of the databases fail to close properly.
func (*Manager) GetDb ¶
GetDb retrieves a specific database by its name (DbType) from the manager. If the database is not found, an error is returned.
Example usage:
db, err := mdbxManager.GetDb("node1")
if err != nil {
log.Fatalf("Failed to retrieve MDBX database: %v", err)
}
Parameters:
name (types.DbType): The name of the database to retrieve.
Returns:
Provider: The database provider associated with the specified name. error: Returns an error if the database is not found.
type Provider ¶
type Provider interface {
// Set stores a key-value pair in the database. If the key already exists,
// the value is updated.
//
// Example usage:
// err := provider.Set([]byte("key"), []byte("value"))
// if err != nil {
// log.Fatalf("Failed to set key-value pair: %v", err)
// }
//
// Parameters:
// key ([]byte): The key to store in the database.
// value ([]byte): The value associated with the key.
//
// Returns:
// error: Returns an error if the key-value pair cannot be stored.
Set(key, value []byte) error
// Get retrieves the value associated with the given key from the database.
//
// Example usage:
// value, err := provider.Get([]byte("key"))
// if err != nil {
// log.Fatalf("Failed to retrieve value: %v", err)
// }
//
// Parameters:
// key ([]byte): The key to retrieve the value for.
//
// Returns:
// []byte: The value associated with the key.
// error: Returns an error if the key is not found or the retrieval fails.
Get(key []byte) ([]byte, error)
// Exists checks if the specified key exists in the database.
//
// Example usage:
// exists, err := provider.Exists([]byte("key"))
// if err != nil {
// log.Fatalf("Failed to check key existence: %v", err)
// }
//
// Parameters:
// key ([]byte): The key to check for existence.
//
// Returns:
// bool: True if the key exists, false otherwise.
// error: Returns an error if the existence check fails.
Exists(key []byte) (bool, error)
// Delete removes a key-value pair from the database.
//
// Example usage:
// err := provider.Delete([]byte("key"))
// if err != nil {
// log.Fatalf("Failed to delete key-value pair: %v", err)
// }
//
// Parameters:
// key ([]byte): The key to remove from the database.
//
// Returns:
// error: Returns an error if the key cannot be deleted.
Delete(key []byte) error
// Close gracefully closes the database, releasing any resources held by the
// database environment.
//
// Example usage:
// err := provider.Close()
// if err != nil {
// log.Fatalf("Failed to close database: %v", err)
// }
//
// Returns:
// error: Returns an error if the database cannot be closed properly.
Close() error
// Destroy permanently removes the database files and cleans up the environment.
//
// Example usage:
// err := provider.Destroy()
// if err != nil {
// log.Fatalf("Failed to destroy database: %v", err)
// }
//
// Returns:
// error: Returns an error if the database files cannot be removed or if there
// is an issue cleaning up the environment.
Destroy() error
}
Provider defines the interface for a key-value database provider. This interface abstracts the basic operations for interacting with a database, allowing for different implementations (e.g., MDBX, BoltDB) to conform to the same interface and be used interchangeably in the application.
The Provider interface includes the following methods for key-value operations: - Set: Store a key-value pair in the database. - Get: Retrieve the value associated with a key. - Exists: Check if a key exists in the database. - Delete: Remove a key-value pair from the database. - Close: Close the database connection. - Destroy: Permanently remove the database files and environment.
func NewDb ¶
NewDb creates a new MDBX database environment based on the provided configuration. It sets the database geometry (min size, max size, growth step), maximum readers, and file permissions. The function returns a Provider interface to allow for interaction with the database.
Example usage:
db, err := NewDb(ctx, config.MdbxNode{...})
if err != nil {
log.Fatalf("Failed to create MDBX database: %v", err)
}
Parameters:
ctx (context.Context): The context for managing the lifecycle of the database. opts (config.MdbxNode): The configuration options for the MDBX database.
Returns:
Provider: A new MDBX database provider for interacting with the database. error: Returns an error if the environment or database creation fails.
type WriteRequest ¶
type WriteRequest struct {
Key [32]byte // Fixed-size byte array for keys
Value []byte // Value as byte slice
}
WriteRequest represents a key-value pair to be written to the database.
Source Files