Database.RethinkDB.Driver

The core of the haskell client library for RethinkDB

Network

data RethinkDBHandle

A connection to the database server

Constructors

RethinkDBHandle

Fields

rdbHandle :: Handle

rdbToken :: IORef Int64

The next token to use

rdbDatabase :: Database

When no database is specified, this one will be used

openConnection :: HostName -> Maybe PortID -> Maybe String -> IO RethinkDBHandle

Create a new connection to the database server

Example: connect using the default port (28015) and specifying the default database for all queries.

>>> h <- openConnection "localhost" Nothing (Just "test")

use :: RethinkDBHandle -> Database -> RethinkDBHandle

Set the default connection

The new handle is an alias for the old one. Calling closeConnection on either one will close both.

>>> let h' = h `use` (db "players")

closeConnection :: RethinkDBHandle -> IO ()

Close an open connection

>>> closeConnection h

recvAll :: RethinkDBHandle -> Int -> IO ByteString

Receive a fixed amoutn of data

sendAll :: RethinkDBHandle -> ByteString -> IO ()

Send a bytestring

getNewToken :: RethinkDBHandle -> IO Int64

Get a request token and increment the token counter

data ErrorCode

Constructors

ErrorBrokenClient

ErrorBadQuery

ErrorRuntime

ErrorNetwork

Instances

Show ErrorCode

data SuccessCode

Constructors

SuccessEmpty

SuccessJson

SuccessPartial

SuccessStream

Instances

Show SuccessCode

data Response

The raw response to a query

Constructors

ErrorResponse

Fields

errorCode :: ErrorCode

errorMessage :: String

errorBacktrace :: [String]

SuccessResponse

Fields

successCode :: SuccessCode

successString :: [ByteString]

Instances

Show Response

convertResponse :: Either String Response -> Response

showBacktrace :: [String] -> String

runQLQuery :: RethinkDBHandle -> Query -> IO Response

Execute a raw protobuffer query and return the raw response

CRUD

data Database

A database, referenced by name

Constructors

Database

Fields

databaseName :: String

Instances

Eq Database

Ord Database

Show Database

db :: String -> Database

Create a Database reference

dbCreate :: String -> Query False Database

Create a database on the server

dbDrop :: Database -> Query False ()

Drop a database

dbList :: Query False [Database]

List the databases on the server

>>> run h $ dbList
[test, dev, prod]

data TableCreateOptions

Options used to create a table

Constructors

TableCreateOptions

Fields

tableDataCenter :: Maybe String

tableCacheSize :: Maybe Int64

Instances

Default TableCreateOptions

data Table

A table description

Constructors

Table

Fields

tableDatabase :: Maybe Database

when Nothing, use the rdbDatabase

tableName :: String

_tablePrimaryAttr :: Maybe String

when Nothing, id is used

Instances

Eq Table

Ord Table

Show Table

ToValue Table

ToExpr Table

ToStream Table

ToBuildQuery Table

(ToBuildQuery Table, FromJSON a) => ToQuery Table [(Document, a)]

tablePrimaryAttr :: Table -> String

defaultPrimaryAttr :: Utf8

id

table :: String -> Table

Create a simple table refence with no associated database or primary key

>>> table "music"

Another way to create table references is to use the Table constructor:

>>> Table (Just "mydatabase") "music" (Just "tuneid")

tableCreate :: Table -> TableCreateOptions -> Query False Table

Create a table on the server

def can be imported from Data.Default

>>> t <- run h $ tableCreate (table "fruits") def

tableDrop :: Table -> Query False ()

Drop a table

tableList :: Database -> Query False [Table]

List the tables in a database

uTableKey :: Table -> Utf8

Get the primary key of the table as a Utf8, or id if there is none

data Document

A reference to a document

Constructors

Document

Fields

documentTable :: Table

documentKey :: Value

Instances

Eq Document

Show Document

ToValue Document

ToExpr Document

ToStream Document

ToBuildQuery Document

(ToBuildQuery Document, FromJSON a) => ToQuery Document a

(ToBuildQuery Table, FromJSON a) => ToQuery Table [(Document, a)]

(ToBuildQuery (Expr (StreamType True v)), ExtractValue ValueTypeKind v a) => ToQuery (Expr (StreamType True v)) [(Document, a)]

get :: (ToExpr e, ExprType e ~ StreamType True ObjectType, ToValue k) => e -> k -> ObjectExpr

Get a document by primary key

insert_or_upsert :: (ToValue a, ToValueType (ExprType a) ~ ObjectType) => Table -> [a] -> Bool -> WriteQuery [Document]

insert :: (ToValue a, ToValueType (ExprType a) ~ ObjectType) => Table -> a -> WriteQuery Document

Insert a document into a table

>>> d <- run h $ insert t (object ["name" .= "banana", "color" .= "red"])

insertMany :: (ToValue a, ToValueType (ExprType a) ~ ObjectType) => Table -> [a] -> WriteQuery [Document]

Insert many documents into a table

upsert :: (ToValue a, ToValueType (ExprType a) ~ ObjectType) => Table -> a -> WriteQuery Document

Insert a document into a table, overwriting a document with the same primary key if one exists.

upsertMany :: (ToValue a, ToValueType (ExprType a) ~ ObjectType) => Table -> [a] -> WriteQuery [Document]

Insert many documents into a table, overwriting any existing documents with the same primary key.

update :: (ToExpr sel, ExprType sel ~ StreamType True out, ToMapping map, MappingFrom map ~ out, MappingTo map ~ ObjectType) => sel -> map -> WriteQuery ()

Update a table

>>> t <- run h $ tableCreate (table "example") def
>>> run h $ insertMany t [object ["a" .= 1, "b" .= 11], object ["a" .= 2, "b" .= 12]]
>>> run h $ update t (object ["b" .= 20])
>>> run h $ t

replace :: (ToExpr sel, ExprIsView sel ~ True, ToJSON a) => sel -> a -> WriteQuery ()

Replace documents in a table

delete :: (ToExpr sel, ExprIsView sel ~ True) => sel -> WriteQuery ()

Delete one or more documents from a table

Queries

data Query b a where

A query returning a

Constructors

Query :: QueryM Query -> ([Value] -> Either String a) -> Query False a

Fields

_queryBuild :: QueryM Query

_queryExtract :: [Value] -> Either String a

ViewQuery :: QueryM (Table, Query) -> ([(Document, Value)] -> Either String a) -> Query True a

Fields

_viewQueryBuild :: QueryM (Table, Query)

_viewQueryExtract :: [(Document, Value)] -> Either String a

Instances

Functor (Query w)

ToBuildQuery (Query w a)

ToBuildQuery (Query w a) => ToQuery (Query w a) a

data WriteQuery a

Constructors

WriteQuery

Fields

writeQueryBuild :: QueryM WriteQuery

writeQueryExtract :: [Value] -> Either String a

Instances

Functor WriteQuery

ToBuildQuery (WriteQuery a)

ToBuildQuery (WriteQuery a) => ToQuery (WriteQuery a) a

queryBuild :: Query w a -> QueryM (MaybeView w, Query)

queryExtract :: Query w a -> MaybeView w -> [Value] -> Either String a

type family If p a b :: k

class ToBuildQuery a where

Convert things like tables and documents into queries

Associated Types

type BuildViewQuery a :: Bool

Methods

buildQuery :: a -> ([If (BuildViewQuery a) (Document, Value) Value] -> Either String b) -> Query (BuildViewQuery a) b

Instances

ToBuildQuery Document

ToBuildQuery Table

ToBuildQuery (Expr (ValueType v))

ToBuildQuery (Expr (StreamType False v))

ToBuildQuery (Expr (StreamType True v))

ToBuildQuery (WriteQuery a)

ToBuildQuery (Query w a)

class ToBuildQuery a => ToQuery a b | a -> b where

Methods

toQuery :: a -> Query (BuildViewQuery a) b

Instances

(ToBuildQuery Document, FromJSON a) => ToQuery Document a

(ToBuildQuery Table, FromJSON a) => ToQuery Table [(Document, a)]

(ToBuildQuery (Expr (ValueType v)), ExtractValue ValueTypeKind v a) => ToQuery (Expr (ValueType v)) a

ToBuildQuery (WriteQuery a) => ToQuery (WriteQuery a) a

(ToBuildQuery (Expr (StreamType False v)), ExtractValue ValueTypeKind v a) => ToQuery (Expr (StreamType False v)) [a]

(ToBuildQuery (Expr (StreamType True v)), ExtractValue ValueTypeKind v a) => ToQuery (Expr (StreamType True v)) [(Document, a)]

ToBuildQuery (Query w a) => ToQuery (Query w a) a

mapMSnd :: Monad m => (a -> m b) -> [(c, a)] -> m [(c, b)]

data Proxy t

Constructors

Proxy

exprToQLQuery :: Expr t -> QueryM (MaybeView (ExprTypeIsView t), Query)

exprViewQuery :: ExprTypeIsView t ~ True => ([Value] -> Either String [a]) -> Expr t -> Query True [(Document, a)]

extractListOf :: ExtractValue t a => Proxy t -> [Value] -> Maybe [a]

class ExtractValue t v | t -> v where

Methods

extractValue :: Proxy t -> Value -> Maybe v

Instances

FromJSON a => ExtractValue ValueTypeKind OtherValueType a

ExtractValue ValueTypeKind NoneType ()

(IsString a, FromJSON a) => ExtractValue ValueTypeKind StringType a

FromJSON a => ExtractValue ValueTypeKind ArrayType a

FromJSON a => ExtractValue ValueTypeKind ObjectType a

ExtractValue ValueTypeKind BoolType Bool

(Num a, FromJSON a) => ExtractValue ValueTypeKind NumberType a

run :: ToQuery a v => RethinkDBHandle -> a -> IO v

Run a query on the connection

The return value depends on the type of the second argument.

When the return value is polymorphic, type annotations may be required.

>>> run h $ table "fruits" :: IO [(Document, Value)]

runEither :: ToQuery a v => RethinkDBHandle -> a -> IO (Either String v)

Run a query on the connection, returning (Left message) on error

addDoc :: Table -> Value -> Either String (Document, Value)

runMaybe :: ToQuery a v => RethinkDBHandle -> a -> IO (Maybe v)

Run a query on the connection, returning Nothing on error

runRaw :: (ToBuildQuery q, JSONQuery (BuildViewQuery q)) => RethinkDBHandle -> q -> IO Response

Run a query on the connection and return the raw response

runJSON :: (JSONQuery (BuildViewQuery q), ToBuildQuery q) => RethinkDBHandle -> q -> IO [Value]

Run a query on the connection and return the resulting JSON value

class JSONQuery b where

Methods

jsonQuery :: (forall a. ([If b (Document, Value) Value] -> Either String a) -> Query b a) -> Query b [Value]

Instances

JSONQuery False

JSONQuery True

data Results a

Constructors

Results

Fields

resultsHandle :: IORef (Maybe (RethinkDBHandle, Int64))

resultsSeq :: IORef (Seq a)

_resultsError :: IORef (Maybe String)

resultsQueryView :: QueryViewPair [a]

data QueryViewPair a where

Constructors

QueryViewPair :: Query w a -> MaybeView w -> QueryViewPair a

runBatch :: ToQuery q [a] => RethinkDBHandle -> q -> IO (Results a)

Run a query on the connection and a return a lazy result list

>>> res <- runBatch h <- (arrayToStream [1,2,3] :: NumberStream)
>>> next res
Just 1
>>> collect res
[2,3]

queryExtractResponse :: Query w [a] -> MaybeView w -> Response -> RethinkDBHandle -> Int64 -> (Maybe (RethinkDBHandle, Int64), Seq a, Maybe String)

next :: Results a -> IO (Maybe a)

Read the next value from a lazy query. Fetch it from the server if needed.

collect :: Results a -> IO [a]

Return all the results of a lazy query.

resultsError :: Results a -> IO (Maybe String)

Get the last error from a lazy query.

If both next and resultsError return Nothing, then all results have been fetched without error.

Expressions

type family ExprTypeIsView expr :: Bool

Can the Expr be written to? (updated or deleted)

type ExprIsView e = ExprTypeIsView (ExprType e)

type family ExprTypeNoView t :: ExprTypeKind

type family ExprValueType expr :: ValueTypeKind

The type of the value of an Expr

type family ExprTypeStreamType t :: ValueTypeKind

The type of the stream of an Expr

data Expr t where

An RQL expression

Constructors

Expr :: QueryM (MaybeView (ExprIsView (Expr t)), Term) -> Expr t

SpotExpr :: Document -> Expr (StreamType True ObjectType)

Instances

Fractional (Expr (ValueType NumberType))

Num (Expr (ValueType NumberType))

ToValue (Expr (ValueType t))

ToValue (Expr (StreamType w t))

ToExpr (Expr t)

ToMapping (Expr (ValueType t))

ToStream (Expr (ValueType ArrayType))

ToExpr (Expr (StreamType w t)) => ToStream (Expr (StreamType w t))

ToBuildQuery (Expr (ValueType v))

ToBuildQuery (Expr (StreamType False v))

ToBuildQuery (Expr (StreamType True v))

(ToBuildQuery (Expr (ValueType v)), ExtractValue ValueTypeKind v a) => ToQuery (Expr (ValueType v)) a

(ToBuildQuery (Expr (StreamType False v)), ExtractValue ValueTypeKind v a) => ToQuery (Expr (StreamType False v)) [a]

(ToBuildQuery (Expr (StreamType True v)), ExtractValue ValueTypeKind v a) => ToQuery (Expr (StreamType True v)) [(Document, a)]

mkExpr :: ExprIsView (Expr t) ~ False => QueryM Term -> Expr t

mkView :: ExprIsView (Expr t) ~ True => Table -> QueryM Term -> Expr t

viewKeyAttr :: MaybeView b -> Utf8

viewTable :: MaybeView True -> Table

data MaybeView w where

Constructors

NoView :: MaybeView False

ViewOf :: Table -> MaybeView True

class ToExpr o where

Convert something into an Expr

Associated Types

type ExprType o :: ExprTypeKind

Methods

toExpr :: o -> Expr (ExprType o)

Instances

ToExpr Char

ToExpr Double

ToExpr Int

ToExpr Integer

ToExpr ()

ToExpr Text

ToExpr Obj

ToExpr Document

ToExpr Table

ToExpr a => ToExpr [a]

ToExpr (Expr t)

type family ToValueType t :: ValueTypeKind

The result type of toValue

class ToValue e where

Convert something into a value Expr

Methods

toValue :: e -> Expr (ValueType (ToValueType (ExprType e)))

Instances

ToValue Double

ToValue Int

ToValue Integer

ToValue ()

ToValue Text

ToValue Obj

ToValue Document

ToValue Table

ToExpr a => ToValue [a]

ToValue (Expr (ValueType t))

ToValue (Expr (StreamType w t))

type family FromMaybe a m :: k

type HasToStreamValueOf a b = FromMaybe a (ToStreamValue b) ~ a

type ToStreamValue e = ToStreamTypeValue (ExprType e)

type family ToStreamTypeValue t :: Maybe ValueTypeKind

class ToExpr e => ToStream e where

Methods

toStream :: e -> Expr (StreamType (ExprIsView e) (FromMaybe a (ToStreamValue e)))

Instances

ToStream Document

ToStream Table

(ToExpr [a], ToExpr a) => ToStream [a]

ToStream (Expr (ValueType ArrayType))

ToExpr (Expr (StreamType w t)) => ToStream (Expr (StreamType w t))

str :: String -> Text

type HasValueType a v = (ToValue a, ToValueType (ExprType a) ~ v)

Aliases for type constraints on expressions

type HaveValueType a b v = (HasValueType a v, HasValueType b v)

type NumberExpr = Expr (ValueType NumberType)

Simple aliases for different Expr types

type BoolExpr = Expr (ValueType BoolType)

type ObjectExpr = Expr (ValueType ObjectType)

type ArrayExpr = Expr (ValueType ArrayType)

type StringExpr = Expr (ValueType StringType)

type ValueExpr t = Expr (ValueType t)

type NumberStream = Expr (StreamType False NumberType)

type BoolStream = Expr (StreamType False BoolType)

type ArrayStream = Expr (StreamType False ArrayType)

type StringStream = Expr (StreamType False StringType)

type ObjectStream = Expr (StreamType False ObjectType)

type Selection = Expr (StreamType True ObjectType)

class CanCompare a

What values can be compared with eq, ne, lt, gt, le and ge

Instances

CanCompare StringType

CanCompare NumberType

class Sequence e

A sequence is either a stream or an array

Associated Types

type SequenceType e t :: Constraint

Instances

~ ValueTypeKind a ArrayType => Sequence (ValueType a)

Sequence (StreamType w t)

data Obj

A list of String/Expr pairs

Constructors

Obj [Attribute]

Instances

ToValue Obj

ToExpr Obj

ToMapping Obj

data Attribute

Constructors

forall e . ToValue e => String := e

obj :: [Attribute] -> Obj

Build an Obj

streamToArray :: (ToExpr e, ExprType e ~ StreamType w t) => e -> Expr (ValueType ArrayType)

Convert a stream into an array

arrayToStream :: (ToExpr e, ExprType e ~ ValueType ArrayType) => e -> Expr (StreamType False t)

Convert an array into a stream

Mappings

data Mapping from to

A mapping is a like single-parameter function

Constructors

Mapping (QueryM Mapping)

class ToMapping map where

Convert objects into mappings

Associated Types

type MappingFrom map :: ValueTypeKind

type MappingTo map :: ValueTypeKind

Methods

toMapping :: map -> Mapping (MappingFrom map) (MappingTo map)

Instances

ToMapping Value

ToMapping Obj

ToMapping (Expr (ValueType t))

(ToValue b, ~ * a (Expr (ValueType t))) => ToMapping (a -> b)

QueryM Monad

data QuerySettings

Constructors

QuerySettings

Fields

_queryToken :: Int64

_queryDB :: Database

_queryVars :: [String]

_queryUseOutdated :: Bool

Instances

Default QuerySettings

type QueryM = State QuerySettings

runQueryM :: QueryM a -> QuerySettings -> (a, QuerySettings)

initialVars :: [String]

getToken :: QueryM Int64

activeDB :: QueryM Database

newVar :: QueryM String

setUseOutdated :: ToExpr e => Bool -> e -> Expr (ExprType e)

Utilities

mappingToPredicate :: Mapping -> Predicate

Convert a protobuf Mapping into a Predicate

tableToTerm :: Table -> QueryM Term

Convert a table to a raw protobuf term

mapping :: ToMapping m => m -> QueryM Mapping

Convert into a raw protobuf mapping

expr :: ToExpr e => e -> QueryM Term

Convert an Expr to a term

exprV :: ToExpr e => e -> QueryM (MaybeView (ExprIsView e), Term)

stream :: ToStream a => a -> QueryM Term

Convert a stream to a term

value :: ToValue a => a -> QueryM Term

Convert a value to a term

toJsonTerm :: ToJSON a => a -> Term

build a raw protobuf Term

(.?) :: FromJSON a => Value -> String -> Maybe a

Test if a field is present in a json Value and return it

whenSuccess :: FromJSON a => String -> (a -> Either String b) -> [Value] -> Either String b

Helper function to handle responses to a query

whenSuccess_ :: b -> [Value] -> Either String b

same as whenSuccess, but ignore the response when there is no error

decodeAny :: FromJSON a => ByteString -> Maybe a

Like aeson's decode, but but works on numbers and strings, not only objects and arrays

convert :: FromJSON a => Value -> Maybe a

Convert a JSON Value into another type

metaQuery :: QueryM MetaQuery -> QueryM Query

Extract the error message from a Response if there is an error | Help build meta queries

packUInt :: Int -> ByteString

Convert an int to a 4-byte bytestring

unpackUInt :: ByteString -> Int

Convert a 4-bte byestring to an int

op :: BuiltinType -> Builtin

apply :: Builtin -> [QueryM Term] -> QueryM Term

rapply :: [QueryM Term] -> Builtin -> QueryM Term

simpleOp :: ExprIsView (Expr t) ~ False => BuiltinType -> [QueryM Term] -> Expr t

withView :: MaybeView b -> QueryM Term -> QueryM (MaybeView b, Term)

primaryAttr :: (ToExpr e, ExprTypeIsView (ExprType e) ~ True) => e -> String -> Expr (ExprType e)

comparison :: ExprTypeIsView t ~ False => Comparison -> [QueryM Term] -> Expr t

tableRef :: Table -> QueryM TableRef

Build a protobuf TableRef object

extractTerm :: ToExpr e => e -> Term

dumpExpr :: ToExpr e => e -> String

dumpTermPart :: Data a => String -> a -> String