Safe Haskell	None
Language	Haskell98

Database.Cassandra.CQL

Contents

Initialization
Cassandra monad
Auth
Queries
Executing queries
Value types
Lower-level interfaces

Description

Haskell client for Cassandra's CQL protocol

For examples, take a look at the tests directory in the source archive.

Here's the correspondence between CQL and Haskell types:

ascii - ByteString
bigint - Int64
blob - Blob
boolean - Bool
counter - Counter
decimal - Decimal
double - Double
float - Float
int - Int
text / varchar - Text
timestamp - UTCTime
uuid - UUID
varint - Integer
timeuuid - TimeUUID
inet - SockAddr
list<a> - [a]
map<a, b> - Map a b
set<a> - Set b

...and you can define your own CasType instances to extend these types, which is a very powerful way to write your code.

One way to do things is to specify your queries with a type signature, like this:

createSongs :: Query Schema () ()
createSongs = "create table songs (id uuid PRIMARY KEY, title text, artist text, comment text)"

insertSong :: Query Write (UUID, Text, Text, Maybe Text) ()
insertSong = "insert into songs (id, title, artist, comment) values (?, ?, ?)"

getOneSong :: Query Rows UUID (Text, Text, Maybe Text)
getOneSong = "select title, artist, comment from songs where id=?"

The three type parameters are the query type (Schema, Write or Rows) followed by the input and output types, which are given as tuples whose constituent types must match the ones in the query CQL. If you do not match them correctly, you'll get a runtime error when you execute the query. If you do, then the query becomes completely type safe.

Types can be Maybe types, in which case you can read and write a Cassandra 'null' in the table. Cassandra allows any column to be null, but you can lock this out by specifying non-Maybe types.

The query types are:

Schema for modifications to the schema. The output tuple type must be ().
Write for row inserts and updates, and such. The output tuple type must be ().
Rows for selects that give a list of rows in response.

The functions to use for these query types are executeSchema, executeWrite, executeTrans and executeRows or executeRow respectively.

The following pattern seems to work very well, especially along with your own CasType instances, because it gives you a place to neatly add marshalling details that keeps away from the body of your code.

insertSong :: UUID -> Text -> Text -> Maybe Text -> Cas ()
insertSong id title artist comment = executeWrite QUORUM q (id, title, artist, comment)
     where q = "insert into songs (id, title, artist, comment) values (?, ?, ?, ?)"

Incidentally, here's Haskell's little-known multi-line string syntax. You escape it using \ and then another \ where the string starts again.

str = "multi\
       \line"

(gives "multiline")

To do

Add the ability to easily run queries in parallel.
Add support for batch queries.
Add support for query paging.

Synopsis

Initialization

type Server = (HostName, ServiceName) Source

newtype Keyspace Source

The name of a Cassandra keyspace. See the Cassandra documentation for more information.

Constructors

Keyspace Text

Instances

Eq Keyspace
Ord Keyspace
Show Keyspace
IsString Keyspace

data Pool Source

newPool :: [Server] -> Keyspace -> Maybe Authentication -> IO Pool Source

Construct a pool of Cassandra connections.

newPool' :: PoolConfig -> IO Pool Source

defaultConfig :: [Server] -> Keyspace -> Maybe Authentication -> PoolConfig Source

Cassandra monad

class MonadCatchIO m => MonadCassandra m where Source

Methods

getCassandraPool :: m Pool Source

Instances

MonadCassandra Cas
MonadCassandra m => MonadCassandra (ReaderT a m)
MonadCassandra m => MonadCassandra (StateT a m)
(MonadCassandra m, Error e) => MonadCassandra (ErrorT e m)
(MonadCassandra m, Monoid a) => MonadCassandra (WriterT a m)
(MonadCassandra m, Monoid w) => MonadCassandra (RWST r w s m)

data Cas a Source

The monad used to run Cassandra queries in.

Instances

Monad Cas
Functor Cas
Applicative Cas
MonadCatchIO Cas
MonadIO Cas
MonadCassandra Cas

runCas :: Pool -> Cas a -> IO a Source

Execute Cassandra queries.

data CassandraException Source

An exception that indicates an error originating in the Cassandra server.

Instances

Show CassandraException
Exception CassandraException
Typeable * CassandraException

data CassandraCommsError Source

All errors at the communications level are reported with this exception (IOExceptions from socket I/O are always wrapped), and this exception typically would mean that a retry is warranted.

Note that this exception isn't guaranteed to be a transient one, so a limit on the number of retries is likely to be a good idea. LocalProtocolError probably indicates a corrupted database or driver bug.

Constructors

AuthenticationException Text
LocalProtocolError Text Text
MissingAuthenticationError Text Text
ValueMarshallingException TransportDirection Text Text
CassandraIOException IOException
ShortRead
NoAvailableServers
CoordinatorTimeout

Instances

Show CassandraCommsError
Exception CassandraCommsError
Typeable * CassandraCommsError

data TransportDirection Source

Constructors

TransportSending
TransportReceiving

Instances

Eq TransportDirection
Show TransportDirection

Auth

data Authentication Source

Constructors

PasswordAuthenticator UserId Password

Queries

data Query :: Style -> * -> * -> * Source

The text of a CQL query, along with type parameters to make the query type safe. The type arguments are Style, followed by input and output column types for the query each represented as a tuple.

The DataKinds language extension is required for Style.

Instances

Show (Query $a $b $c)
IsString (Query style i o)

data Style Source

The first type argument for Query. Tells us what kind of query it is.

Constructors

Schema	A query that modifies the schema, such as DROP TABLE or CREATE TABLE
Write	A query that writes data, such as an INSERT or UPDATE
Rows	A query that returns a list of rows, such as SELECT

query :: Text -> Query style i o Source

Construct a query. Another way to construct one is as an overloaded string through the IsString instance if you turn on the OverloadedStrings language extension, e.g.

{-# LANGUAGE OverloadedStrings #-}
...

getOneSong :: Query Rows UUID (Text, Text, Maybe Text)
getOneSong = "select title, artist, comment from songs where id=?"

Executing queries

data Consistency Source

Cassandra consistency level. See the Cassandra documentation for an explanation.

Constructors

ANY
ONE
TWO
THREE
QUORUM
ALL
LOCAL_QUORUM
EACH_QUORUM
SERIAL
LOCAL_SERIAL
LOCAL_ONE

Instances

Bounded Consistency
Enum Consistency
Eq Consistency
Ord Consistency
Show Consistency

data Change Source

Constructors

CREATED
UPDATED
DROPPED

Instances

Eq Change
Ord Change
Show Change

executeSchema Source

Arguments

:: (MonadCassandra m, CasValues i)
=> Consistency	Consistency level of the operation
-> Query Schema i ()	CQL query to execute
-> i	Input values substituted in the query
-> m (Change, Keyspace, Table)

Execute a schema change, such as creating or dropping a table.

executeWrite Source

Arguments

:: (MonadCassandra m, CasValues i)
=> Consistency	Consistency level of the operation
-> Query Write i ()	CQL query to execute
-> i	Input values substituted in the query
-> m ()

Execute a write operation that returns void.

executeRows Source

Arguments

:: (MonadCassandra m, CasValues i, CasValues o)
=> Consistency	Consistency level of the operation
-> Query Rows i o	CQL query to execute
-> i	Input values substituted in the query
-> m [o]

Execute a query that returns rows.

executeRow Source

Arguments

:: (MonadCassandra m, CasValues i, CasValues o)
=> Consistency	Consistency level of the operation
-> Query Rows i o	CQL query to execute
-> i	Input values substituted in the query
-> m (Maybe o)

Helper for executeRows useful in situations where you are only expecting one row to be returned.

executeTrans Source

Arguments

:: (MonadCassandra m, CasValues i)
=> Query Write i ()	CQL query to execute
-> i	Input values substituted in the query
-> m Bool

Execute a lightweight transaction. The consistency level is implicit and is SERIAL.

Value types

newtype Blob Source

If you wrap this round a ByteString, it will be treated as a blob type instead of ascii (if it was a plain ByteString type).

Constructors

Blob
Fields unBlob :: ByteString

Instances

Eq Blob
Ord Blob
Show Blob
CasType Blob

newtype Counter Source

A Cassandra distributed counter value.

Constructors

Counter
Fields unCounter :: Int64

Instances

Eq Counter
Ord Counter
Read Counter
Show Counter
CasType Counter

newtype TimeUUID Source

If you wrap this round a UUID then it is treated as a timeuuid type instead of uuid (if it was a plain UUID type).

Constructors

TimeUUID
Fields unTimeUUID :: UUID

Instances

Eq TimeUUID
Data TimeUUID
Ord TimeUUID
Read TimeUUID
Show TimeUUID
CasType TimeUUID
Typeable * TimeUUID

metadataTypes :: Metadata -> [CType] Source

A helper for extracting the types from a metadata definition.

class CasType a where Source

A type class for types that can be used in query arguments or column values in returned results.

To define your own newtypes for Cassandra data, you only need to define getCas, putCas and casType, like this:

newtype UserId = UserId UUID deriving (Eq, Show)

instance CasType UserId where
    getCas = UserId <$> getCas
    putCas (UserId i) = putCas i
    casType (UserId i) = casType i

The same can be done more simply using the GeneralizedNewtypeDeriving language extension, e.g.

{-# LANGUAGE GeneralizedNewtypeDeriving #-}

...
newtype UserId = UserId UUID deriving (Eq, Show, CasType)

If you have a more complex type you want to store as a Cassandra blob, you could write an instance like this (assuming it's an instance of the cereal package's Serialize class):

instance CasType User where
    getCas = decode . unBlob <$> getCas
    putCas = putCas . Blob . encode
    casType _ = CBlob

Minimal complete definition

getCas, putCas, casType

Methods

getCas :: Get a Source

putCas :: a -> Put Source

casType :: a -> CType Source

For a given Haskell type given as (undefined :: a), tell the caller how Cassandra represents it.

casNothing :: a Source

casObliterate :: a -> ByteString -> Maybe ByteString Source

Instances

CasType Bool
CasType Double
CasType Float
CasType Int
CasType Int64
CasType Integer
CasType Decimal
CasType ByteString
CasType SockAddr
CasType Text
CasType UTCTime
CasType UUID
CasType TimeUUID
CasType Counter
CasType Blob
CasType a => CasType [a]
CasType a => CasType (Maybe a)
(CasType a, Ord a) => CasType (Set a)
(CasType a, Ord a, CasType b) => CasType (Map a b)

class CasValues v where Source

A type class for a tuple of CasType instances, representing either a list of arguments for a query, or the values in a row of returned query results.

Methods

encodeValues :: v -> [CType] -> Either CodingFailure [Maybe ByteString] Source

decodeValues :: [(CType, Maybe ByteString)] -> Either CodingFailure v Source

Instances

CasValues ()
CasType a => CasValues a
(CasType a, CasType b) => CasValues (a, b)
(CasType a, CasType b, CasType c) => CasValues (a, b, c)
(CasType a, CasType b, CasType c, CasType d) => CasValues (a, b, c, d)
(CasType a, CasType b, CasType c, CasType d, CasType e) => CasValues (a, b, c, d, e)
(CasType a, CasType b, CasType c, CasType d, CasType e, CasType f) => CasValues (a, b, c, d, e, f)
(CasType a, CasType b, CasType c, CasType d, CasType e, CasType f, CasType g) => CasValues (a, b, c, d, e, f, g)
(CasType a, CasType b, CasType c, CasType d, CasType e, CasType f, CasType g, CasType h) => CasValues (a, b, c, d, e, f, g, h)
(CasType a, CasType b, CasType c, CasType d, CasType e, CasType f, CasType g, CasType h, CasType i) => CasValues (a, b, c, d, e, f, g, h, i)
(CasType a, CasType b, CasType c, CasType d, CasType e, CasType f, CasType g, CasType h, CasType i, CasType j) => CasValues (a, b, c, d, e, f, g, h, i, j)
(CasType a, CasType b, CasType c, CasType d, CasType e, CasType f, CasType g, CasType h, CasType i, CasType j, CasType k) => CasValues (a, b, c, d, e, f, g, h, i, j, k)
(CasType a, CasType b, CasType c, CasType d, CasType e, CasType f, CasType g, CasType h, CasType i, CasType j, CasType k, CasType l) => CasValues (a, b, c, d, e, f, g, h, i, j, k, l)
(CasType a, CasType b, CasType c, CasType d, CasType e, CasType f, CasType g, CasType h, CasType i, CasType j, CasType k, CasType l, CasType m) => CasValues (a, b, c, d, e, f, g, h, i, j, k, l, m)
(CasType a, CasType b, CasType c, CasType d, CasType e, CasType f, CasType g, CasType h, CasType i, CasType j, CasType k, CasType l, CasType m, CasType n) => CasValues (a, b, c, d, e, f, g, h, i, j, k, l, m, n)
(CasType a, CasType b, CasType c, CasType d, CasType e, CasType f, CasType g, CasType h, CasType i, CasType j, CasType k, CasType l, CasType m, CasType n, CasType o) => CasValues (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o)
(CasType a, CasType b, CasType c, CasType d, CasType e, CasType f, CasType g, CasType h, CasType i, CasType j, CasType k, CasType l, CasType m, CasType n, CasType o, CasType p) => CasValues (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p)
(CasType a, CasType b, CasType c, CasType d, CasType e, CasType f, CasType g, CasType h, CasType i, CasType j, CasType k, CasType l, CasType m, CasType n, CasType o, CasType p, CasType q) => CasValues (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q)
(CasType a, CasType b, CasType c, CasType d, CasType e, CasType f, CasType g, CasType h, CasType i, CasType j, CasType k, CasType l, CasType m, CasType n, CasType o, CasType p, CasType q, CasType r) => CasValues (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r)
(CasType a, CasType b, CasType c, CasType d, CasType e, CasType f, CasType g, CasType h, CasType i, CasType j, CasType k, CasType l, CasType m, CasType n, CasType o, CasType p, CasType q, CasType r, CasType s) => CasValues (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s)
(CasType a, CasType b, CasType c, CasType d, CasType e, CasType f, CasType g, CasType h, CasType i, CasType j, CasType k, CasType l, CasType m, CasType n, CasType o, CasType p, CasType q, CasType r, CasType s, CasType t) => CasValues (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t)

Lower-level interfaces

executeRaw :: (MonadCassandra m, CasValues i) => Query style any_i any_o -> i -> Consistency -> m (Result [Maybe ByteString]) Source

A low-level function in case you need some rarely-used capabilities.

data Result vs Source

A low-level query result used with executeRaw.

Constructors

Void
RowsResult Metadata [vs]
SetKeyspace Text
Prepared PreparedQueryID Metadata
SchemaChange Change Keyspace Table

Instances

Functor Result
Show vs => Show (Result vs)

data TableSpec Source

A fully qualified identification of a table that includes the Keyspace.

Constructors

TableSpec Keyspace Table

Instances

Eq TableSpec
Ord TableSpec
Show TableSpec

data ColumnSpec Source

Information about a table column.

Constructors

ColumnSpec TableSpec Text CType

Instances

Show ColumnSpec

data Metadata Source

The specification of a list of result set columns.

Constructors

Metadata [ColumnSpec]

Instances

Show Metadata

data CType Source

Cassandra data types as used in metadata.

Instances

Eq CType
Show CType

newtype Table Source

The name of a Cassandra table (a.k.a. column family).

Constructors

Table Text

Instances

Eq Table
Ord Table
Show Table
IsString Table

newtype PreparedQueryID Source

Constructors

PreparedQueryID ByteString

Instances

Eq PreparedQueryID
Ord PreparedQueryID
Show PreparedQueryID

serverStats :: Pool -> IO [ServerStat] Source

data ServerStat Source

Exported stats for a server.

Constructors

ServerStat
Fields statServer :: Server statSessionCount :: Int statAvailable :: Bool

Instances

Show ServerStat

data PoolConfig Source

Constructors

PoolConfig
Fields piServers :: [Server] piKeyspace :: Keyspace piAuth :: Maybe Authentication piSessionCreateTimeout :: NominalDiffTime piConnectionTimeout :: NominalDiffTime piIoTimeout :: NominalDiffTime piBackoffOnError :: NominalDiffTime piMaxSessionIdleTime :: NominalDiffTime piMaxSessions :: Int

ServerError Text Text
ProtocolError Text Text
BadCredentials Text Text
UnavailableException Text Consistency Int Int Text
Overloaded Text Text
IsBootstrapping Text Text
TruncateError Text Text
WriteTimeout Text Consistency Int Int Text Text
ReadTimeout Text Consistency Int Int Bool Text
SyntaxError Text Text
Unauthorized Text Text
Invalid Text Text
ConfigError Text Text
AlreadyExists Text Keyspace Table Text
Unprepared Text PreparedQueryID Text

CCustom Text
CAscii
CBigint
CBlob
CBoolean
CCounter
CDecimal
CDouble
CFloat
CInt
CText
CTimestamp
CUuid
CVarint
CTimeuuid
CInet
CList CType
CMap CType CType
CSet CType
CMaybe CType