Safe Haskell	None
Language	Haskell2010

Database.CQL.Protocol

Contents

Cql type-class
Basic type definitions
Header
Request
Response
Row, Tuple and Record

Description

The CQL native protocol is a binary frame-based protocol where each frame has a Header, a Length and a body. The protocol distinguishes Requests and Responses.

Some usage examples:

Constructing and Serialising a Request

let q = QueryString "select peer from system.peers where data_center = ? and rack = ?"
    p = QueryParams One False ("uk-1", "r-0") Nothing Nothing Nothing
    r = RqQuery (Query q p :: Query R (Text, Text) (Identity IP))
    i = mkStreamId 0
in pack V3 noCompression False i r

Deserialising a Response

-- assuming bh contains the raw header byte string and bb the raw
-- body byte string.
case header V3 bh of
    Left  e -> ...
    Right h -> unpack noCompression h bb

A generic query processing function

query :: (Tuple a, Tuple b) => Version -> Socket -> QueryString k a b -> QueryParams a -> IO (Response k a b)
query v s q p = do
    let i = mkStreamId 0
    sendToServer s (pack v noCompression False i (RqQuery (Query q p)))
    b <- recv (if v == V3 then 9 else 8) s
    h <- either (throwIO . MyException) return (header v b)
    when (headerType h == RqHeader) $
        throwIO UnexpectedRequestHeader
    let len = lengthRepr (bodyLength h)
    x <- recv (fromIntegral len) s
    case unpack noCompression h x of
        Left e              -> throwIO $ AnotherException e
        Right (RsError _ e) -> throwIO e
        Right response      -> return response

Synopsis

Cql type-class

class Cql a where Source

A type that can be converted from and to some CQL Value.

This type-class is used to map custom types to Cassandra data-types. For example:

newtype MyType = MyType Int32

instance Cql MyType where
    ctype              = Tagged IntColumn
    toCql (MyType i)   = CqlInt i
    fromCql (CqlInt i) = Right (MyType i)
    fromCql _          = Left "Expected CqlInt"

Methods

ctype :: Tagged a ColumnType Source

the column-type of a

toCql :: a -> Value Source

map a to some CQL data-type

fromCql :: Value -> Either String a Source

map a CQL value back to a

Instances

Cql Bool Source
Cql Double Source
Cql Float Source
Cql Int32 Source
Cql Int64 Source
Cql Integer Source
Cql Decimal Source
Cql IP Source
Cql Text Source
Cql UTCTime Source
Cql UUID Source
Cql TimeUuid Source
Cql Counter Source
Cql Blob Source
Cql Ascii Source
Cql a => Cql [a] Source
Cql a => Cql (Maybe a) Source	Please note that due to the fact that Cassandra internally represents empty collection type values (i.e. lists, maps and sets) as `null`, we can not distinguish `Just []` from `Nothing` on response decoding.
Cql a => Cql (Set a) Source
(Cql a, Cql b) => Cql (Map a b) Source

Basic type definitions

newtype Keyspace Source

Constructors

Keyspace
Fields unKeyspace :: Text

Instances

Eq Keyspace Source
Show Keyspace Source

newtype Table Source

Constructors

Table
Fields unTable :: Text

Instances

Eq Table Source
Show Table Source

newtype PagingState Source

Opaque token passed to the server to continue result paging.

Constructors

PagingState
Fields unPagingState :: ByteString

Instances

Eq PagingState Source
Show PagingState Source

newtype QueryId k a b Source

ID representing a prepared query.

Constructors

QueryId
Fields unQueryId :: ByteString

Instances

Eq (QueryId k a b) Source
Show (QueryId k a b) Source

newtype QueryString k a b Source

Constructors

QueryString
Fields unQueryString :: Text

Instances

Eq (QueryString k a b) Source
Show (QueryString k a b) Source
IsString (QueryString k a b) Source

data Version Source

CQL binary protocol version.

Constructors

V2	version 2
V3	version 3

Instances

Eq Version Source
Show Version Source

data CqlVersion Source

The CQL version (not the binary protocol version).

Constructors

Cqlv300
CqlVersion !Text

Instances

Eq CqlVersion Source
Show CqlVersion Source

data CompressionAlgorithm Source

Constructors

Snappy
LZ4
None

Instances

Eq CompressionAlgorithm Source
Show CompressionAlgorithm Source

data Compression Source

Constructors

Compression
Fields algorithm :: !CompressionAlgorithm shrink :: ByteString -> Maybe ByteString expand :: ByteString -> Maybe ByteString

Instances

Show Compression Source

noCompression :: Compression Source

data Consistency Source

Consistency level.

Constructors

Any
One
Two
Three
Quorum
All
LocalQuorum
EachQuorum
Serial
LocalOne
LocalSerial

Instances

Eq Consistency Source
Show Consistency Source

data OpCode Source

An opcode is a tag to distinguish protocol frame bodies.

Constructors

OcError
OcStartup
OcReady
OcAuthenticate
OcOptions
OcSupported
OcQuery
OcResult
OcPrepare
OcExecute
OcRegister
OcEvent
OcBatch
OcAuthChallenge
OcAuthResponse
OcAuthSuccess

Instances

Eq OpCode Source
Show OpCode Source

data ColumnType Source

The type of a single CQL column.

Instances

Eq ColumnType Source
Show ColumnType Source

newtype Ascii Source

Constructors

Ascii
Fields fromAscii :: Text

Instances

Eq Ascii Source
Ord Ascii Source
Show Ascii Source
IsString Ascii Source
Cql Ascii Source

newtype Blob Source

Constructors

Blob
Fields fromBlob :: ByteString

Instances

Eq Blob Source
Ord Blob Source
Show Blob Source
Cql Blob Source

newtype Counter Source

Constructors

Counter
Fields fromCounter :: Int64

Instances

Eq Counter Source
Ord Counter Source
Show Counter Source
Cql Counter Source

newtype TimeUuid Source

Constructors

TimeUuid
Fields fromTimeUuid :: UUID

Instances

Eq TimeUuid Source
Ord TimeUuid Source
Show TimeUuid Source
Cql TimeUuid Source

newtype Set a Source

Constructors

Set
Fields fromSet :: [a]

Instances

Show a => Show (Set a) Source
Cql a => Cql (Set a) Source

newtype Map a b Source

Constructors

Map
Fields fromMap :: [(a, b)]

Instances

(Show a, Show b) => Show (Map a b) Source
(Cql a, Cql b) => Cql (Map a b) Source

data Value Source

A CQL value. The various constructors correspond to CQL data-types for individual columns in Cassandra.

Constructors

CqlCustom !ByteString
CqlBoolean !Bool
CqlInt !Int32
CqlBigInt !Int64
CqlVarInt !Integer
CqlFloat !Float
CqlDecimal !Decimal
CqlDouble !Double
CqlText !Text
CqlInet !IP
CqlUuid !UUID
CqlTimestamp !Int64
CqlAscii !Text
CqlBlob !ByteString
CqlCounter !Int64
CqlTimeUuid !UUID
CqlMaybe (Maybe Value)
CqlList [Value]
CqlSet [Value]
CqlMap [(Value, Value)]
CqlTuple [Value]	binary protocol version >= 3
CqlUdt [(Text, Value)]	binary protocol version >= 3

Instances

Eq Value Source
Show Value Source

newtype Tagged a b Source

Tag some value with a phantom type.

Constructors

Tagged
Fields untag :: b

retag :: Tagged a c -> Tagged b c Source

data R Source

data W Source

data S Source

Header

data Header Source

Protocol frame header.

Constructors

Header
Fields headerType :: !HeaderType version :: !Version flags :: !Flags streamId :: !StreamId opCode :: !OpCode bodyLength :: !Length

data HeaderType Source

Constructors

RqHeader	A request frame header.
RsHeader	A response frame header.

Instances

Show HeaderType Source

header :: Version -> ByteString -> Either String Header Source

Deserialise a frame header using the version specific decoding format.

Length

newtype Length Source

The type denoting a protocol frame length.

Constructors

Length
Fields lengthRepr :: Int32

Instances

Eq Length Source
Show Length Source

StreamId

data StreamId Source

Streams allow multiplexing of requests over a single communication channel. The StreamId correlates Requests with Responses.

Instances

Eq StreamId Source
Show StreamId Source

mkStreamId :: Integral i => i -> StreamId Source

Create a StreamId from the given integral value. In version 2, a StreamId is an Int8 and in version 3 an Int16.

fromStreamId :: StreamId -> Int Source

Convert the stream ID to an integer.

Flags

data Flags Source

Type representing header flags. Flags form a monoid and can be used as in compress <> tracing <> mempty.

Instances

Eq Flags Source
Show Flags Source
Monoid Flags Source

compress :: Flags Source

Compression flag. If set, the frame body is compressed.

tracing :: Flags Source

Tracing flag. If a request support tracing and the tracing flag was set, the response to this request will have the tracing flag set and contain tracing information.

isSet :: Flags -> Flags -> Bool Source

Check if a particular flag is present.

Request

data Request k a b Source

The type corresponding to the protocol request frame.

The type parameter k denotes the kind of request. It is present to allow distinguishing read operations from write operations. Use R for read, W for write and S for schema related operations.

a represents the argument type and b the return type of this request.

Constructors

RqStartup !Startup
RqOptions !Options
RqRegister !Register
RqBatch !Batch
RqAuthResp !AuthResponse
RqPrepare !(Prepare k a b)
RqQuery !(Query k a b)
RqExecute !(Execute k a b)

Instances

Show a => Show (Request k a b) Source

getOpCode :: Request k a b -> OpCode Source

Get the protocol OpCode corresponding to the given Request.

pack Source

Arguments

:: Tuple a
=> Version	protocol version, which determines the encoding
-> Compression	compression to use
-> Bool	enable/disable tracing
-> StreamId	the stream Id to use
-> Request k a b	the actual request to serialise
-> Either String ByteString

Serialise the given request, optionally using compression. The result is either an error description in case of failure or a binary protocol frame, including Header, Length and body.

Options

data Options Source

An options request, send prior to Startup to request the server's startup options.

Constructors

Options

Instances

Show Options Source

Startup

data Startup Source

A startup request which is used when initialising a connection to the server. It specifies the CQL version to use and optionally the compression algorithm.

Constructors

Startup !CqlVersion !CompressionAlgorithm

Instances

Show Startup Source

Auth Response

newtype AuthResponse Source

A request send in response to a previous authentication challenge.

Constructors

AuthResponse ByteString

Instances

Show AuthResponse Source

Register

newtype Register Source

Register's the connection this request is made through, to receive server events.

Constructors

Register [EventType]

Instances

Show Register Source

data EventType Source

Event types to register.

Constructors

TopologyChangeEvent	events related to change in the cluster topology
StatusChangeEvent	events related to change of node status
SchemaChangeEvent	events related to schema change

Instances

Show EventType Source

Query

data Query k a b Source

A CQL query (select, insert, etc.).

Constructors

Query !(QueryString k a b) !(QueryParams a)

Instances

Show a => Show (Query k a b) Source

data QueryParams a Source

Query parameters.

Constructors

QueryParams
Fields consistency :: !Consistency consistency leven to use skipMetaData :: !Bool skip metadata in response values :: a query arguments pageSize :: Maybe Int32 desired result set size queryPagingState :: Maybe PagingState serialConsistency :: Maybe SerialConsistency

Instances

Show a => Show (QueryParams a) Source

data SerialConsistency Source

Consistency level for the serial phase of conditional updates.

Constructors

SerialConsistency
LocalSerialConsistency

Instances

Show SerialConsistency Source

Batch

data Batch Source

Allows executing a list of queries (prepared or not) as a batch.

Constructors

Batch
Fields batchType :: !BatchType batchQuery :: [BatchQuery] batchConsistency :: !Consistency batchSerialConsistency :: Maybe SerialConsistency

Instances

Show Batch Source

data BatchQuery where Source

A GADT to unify queries and prepared queries both of which can be used in batch requests.

Constructors

BatchQuery :: (Show a, Tuple a, Tuple b) => !(QueryString W a b) -> !a -> BatchQuery
BatchPrepared :: (Show a, Tuple a, Tuple b) => !(QueryId W a b) -> !a -> BatchQuery

Instances

Show BatchQuery Source

data BatchType Source

Constructors

BatchLogged	default, uses a batch log for atomic application
BatchUnLogged	skip the batch log
BatchCounter	used for batched counter updates

Instances

Show BatchType Source

Prepare

newtype Prepare k a b Source

Prepare a query for later execution (cf. Execute).

Constructors

Prepare (QueryString k a b)

Instances

Show (Prepare k a b) Source

Execute

data Execute k a b Source

Executes a prepared query.

Constructors

Execute !(QueryId k a b) !(QueryParams a)

Instances

Show a => Show (Execute k a b) Source

Response

data Response k a b Source

The type corresponding to the protocol response frame.

The type parameter k denotes the kind of response. It is present to allow distinguishing read operations from write operations. Use R for read, W for write and S for schema related operations.

a represents the argument type and b the return type of this response.

Constructors

RsError (Maybe UUID) !Error
RsReady (Maybe UUID) !Ready
RsAuthenticate (Maybe UUID) !Authenticate
RsAuthChallenge (Maybe UUID) !AuthChallenge
RsAuthSuccess (Maybe UUID) !AuthSuccess
RsSupported (Maybe UUID) !Supported
RsResult (Maybe UUID) !(Result k a b)
RsEvent (Maybe UUID) !Event

Instances

Show b => Show (Response k a b) Source

unpack :: (Tuple a, Tuple b) => Compression -> Header -> ByteString -> Either String (Response k a b) Source

Deserialise a Response from the given ByteString.

Ready

data Ready Source

The server is ready to process queries. Response of a Startup request.

Constructors

Ready

Instances

Show Ready Source

Authenticate

newtype Authenticate Source

The server requires authentication.

Constructors

Authenticate Text

Instances

Show Authenticate Source

newtype AuthChallenge Source

A server-send authentication challenge.

Constructors

AuthChallenge (Maybe ByteString)

Instances

Show AuthChallenge Source

newtype AuthSuccess Source

Indicates the success of an authentication phase.

Constructors

AuthSuccess (Maybe ByteString)

Instances

Show AuthSuccess Source

Result

data Result k a b Source

Query response.

Constructors

VoidResult
RowsResult !MetaData [b]
SetKeyspaceResult !Keyspace
PreparedResult !(QueryId k a b) !MetaData !MetaData
SchemaChangeResult !SchemaChange

Instances

Show b => Show (Result k a b) Source

data MetaData Source

Part of a RowsResult. Describes the result set.

Constructors

MetaData
Fields columnCount :: !Int32 pagingState :: Maybe PagingState columnSpecs :: [ColumnSpec]

Instances

Show MetaData Source

data ColumnSpec Source

The column specification. Part of MetaData unless skipMetaData in QueryParams was True.

Constructors

ColumnSpec
Fields keyspace :: !Keyspace table :: !Table columnName :: !Text columnType :: !ColumnType

Instances

Show ColumnSpec Source

Supported

data Supported Source

The startup options supported by the server. Response of an Options request.

Constructors

Supported [CompressionAlgorithm] [CqlVersion]

Instances

Show Supported Source

Event

data Event Source

Messages send by the server without request, if the connection has been Registered to receive such events.

Constructors

TopologyEvent !TopologyChange !SockAddr
StatusEvent !StatusChange !SockAddr
SchemaEvent !SchemaChange

Instances

Show Event Source

data TopologyChange Source

Constructors

NewNode
RemovedNode

Instances

Eq TopologyChange Source
Ord TopologyChange Source
Show TopologyChange Source

data SchemaChange Source

Constructors

SchemaCreated !Change
SchemaUpdated !Change
SchemaDropped !Change

Instances

Show SchemaChange Source

data StatusChange Source

Constructors

Up
Down

Instances

Eq StatusChange Source
Ord StatusChange Source
Show StatusChange Source

data Change Source

Constructors

KeyspaceChange !Keyspace
TableChange !Keyspace !Table
TypeChange !Keyspace !Text

Instances

Show Change Source

Error

data Error Source

Error response.

Constructors

AlreadyExists !Text !Keyspace !Table
BadCredentials !Text
ConfigError !Text
Invalid !Text
IsBootstrapping !Text
Overloaded !Text
ProtocolError !Text
ServerError !Text
SyntaxError !Text
TruncateError !Text
Unauthorized !Text
Unprepared !Text !ByteString
Unavailable
Fields unavailMessage :: !Text unavailConsistency :: !Consistency unavailNumRequired :: !Int32 unavailNumAlive :: !Int32
ReadTimeout
Fields rTimeoutMessage :: !Text rTimeoutConsistency :: !Consistency rTimeoutNumAck :: !Int32 rTimeoutNumRequired :: !Int32 rTimeoutDataPresent :: !Bool
WriteTimeout
Fields wTimeoutMessage :: !Text wTimeoutConsistency :: !Consistency wTimeoutNumAck :: !Int32 wTimeoutNumRequired :: !Int32 wTimeoutWriteType :: !WriteType

Instances

Eq Error Source
Show Error Source
Exception Error Source

data WriteType Source

Constructors

WriteSimple
WriteBatch
WriteBatchLog
WriteUnloggedBatch
WriteCounter

Instances

Eq WriteType Source
Show WriteType Source

Row, Tuple and Record

class PrivateTuple a => Tuple a Source

Instances

Tuple () Source
Tuple Row Source
Cql a => Tuple (Identity a) Source

count :: PrivateTuple a => Tagged a Int Source

check :: PrivateTuple a => Tagged a ([ColumnType] -> [ColumnType]) Source

tuple :: PrivateTuple a => Version -> [ColumnType] -> Get a Source

store :: PrivateTuple a => Version -> Putter a Source

data Row Source

A row is a vector of Values.

Instances

Eq Row Source
Show Row Source
Tuple Row Source

mkRow :: [(Value, ColumnType)] -> Row Source

fromRow :: Cql a => Int -> Row -> Either String a Source

Convert a row element.

columnTypes :: Row -> [ColumnType] Source

rowLength :: Row -> Int Source

class Record a where Source

Record/Tuple conversion. For example:

data Peer = Peer
    { peerAddr :: IP
    , peerRPC  :: IP
    , peerDC   :: Text
    , peerRack :: Text
    } deriving Show

recordInstance ''Peer

map asRecord <$> performQuery "SELECT peer, rpc_address, data_center, rack FROM system.peers"

The generated type-class instance maps between record and tuple constructors:

type instance TupleType Peer = (IP, IP, Text, Text)

instance Record Peer where
    asTuple (Peer a b c d) = (a, b, c, d)
    asRecord (a, b, c, d)  = Peer a b c d

Methods

asTuple :: a -> TupleType a Source

asRecord :: TupleType a -> a Source

type family TupleType a Source

recordInstance :: Name -> Q [Dec] Source

CustomColumn !Text
AsciiColumn
BigIntColumn
BlobColumn
BooleanColumn
CounterColumn
DecimalColumn
DoubleColumn
FloatColumn
IntColumn
TextColumn
TimestampColumn
UuidColumn
VarCharColumn
VarIntColumn
TimeUuidColumn
InetColumn
MaybeColumn !ColumnType
ListColumn !ColumnType
SetColumn !ColumnType
MapColumn !ColumnType !ColumnType
TupleColumn [ColumnType]
UdtColumn !Keyspace !Text [(Text, ColumnType)]