redka

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:

• mattn - CGO SQLite driver.
• ncruces - Pure Go SQLite driver (WASM).
• modernc - Pure Go SQLite driver (libc port).
• postgres - Postgres driver.
• tx - Using transactions.

Index

• Constants
• Variables
• type DB
  • func Open(path string, opts *Options) (*DB, error)
  • func OpenDB(rw *sql.DB, ro *sql.DB, opts *Options) (*DB, error)
  • func OpenRead(path string, opts *Options) (*DB, error)
  • func OpenReadDB(db *sql.DB, opts *Options) (*DB, error)
  • 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
  • func (tx *Tx) Hash() *rhash.Tx
  • func (tx *Tx) Key() *rkey.Tx
  • func (tx *Tx) List() *rlist.Tx
  • func (tx *Tx) Set() *rset.Tx
  • func (tx *Tx) Str() *rstring.Tx
  • func (tx *Tx) ZSet() *rzset.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.

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

func Open(path string, opts *Options) (*DB, error)

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

func OpenDB(rw *sql.DB, ro *sql.DB, opts *Options) (*DB, error)

OpenDB connects to an existing SQL database. Creates the database schema if necessary. The opts parameter is optional. If nil, uses default options.

func OpenRead

func OpenRead(path string, opts *Options) (*DB, error)

OpenRead opens an existing database at the given path in read-only mode.

func OpenReadDB

func OpenReadDB(db *sql.DB, opts *Options) (*DB, error)

OpenReadDB connects to an existing SQL database in read-only mode.

func (*DB) Close

func (db *DB) Close() error

Close closes the database. It's safe for concurrent use by multiple goroutines.

func (*DB) Geo

func (db *DB) Geo() *rgeo.DB

func (*DB) Hash

func (db *DB) Hash() *rhash.DB

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

func (db *DB) Key() *rkey.DB

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

func (db *DB) List() *rlist.DB

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) Log

func (db *DB) Log() *slog.Logger

Log returns the logger for the database.

func (*DB) Set

func (db *DB) Set() *rset.DB

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

func (db *DB) Str() *rstring.DB

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) Update

func (db *DB) Update(f func(tx *Tx) error) error

Update executes a function within a writable transaction.

func (*DB) UpdateContext

func (db *DB) UpdateContext(ctx context.Context, f func(tx *Tx) error) error

UpdateContext executes a function within a writable transaction.

func (*DB) View

func (db *DB) View(f func(tx *Tx) error) error

View executes a function within a read-only transaction.

func (*DB) ViewContext

func (db *DB) ViewContext(ctx context.Context, f func(tx *Tx) error) error

ViewContext executes a function within a read-only transaction.

func (*DB) ZSet

func (db *DB) ZSet() *rzset.DB

ZSet returns the sorted set repository. A sorted set (zset) is a like a set, but each element has a score, and elements are ordered by score from low to high. Use the sorted set repository to work with individual sets and their elements, and to perform set operations.

type Key

type Key = core.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.

func (*Tx) Hash

func (tx *Tx) Hash() *rhash.Tx

Hash returns the hash transaction.

func (*Tx) Key

func (tx *Tx) Key() *rkey.Tx

Keys returns the key transaction.

func (*Tx) List

func (tx *Tx) List() *rlist.Tx

List returns the list transaction.

func (*Tx) Set

func (tx *Tx) Set() *rset.Tx

Set returns the set transaction.

func (*Tx) Str

func (tx *Tx) Str() *rstring.Tx

Str returns the string transaction.

func (*Tx) ZSet

func (tx *Tx) ZSet() *rzset.Tx

ZSet returns the sorted set transaction.

type TypeID

type TypeID = core.TypeID

A TypeID identifies the type of the key and thus the data structure of the value with that key.

type Value

type Value = core.Value

Value represents a value stored in a database (a byte slice). It can be converted to other scalar types.