Home

Usage

Connection

The DSN format matches the following syntax:

"cassandra:[host=ip_address;port=port_number;dbname=keyspace_name;cqlversion=version],+"

Sample connections syntaxes:

"cassandra:host=10.0.0.1;port=9160,host=10.0.0.2;port=9162;cqlversion=3.0.0"
"cassandra:host=localhost;port=9160"

The connection respects the PDO construction:

$db_handle = new PDO("cassandra:host=localhost;port=9160", $username, $password);

The constructor honours the following options

These options can be passed in the fourth argument for PDO constructor

PDO::ATTR_PERSISTENT	False/True	Keep a connection alive between requests
PDO::ATTR_TIMEOUT	integer	Connection timeout value in seconds
PDO::CASSANDRA_ATTR_THRIFT_DEBUG	boolean	Converts thrift debug output into PHP warnings
PDO::CASSANDRA_ATTR_PRESERVE_VALUES	boolean	Preserves values as they come from Cassandra
PDO::CASSANDRA_ATTR_CONSISTENCYLEVEL	PDO::CASSANDRA_CONSISTENCYLEVEL_ONE PDO::CASSANDRA_CONSISTENCYLEVEL_LOCAL_QUORUM PDO::CASSANDRA_CONSISTENCYLEVEL_QUORUM

Driver specific attributes for PDO::setAttribute

PDO::CASSANDRA_ATTR_NUM_RETRIES	integer	The amount of connection retries
PDO::CASSANDRA_ATTR_RETRY_INTERVAL	integer	Sets how many times to keep retrying a host before marking it as down.
PDO::CASSANDRA_ATTR_MAX_CONSECUTIVE_FAILURES	integer	Sets how many times to keep retrying a host before marking it as down.
PDO::CASSANDRA_ATTR_LINGER	integer	How long does the socket linger after it's being closed
PDO::CASSANDRA_ATTR_NO_DELAY	boolean	Whether to enable/disable Nagle algorithm
PDO::CASSANDRA_ATTR_CONN_TIMEOUT	integer	Connection timeout in ms
PDO::CASSANDRA_ATTR_RECV_TIMEOUT	integer	Receive timeout in ms
PDO::CASSANDRA_ATTR_SEND_TIMEOUT	integer	Send timeout in ms
PDO::CASSANDRA_ATTR_COMPRESSION	boolean	Whether to enable/disable compression
PDO::CASSANDRA_ATTR_THRIFT_DEBUG	boolean	Converts thrift debug output into PHP warnings
PDO::CASSANDRA_ATTR_PRESERVE_VALUES	boolean	Preserves values as they come from Cassandra

Transactions

Transactions are not supported and calling PDO::beginTransaction will result in an exception.

Request Execution

Direct execution

$db_handle->exec("UPDATE mytable SET my_int=42 WHERE my_key='awesome');

Prepared statements

$stmt = $db_handle->prepare("SELECT my_int FROM my_table WHERE my_key=:key;");
$stmt->bindValue(':my_key', 'awesome');
$stmt->execute();
print_r($stmt->fetch(PDO::FETCH_ASSOC));

Binding

Parameters can be bound using the PDO::bindValue method which has the following signature:

$stmt->bindValue (':placeholder', value, target_type = PDO::PARAM_STR);

Binding examples:

$stmt->bindValue (':my_int', "4242", PDO::PARAM_INT);
$stmt->bindValue (':my_int', 2121, PDO::PARAM_INT);
$stmt->bindValue (':my_map', "{'key':value}", PDO::CASSANDRA_MAP);

Collections are currently not bindable. However you can still use them by binding constructing the corresponding string by hand.

This chart resumes the current situation:

Type	Bindable?	Associated type
text	YES	PDO::PARAM_STR OR PDO::CASSANDRA_STR
blob	YES	PDO::PARAM_BLOB
ascii	YES	PDO::PARAM_STR OR PDO::CASSANDRA_STR
varchar	YES	PDO::PARAM_STR OR PDO::CASSANDRA_STR
uuid	YES	PDO::CASSANDRA_UUID
int	YES	PDO::PARAM_INT OR PDO::CASSANDRA_INT
bigint	YES	PDO::PARAM_INT OR PDO::CASSANDRA_INT
float	YES	PDO::CASSANDRA_FLOAT
double	YES	PDO::CASSANDRA_FLOAT
decimal	YES	PDO::CASSANDRA_DECIMAL
collections	NO	PDO::PARAM_STMT
map	YES	PDO::CASSANDRA_MAP
set	YES	PDO::CASSANDRA_SET
list	YES	PDO::CASSANDRA_LIST

Special types representation

Decimal type

Cassandra decimal type is implemented using variable precision. This means that according to the actual size of the unscaled value (uv), the uv can be stored on an integer or a n bytes number.

PHP has no core support for multiprecision numbers. To avoid to add dependencies on external libraries such as GMP, the values are returned as an array representing the uv as is:

Value	Type	Explanation
scale_factor	int	10 power - scalefactor
unscaled_val	int,long	Least significant part (1 time)
unscaled_val	long	(0..n times)
unscaled_val	int,long	(0,1 time) Most significant part

E.G 4242.21 would be represented as follow:

Value	Type	Explanation
2	int	scale factor
424221	long	unscaled_val

112233445566778899.112233445566778899 would be represented as follow:

Value	Type	Explanation
18	int	scale factor
8234495237290528275	long	unscaled_val
6084187275451764	int	unscaled_val Most significant type

The value can be calculated like this: 8234495237290528275 + 6084187275451764 * 2 power 64