Connection Handling

The ‘PandraCore’ connection handler provides managed access to the underlying Cassandra/Thrift transports and API.

Core natively supports named connection pooling against Thrift’s TBinaryProtocol, TBinaryProtocolAccelerated and thrift_protocol.so, tweakable read/write modes (active connection, round-robin and random), dynamic consistency levels, robust logging and error correction and a complete abstraction suite against the Thrift API. It’s therefore straight forward to create your own data model without any reliance on the packaged object model (Containers) while retaining the power of Core’s socket pool.

Getting Connected

Connection pooling allow nodes in a single ring to be connected to and managed on a host by host basis, or collectively auto-discoverd based on a handful of seeding hosts. This small guide shows how to do both, how to setup authentication, toggle read/write consistency levels and interact with the Thrift API directly.

Pooling Overview

Pools are labelled collections of open sockets to Cassandra, usually named the same as the Keyspace they’re connecting to. Pandra’s default pool name is ‘Keyspace1’, matching the default Cassandra install. This can be changed in config.php to reflect your working keyspace, or at runtime by passing it to the connection methods.

Once hosts have been attached to the pool (described later), a range of rollback and host selection features will come into play for both reading and writing.

Read/Write host selection modes* can be toggled independently. eg :

PandraCore::setWriteMode(PandraCore::MODE_ROUND);
PandraCore::setReadMode(PandraCore::MODE_ACTIVE);

*By default, both Read and Write modes are random.

PandraCore::MODE_ROUND Iterates over each host in the pool (round robin)

PandraCore::MODE_RANDOM Randomly selects a node in the active pool

PandraCore::MODE_ACTIVE Always selects a single host (set by PandraCore::setActive())

Core will attempt 2 successive retries before marking a host as ‘down’, whereby it will close any persistent connection and trim the host from the connection pool. The host will be marked in Memcached or APC if available for a cooldown period of 10 seconds to avoid other PHP instances polling the ‘dead’ host.

Host by Host

Individual hosts can be attached to a connection pool by calling the connect() method

PandraCore::connect('unique id', '127.0.0.1'); 

optionally, both the pool name (keyspace) and port can be passed

PandraCore::connect('unique1', '127.0.0.1', 'MyKeyspace'); 

PandraCore::connect('unique2', '127.0.0.1', 'MyKeyspace', '5690'); 

It’s necessary to give each connection a unique ID as well as a hostname – it serves as the handle for managing the node.

To disconnect a host :

PandraCore::disconnect('uniqueid);

… disconnectAll(); drops everything.

Seeded connection

Core can take an array of hosts, even if that array is 1 element long, and discover Cassandra’s logical topology on it’s own.

PandraCore::connectSeededKeyspace(array('127.0.0.1', '10.0.0.20')); 

This works for a single host or dozens, and is generally the preferred method for making a quick connection.