README
¶
Redka aims to reimplement the core parts of Redis with SQL, while remaining compatible with Redis API.
Highlights:
- Data doesn't have to fit in RAM.
- Supports ACID transactions.
- SQL views for easier analysis and reporting.
- Uses SQLite or PostgreSQL as a backend.
- Runs in-process (Go API) or as a standalone server.
- Implements Redis commands and wire protocol (RESP).
Redka is functionally ready for 1.0. Feel free to try it in non-critical production scenarios and provide feedback in the issues.
Use cases
Here are some situations where Redka might be helpful:
Embedded cache for Go applications. If your Go app already uses SQLite or just needs a built-in key-value store, Redka is a natural fit. It gives you Redis-like features without the hassle of running a separate server. You're not limited to just get/set with expiration, of course — more advanced structures like lists, maps, and sets are also available.
Lightweight testing environment. Your app uses Redis in production, but setting up a Redis server for local development or integration tests can be a hassle. Redka with an in-memory database offers a fast alternative to test containers, providing full isolation for each test run.
Postgres-first data structures. If you prefer to use PostgreSQL for everything but need Redis-like data structures, Redka can use your existing database as the backend. This way, you can manage both relational data and specialized data structures with the same tools and transactional guarantees.
Commands
Redka supports five core Redis data types:
- Strings are the most basic Redis type, representing a sequence of bytes.
- Lists are sequences of strings sorted by insertion order.
- Sets are unordered collections of unique strings.
- Hashes are field-value (hash)maps.
- Sorted sets (zsets) are collections of unique strings ordered by each string's associated score.
Redka also provides commands for key management, server/connection management, and transactions.
Installation and usage
Redka comes in two flavors:
- Standalone Redis-compatible server: installation, usage.
- Go module for in-process use: installation, usage.
You can also run an in-process Redka server as a lightweight alternative to Redis test containers, or as a small-scale production instance.
Storage
Redka can use either SQLite or PostgreSQL as its backend. It stores data in a relational database with a simple schema and provides views for better introspection.
Performance
Redka is not about raw performance. You can't beat a specialized data store like Redis with a general-purpose relational backend like SQLite. However, Redka can still handle tens of thousands of operations per second, which should be more than enough for many apps.
See the benchmarks for more details.
Contributing
Contributions are welcome. For anything other than bugfixes, please first open an issue to discuss what you want to change.
Make sure to add or update tests as needed.
Acknowledgements
Redka would not be possible without these great projects and their creators:
- Redis (Salvatore Sanfilippo). It's such an amazing idea to go beyond the get-set paradigm and provide a convenient API for more complex data structures.
- SQLite (D. Richard Hipp). The in-process database powering the world.
- Redcon (Josh Baker). A very clean and convenient implementation of a RESP server.
Logo font by Ek Type.
Support
Redka is mostly a one-man project, not backed by a VC fund or anything.
If you find Redka useful, please star it on GitHub and spread the word among your peers. It really helps to move the project forward.
If you use Redka for commercial purposes, consider purchasing support.
★ Subscribe to stay on top of new features.
Documentation
¶
Overview ¶
Package Redka implements Redis-like database backed by a relational database (SQLite or PostgreSQL). It provides an API to interact with data structures like keys, strings and hashes.
Typically, you open a database with Open and use the returned DB instance methods like DB.Key or DB.Str to access the data structures. You should only use one instance of DB throughout your program and close it with DB.Close when the program exits.
See usage examples in the documentation below and at these links:
Index ¶
- Constants
- Variables
- type DB
- func (db *DB) Close() error
- func (db *DB) Geo() *rgeo.DB
- func (db *DB) Hash() *rhash.DB
- func (db *DB) Key() *rkey.DB
- func (db *DB) List() *rlist.DB
- func (db *DB) Log() *slog.Logger
- func (db *DB) Set() *rset.DB
- func (db *DB) Str() *rstring.DB
- func (db *DB) Update(f func(tx *Tx) error) error
- func (db *DB) UpdateContext(ctx context.Context, f func(tx *Tx) error) error
- func (db *DB) View(f func(tx *Tx) error) error
- func (db *DB) ViewContext(ctx context.Context, f func(tx *Tx) error) error
- func (db *DB) ZSet() *rzset.DB
- type Key
- type Options
- type Tx
- type TypeID
- type Value
Constants ¶
const ( TypeAny = core.TypeAny TypeString = core.TypeString TypeList = core.TypeList TypeSet = core.TypeSet TypeHash = core.TypeHash TypeZSet = core.TypeZSet )
Key types.
Variables ¶
var ( ErrKeyType = core.ErrKeyType // key type mismatch ErrNotFound = core.ErrNotFound // key or element not found ErrValueType = core.ErrValueType // invalid value type )
Common errors returned by data structure methods.
Functions ¶
This section is empty.
Types ¶
type DB ¶
type DB struct {
// contains filtered or unexported fields
}
DB is a Redis-like repository backed by a relational database. Provides access to data structures like keys, strings, and hashes.
DB is safe for concurrent use by multiple goroutines as long as you use a single instance of DB throughout your program.
func Open ¶
Open opens a new or existing database at the given path. Creates the database schema if necessary.
The returned DB is safe for concurrent use by multiple goroutines as long as you use a single instance throughout your program. Typically, you only close the DB when the program exits.
The opts parameter is optional. If nil, uses default options.
func OpenDB ¶
OpenDB connects to an existing SQL database. Creates the database schema if necessary. The opts parameter is optional. If nil, uses default options.
func OpenReadDB ¶
OpenReadDB connects to an existing SQL database in read-only mode.
func (*DB) Hash ¶
Hash returns the hash repository. A hash (hashmap) is a field-value map associated with a key. Use the hash repository to work with individual hashmaps and their fields.
func (*DB) Key ¶
Key returns the key repository. A key is a unique identifier for a data structure (string, list, hash, etc.). Use the key repository to manage all keys regardless of their type.
func (*DB) List ¶
List returns the list repository. A list is a sequence of strings ordered by insertion order. Use the list repository to work with lists and their elements.
func (*DB) Set ¶
Set returns the set repository. A set is an unordered collection of unique strings. Use the set repository to work with individual sets and their elements, and to perform set operations.
func (*DB) Str ¶
Str returns the string repository. A string is a slice of bytes associated with a key. Use the string repository to work with individual strings.
func (*DB) UpdateContext ¶
UpdateContext executes a function within a writable transaction.
func (*DB) ViewContext ¶
ViewContext executes a function within a read-only transaction.
type Key ¶
Key represents a key data structure. Each key uniquely identifies a data structure stored in the database (e.g. a string, a list, or a hash). There can be only one data structure with a given key, regardless of type. For example, you can't have a string and a hash map with the same key.
type Options ¶
type Options struct {
// SQL driver name.
// If empty, uses "sqlite3".
DriverName string
// Options to set on the database connection.
// If nil, uses the engine-specific defaults.
Pragma map[string]string
// Timeout for database operations.
// If zero, uses the default timeout of 5 seconds.
Timeout time.Duration
// Logger for the database. If nil, uses a silent logger.
Logger *slog.Logger
// contains filtered or unexported fields
}
Options is the configuration for the database.
type Tx ¶
type Tx struct {
// contains filtered or unexported fields
}
Tx is a Redis-like database transaction. Same as DB, Tx provides access to data structures like keys, strings, and hashes. The difference is that you call Tx methods within a transaction managed by DB.Update or DB.View.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
core
Package core provides the core types used by other Redka packages.
|
Package core provides the core types used by other Redka packages. |
|
rhash
Package rhash is a database-backed hash repository.
|
Package rhash is a database-backed hash repository. |
|
rkey
Package rkey is a database-backed key repository.
|
Package rkey is a database-backed key repository. |
|
rlist
Package rlist is a database-backed list repository.
|
Package rlist is a database-backed list repository. |
|
rset
Package rset is a database-backed set repository.
|
Package rset is a database-backed set repository. |
|
rstring
Package rstring is a database-backed string repository.
|
Package rstring is a database-backed string repository. |
|
rzset
Package rzset is a database-backed sorted set repository.
|
Package rzset is a database-backed sorted set repository. |
|
sqlx
Package sqlx provides base types and helper functions to work with SQL databases.
|
Package sqlx provides base types and helper functions to work with SQL databases. |
|
testx
Package testx provides helper functions for testing.
|
Package testx provides helper functions for testing. |
|
pkg
|
|
|
Package redsrv implements a Redis-compatible (RESP) server.
|
Package redsrv implements a Redis-compatible (RESP) server. |
|
internal/command
Package command implements Redis-compatible commands for operations on data structures.
|
Package command implements Redis-compatible commands for operations on data structures. |
|
internal/parser
Package parser implements command arguments parsing.
|
Package parser implements command arguments parsing. |
|
internal/redis
Package redis implements basis for Redis-compatible commands in Redka.
|
Package redis implements basis for Redis-compatible commands in Redka. |