HLRDB

HLRDB is an opinionated, high-level, type-driven library for modeling Redis-backed database architecture.

This package provides an easy API for you to declare your data paths in Redis, but in doing so makes many decisions for you about how to serialize and deserialize values, construct identifiers, and define path names. If you want more control over these aspects, you may instead use the HLRDB Core package, which simply defines the commands and the abstract API without opining on these matters.

There is a simple demo project that shows how to get started.

Finally, make sure that your Eq instances always respect the induced equality via Store serialization, since obviously Redis commands will be comparing serialized values.

Minimal example

import Data.Store
import Database.Redis (checkedConnect,defaultConnectInfo,runRedis)
import HLRDB

newtype CommentId = CommentId Identifier deriving (Eq,Ord,Show,Store,IsIdentifier)
newtype Comment = Comment String deriving (Eq,Ord,Show,Store)

cidToComment :: RedisBasic CommentId (Maybe Comment)
cidToComment = declareBasic "canonical mapping from CommentId to Comment"

main :: IO ()
main = do
  -- connect to Redis
  rconn <- checkedConnect defaultConnectInfo

  cid :: CommentId <- genId

  c :: Maybe Comment <- runRedis rconn $ do
    -- create a comment
    set' cidToComment cid $ Comment "hi"
    -- read it back
    get cidToComment cid

  print c

Commands

The commands are located in the core package.

Identifiers

data Identifier

Use the following newtype pattern to declare your identifiers

newtype CommentId = CommentId Identifier deriving (Eq,Ord,Show,Store,IsIdentifier)

You may generate a new random identifier using genId

example :: IO CommentId
example = genId

Instances

Eq Identifier

Methods

(==) :: Identifier -> Identifier -> Bool

(/=) :: Identifier -> Identifier -> Bool

Ord Identifier

Methods

compare :: Identifier -> Identifier -> Ordering

(<) :: Identifier -> Identifier -> Bool

(<=) :: Identifier -> Identifier -> Bool

(>) :: Identifier -> Identifier -> Bool

(>=) :: Identifier -> Identifier -> Bool

max :: Identifier -> Identifier -> Identifier

min :: Identifier -> Identifier -> Identifier

Show Identifier

Methods

showsPrec :: Int -> Identifier -> ShowS

show :: Identifier -> String

showList :: [Identifier] -> ShowS

Generic Identifier

Associated Types

type Rep Identifier :: * -> *

Methods

from :: Identifier -> Rep Identifier x

to :: Rep Identifier x -> Identifier

Hashable Identifier

Methods

hashWithSalt :: Int -> Identifier -> Int

hash :: Identifier -> Int

Store Identifier

Methods

size :: Size Identifier

poke :: Identifier -> Poke ()

peek :: Peek Identifier

IsIdentifier Identifier

Methods

toIdentifier :: Identifier -> Identifier

fromIdentifier :: Identifier -> Identifier

type Rep Identifier

type Rep Identifier = D1 * (MetaData "Identifier" "HLRDB" "hlrdb-0.2.0.0-BEf0E3DCqDI5sW6g10dEQh" True) (C1 * (MetaCons "Identifier" PrefixI False) (S1 * (MetaSel (Nothing Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 * (Int32, Word32, Word16, Word8))))

class IsIdentifier a where

IsIdentifier means that a is isomorphic to Identifier, usually via newtype. This enables to use genId :: IsIdentifier a => IO a, declared below. It is required that not only is it isomorphic; it must respect the Store instance as well (you get this for free with a newtype anyway).

Minimal complete definition

toIdentifier, fromIdentifier

Methods

toIdentifier :: a -> Identifier

fromIdentifier :: Identifier -> a

Instances

IsIdentifier Identifier

Methods

toIdentifier :: Identifier -> Identifier

fromIdentifier :: Identifier -> Identifier

genId :: IsIdentifier a => IO a

Generate a new identifier using the current time as the timestamp

genId' :: IsIdentifier a => UTCTime -> IO a

Generate a new identifier for the given timestamp

identifierTimestamp :: IsIdentifier a => a -> UTCTime

Extract the timestamp from an identifier

Indexed path declaration

declareBasic :: (IsIdentifier i, Store v) => PathName -> RedisBasic i (Maybe v)

Declare your paths by choosing the declaration for the Redis structure you want to use. You must provide a unique description, which not only serves to document your architecture, but the hash of which is used to distinguish between otherwise identical paths of the same type.

cidToComment :: RedisBasic CommentId (Maybe Comment)
cidToComment = declareBasic "canonical mapping from CommentId to Comment"

declareIntegral :: (IsIdentifier i, Integral b) => PathName -> RedisIntegral i b

Standard key-value store, but backed by a primitive integer in Redis, enabling extra commands like incr

declareBasicZero :: (IsIdentifier i, Store v) => PathName -> v -> RedisBasic i v

Allows defining your own "zero" value. An example might be RoseTree, where a non-existant value in Redis can be mapped to a sensible empty value in Haskell.

declareList :: (IsIdentifier i, Store v) => PathName -> Maybe TrimScheme -> RedisList i v

Standard Redis list, supporting prepends, appends, and range access. If a TrimScheme is provided, operations will automatically trim the list to the specified length.

declareSet :: (IsIdentifier i, Store v) => PathName -> RedisSet i v

A set in Redis.

declareHSet :: (IsIdentifier i, Store s, Store v) => PathName -> RedisHSet i s v

A sub-hash table, using the sub-index type s. s here is only required to be Storable rather than IsIdentifier, but in practice you'll probably use identifiers for s, too.

declareSSet :: (IsIdentifier i, Store v) => PathName -> Maybe TrimScheme -> RedisSSet i v

A sorted set in Redis. You may optionally provide a trim scheme, which will automatically manage the sorted set's size for you.

Global path declaration

declareGlobalBasic :: Store v => PathName -> RedisBasic () (Maybe v)

A global version of declareBasic

declareGlobalIntegral :: Integral b => PathName -> RedisIntegral () b

A global version of declareIntegral

declareGlobalBasicZero :: Store v => PathName -> v -> RedisBasic () v

A global version of declareZero

declareGlobalList :: Store v => PathName -> Maybe TrimScheme -> RedisList () v

A global version of declareList

declareGlobalSet :: Store v => PathName -> RedisSet () v

A global version of declareSet

declareGlobalHSet :: (Store s, Store v) => PathName -> RedisHSet () s v

A global version of declareHSet

declareGlobalSSet :: Store v => PathName -> Maybe TrimScheme -> RedisSSet () v

A global version of declareSSet

Other commands

encodePath :: IsIdentifier a => PathName -> a -> ByteString

If for some reason you need the actual, raw key name (which you may use with the low-level commands in hedis), you may obtain it via encodePath.

foldPath :: (MonadRedis m, IsIdentifier i, Store v) => RedisStructure s i v -> (a -> i -> m a) -> a -> m a

Note that despite the pretty type signature, the actual implementation of foldPath in Redis is slow (it uses the global scan command, so its run time is proportional to the number of total keys in Redis, *not* the number of keys specifically related to the given path). You should only use foldPath for administrative tasks, and never for any public API.

class Store a

The Store typeclass provides efficient serialization and deserialization to raw pointer addresses.

The peek and poke methods should be defined such that decodeEx (encode x) == x .

Instances

Store Identifier

Methods

size :: Size Identifier

poke :: Identifier -> Poke ()

peek :: Peek Identifier

KnownNat n => Store (StaticSize n ByteString)

Methods

size :: Size (StaticSize n ByteString)

poke :: StaticSize n ByteString -> Poke ()

peek :: Peek (StaticSize n ByteString)

module HLRDB.Core