hord

package module

v0.3.0 Latest Latest Go to latest Published: Apr 14, 2024 License: Apache-2.0 Imports: 1 Imported by: 7

Details

Valid go.mod file

The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
Redistributable license

Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
Tagged version

Modules with tagged versions give importers more predictable builds.
Stable version

When a project reaches major version v1 it is considered stable.
Learn more about best practices

Repository

github.com/madflojo/hord

Links

Open Source Insights

README ¶

Hord

GitHub go.mod Go version

Package hord provides a simple and extensible interface for interacting with various database systems in a uniform way.

Hord is designed to be a database-agnostic library that provides a common interface for interacting with different database systems. It allows developers to write code that is decoupled from the underlying database technology, making it easier to switch between databases or support multiple databases in the same application.

Features

Driver-based: Hord follows a driver-based architecture, where each database system is implemented as a separate driver. This allows for easy extensibility to support new databases.
Uniform API: Hord provides a common API for database operations, including key-value operations, setup, and configuration. The API is designed to be simple and intuitive.
Pluggable: Developers can choose and configure the desired database driver based on their specific needs.
Error handling: Hord provides error types and constants for consistent error handling across drivers.
Testing with Mock Driver: Hord provides a mock driver in the mock package, which can be used for testing purposes. The mock driver allows users to define custom functions executed when calling the Database interface methods, making it easier to test code that relies on the Hord interface.
Documentation: Each driver comes with its own package documentation, providing guidance on how to use and configure the driver.

Evolving Features

Cache Implementations: Combine database drivers with pre-defined cache implementations.

Database Drivers:

Database	Support	Comments	Protocol Compatible Alternatives
BoltDB	✅
Cassandra	✅		ScyllaDB, YugabyteDB, Azure Cosmos DB
Hashmap	✅	Optionally allows storing to YAML or JSON file
Mock	✅	Mock Database interactions within unit tests
NATS	✅	Experimental
Redis	✅		Dragonfly, KeyDB

Caching Implementations

Cache Strategy	Comments
Look Aside	Cache is checked before database, if not found in cache, database is checked and cache is updated

Usage

To use Hord, import it as follows:

import "github.com/madflojo/hord"

Creating a Database Client

To create a database client, you need to import and use the appropriate driver package along with the hord package.

For example, to use the Redis driver:

import (
    "github.com/madflojo/hord"
    "github.com/madflojo/hord/redis"
)

func main() {
    var db hord.Database
    db, err := redis.Dial(redis.Config{})
    if err != nil {
        // Handle connection error
    }

    // Use the db client for database operations
    // ...
}

Each driver provides its own Dial function to establish a connection to the database. Refer to the specific driver documentation for more details.

Database Operations

Once you have a database client, you can use it to perform various database operations. The API is consistent across different drivers.

// Set a value
err = db.Set("key", []byte("value"))
if err != nil {
    // Handle error
}

// Retrieve a value
value, err := db.Get("key")
if err != nil {
    // Handle error
}

Refer to the hord.Database interface documentation for a complete list of available methods.

Contributing

Thank you for your interest in helping develop Hord. The time, skills, and perspectives you contribute to this project are valued.

Please reference our Contributing Guide for details.

License

Apache License 2.0

Documentation ¶

Overview ¶

Package hord provides a simple and extensible interface for interacting with various database systems in a uniform way.

Overview ¶

Hord is designed to be a database-agnostic library that provides a common interface for interacting with different database systems. It allows developers to write code that is decoupled from the underlying database technology, making it easier to switch between databases or support multiple databases in the same application.

Usage ¶

To use Hord, import it as follows:

import "github.com/madflojo/hord"

Creating a Database Client ¶

To create a database client, you need to import and use the appropriate driver package along with the `hord` package.

For example, to use the Redis driver:

import (
    "github.com/madflojo/hord"
    "github.com/madflojo/hord/redis"
)

func main() {
    var db hord.Database
    db, err := redis.Dial(redis.Config{})
    if err != nil {
        // Handle connection error
    }

    // Use the db client for database operations
    // ...
}

Each driver provides its own `Dial` function to establish a connection to the database. Refer to the specific driver documentation for more details.

Database Operations ¶

Once you have a database client, you can use it to perform various database operations. The API is consistent across different drivers.

// Set a value
err = db.Set("key", []byte("value"))
if err != nil {
    // Handle error
}

// Retrieve a value
value, err := db.Get("key")
if err != nil {
    // Handle error
}

Refer to the `hord.Database` interface documentation for a complete list of available methods.

Error Handling ¶

Hord provides common error types and constants for consistent error handling across drivers. Refer to the `hord` package documentation for more information on error handling.

Contributing ¶

Contributions to Hord are welcome! If you want to add support for a new database driver or improve the existing codebase, please refer to the contribution guidelines in the project's repository.

Constants ¶

This section is empty.

Variables ¶

View Source

var (
	ErrInvalidKey      = fmt.Errorf("Key cannot be nil")
	ErrInvalidData     = fmt.Errorf("Data cannot be empty")
	ErrNil             = fmt.Errorf("Nil value returned from database")
	ErrNoDial          = fmt.Errorf("No database connection defined, did you dial?")
	ErrInvalidDatabase = fmt.Errorf("Database cannot be nil")
	ErrCacheError      = fmt.Errorf("Cache error")
)

Common Errors Used by Hord Drivers

Functions ¶

func ValidData ¶ added in v0.2.0

func ValidData(data []byte) error

ValidData checks if data is valid. Valid data should have a length greater than 0. Returns nil if the data is valid, otherwise returns ErrInvalidData.

func ValidKey ¶ added in v0.2.0

func ValidKey(key string) error

ValidKey checks if a key is valid. A valid key should have a length greater than 0. Returns nil if the key is valid, otherwise returns ErrInvalidKey.

Types ¶

type Database ¶

type Database interface {
	// Setup is used to setup and configure the underlying database.
	// This can include setting optimal cluster settings, creating a database or tablespace,
	// or even creating the database structure.
	// Setup is meant to allow users to start with a fresh database service and turn it into a production-ready datastore.
	Setup() error

	// HealthCheck performs a check against the underlying database.
	// If any errors are returned, this health check will return an error.
	// An error returned from HealthCheck should be treated as the database service being untrustworthy.
	HealthCheck() error

	// Get is used to fetch data with the provided key.
	Get(key string) ([]byte, error)

	// Set is used to insert and update the specified key.
	// This function can be used on existing keys, with the new data overwriting existing data.
	Set(key string, data []byte) error

	// Delete will delete the data for the specified key.
	Delete(key string) error

	// Keys will return a list of keys for the entire database.
	// This operation can be expensive, use with caution.
	Keys() ([]string, error)

	// Close will close the database connection.
	// After executing close, all other functions should return an error.
	Close()
}

Database is an interface that is used to create a unified database access object.

Source Files ¶

View all Source files

hord.go

Directories ¶

Path	Synopsis
cache Package cache provides a Hord database driver for a variety of caching strategies.	Package cache provides a Hord database driver for a variety of caching strategies.
lookaside Package lookaside provides a Hord database driver for a look-aside cache.	Package lookaside provides a Hord database driver for a look-aside cache.
drivers
bbolt Package bbolt provides a Hord database driver for BoltDB.	Package bbolt provides a Hord database driver for BoltDB.
cassandra Package cassandra provides a Hord database driver for Cassandra.	Package cassandra provides a Hord database driver for Cassandra.
hashmap Package hashmap provides a Hord database driver for an in-memory hashmap.	Package hashmap provides a Hord database driver for an in-memory hashmap.
mock Package mock is a Hord database driver used to assist in testing.	Package mock is a Hord database driver used to assist in testing.
nats Package nats provides a Hord database driver for the NATS key-value store.	Package nats provides a Hord database driver for the NATS key-value store.
redis Package redis provides a Hord database driver for Redis.	Package redis provides a Hord database driver for Redis.

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL