Documentation
¶
Overview ¶
Package Redka implements Redis-like database backed by SQLite. 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.
Index ¶
- Variables
- type DB
- func (db *DB) Close() error
- func (db *DB) Hash() *rhash.DB
- func (db *DB) Key() *rkey.DB
- func (db *DB) List() *rlist.DB
- 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 Value
Examples ¶
Constants ¶
This section is empty.
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 ¶
DB is a Redis-like database backed by SQLite. 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.
Example ¶
package main import ( "github.com/nalgeon/redka" ) func main() { db, err := redka.Open("file:/data.db?vfs=memdb", nil) if err != nil { panic(err) } defer db.Close() // ... }
Output:
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 (*DB) Close ¶
Close closes the database. It's safe for concurrent use by multiple goroutines.
Example ¶
package main import ( "github.com/nalgeon/redka" ) func main() { db, err := redka.Open("file:/data.db?vfs=memdb", nil) if err != nil { panic(err) } defer db.Close() // ... }
Output:
func (*DB) Hash ¶ added in v0.2.0
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.
Example ¶
package main import ( "fmt" "github.com/nalgeon/redka" ) func main() { // Error handling is omitted for brevity. // In real code, always check for errors. db, _ := redka.Open("file:/data.db?vfs=memdb", nil) defer db.Close() ok, err := db.Hash().Set("user:1", "name", "alice") fmt.Printf("ok=%v, err=%v\n", ok, err) ok, err = db.Hash().Set("user:1", "age", 25) fmt.Printf("ok=%v, err=%v\n", ok, err) name, err := db.Hash().Get("user:1", "name") fmt.Printf("name=%v, err=%v\n", name, err) age, err := db.Hash().Get("user:1", "age") fmt.Printf("age=%v, err=%v\n", age, err) }
Output: ok=true, err=<nil> ok=true, err=<nil> name=alice, err=<nil> age=25, err=<nil>
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.
Example ¶
package main import ( "fmt" "time" "github.com/nalgeon/redka" ) func main() { // Error handling is omitted for brevity. // In real code, always check for errors. db, _ := redka.Open("file:/data.db?vfs=memdb", nil) defer db.Close() _ = db.Str().SetExpires("name", "alice", 60*time.Second) key, _ := db.Key().Get("name") fmt.Printf("key=%v, type=%v, version=%v, exists=%v\n", key.Key, key.TypeName(), key.Version, key.Exists()) key, _ = db.Key().Get("nonexistent") fmt.Printf("key=%v, type=%v, version=%v, exists=%v\n", key.Key, key.TypeName(), key.Version, key.Exists()) }
Output: key=name, type=string, version=1, exists=true key=, type=unknown, version=0, exists=false
func (*DB) List ¶ added in v0.4.0
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 ¶ added in v0.5.0
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.
Example ¶
package main import ( "fmt" "github.com/nalgeon/redka" ) func main() { // Error handling is omitted for brevity. // In real code, always check for errors. db, _ := redka.Open("file:/data.db?vfs=memdb", nil) defer db.Close() _ = db.Str().Set("name", "alice") name, _ := db.Str().Get("name") fmt.Printf("name=%v\n", name) name, _ = db.Str().Get("nonexistent") fmt.Printf("name=%v\n", name) }
Output: name=alice name=
func (*DB) Update ¶ added in v0.2.0
Update executes a function within a writable transaction. See the tx example for details.
Example ¶
package main import ( "fmt" "github.com/nalgeon/redka" ) func main() { db, err := redka.Open("file:/data.db?vfs=memdb", nil) if err != nil { panic(err) } defer db.Close() updCount := 0 err = db.Update(func(tx *redka.Tx) error { err := tx.Str().Set("name", "alice") if err != nil { return err } updCount++ err = tx.Str().Set("age", 25) if err != nil { return err } updCount++ return nil }) fmt.Printf("updated: count=%v, err=%v\n", updCount, err) }
Output: updated: count=2, err=<nil>
func (*DB) UpdateContext ¶ added in v0.2.0
UpdateContext executes a function within a writable transaction. See the tx example for details.
func (*DB) View ¶ added in v0.2.0
View executes a function within a read-only transaction. See the tx example for details.
Example ¶
package main import ( "fmt" "github.com/nalgeon/redka" ) func main() { // Error handling is omitted for brevity. // In real code, always check for errors. db, _ := redka.Open("file:/data.db?vfs=memdb", nil) defer db.Close() _ = db.Str().SetMany(map[string]any{ "name": "alice", "age": 25, }) type person struct { name string age int } var p person err := db.View(func(tx *redka.Tx) error { name, err := tx.Str().Get("name") if err != nil { return err } p.name = name.String() age, err := tx.Str().Get("age") if err != nil { return err } // Only use MustInt() if you are sure that // the key exists and is an integer. p.age = age.MustInt() return nil }) fmt.Printf("person=%+v, err=%v\n", p, err) }
Output: person={name:alice age:25}, err=<nil>
func (*DB) ViewContext ¶ added in v0.2.0
ViewContext executes a function within a read-only transaction. See the tx example for details.
func (*DB) ZSet ¶ added in v0.3.0
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.
Example ¶
package main import ( "fmt" "github.com/nalgeon/redka" ) func main() { // Error handling is omitted for brevity. // In real code, always check for errors. db, _ := redka.Open("file:/data.db?vfs=memdb", nil) defer db.Close() ok, err := db.ZSet().Add("race", "alice", 11) fmt.Printf("ok=%v, err=%v\n", ok, err) ok, err = db.ZSet().Add("race", "bob", 22) fmt.Printf("ok=%v, err=%v\n", ok, err) rank, score, err := db.ZSet().GetRank("race", "alice") fmt.Printf("alice: rank=%v, score=%v, err=%v\n", rank, score, err) rank, score, err = db.ZSet().GetRank("race", "bob") fmt.Printf("bob: rank=%v, score=%v, err=%v\n", rank, score, err) }
Output: ok=true, err=<nil> ok=true, err=<nil> alice: rank=0, score=11, err=<nil> bob: rank=1, score=22, err=<nil>
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 ¶ added in v0.2.0
type Options struct { // SQL driver name. // If empty, uses "sqlite3". DriverName string // SQL pragmas to set on the database connection. // If nil, uses the default pragmas: // - journal_mode=wal // - synchronous=normal // - temp_store=memory // - mmap_size=268435456 // - foreign_keys=on Pragma map[string]string // Logger for the database. If nil, uses a silent logger. Logger *slog.Logger }
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.
See the tx example for details.
Directories
¶
Path | Synopsis |
---|---|
cmd
|
|
cli
Redka CLI.
|
Redka CLI. |
redka
Redka server.
|
Redka server. |
example
module
|
|
internal
|
|
command
Package command implements Redis-compatible commands for operations on data structures.
|
Package command implements Redis-compatible commands for operations on data structures. |
core
Package core provides the core types used by other Redka packages.
|
Package core provides the core types used by other Redka packages. |
parser
Package parser implements command arguments parsing.
|
Package parser implements command arguments parsing. |
redis
Package redis implements basis for Redis-compatible commands in Redka.
|
Package redis implements basis for Redis-compatible commands in Redka. |
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. |
server
Package server implements a Redis-compatible (RESP) server.
|
Package server implements a Redis-compatible (RESP) server. |
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. |