Core

Usage

Specifying addresses of DSE nodes

withContactPoints() and withPort() methods of the Dse\Cluster\Builder are used to specify IP addresses or hostnames and port number of the nodes in a given DSE cluster.

Note that you don’t have to specify the addresses of all hosts in your cluster. Once the driver has established a connection to any host, it will perform auto-discovery and connect to all hosts in the cluster.

<?php

$cluster = Dse::cluster()
               ->withContactPoints('10.0.1.24', 'example.com', 'localhost')
               ->withPort(9042)
               ->build();
$session = $cluster->connect();

Discovering nodes in the cluster

After the initial connection to one of the hosts specified via withContactPoints() succeeds, the driver discovers the addresses and connects to all members of the cluster automatically. You can also see the nodes that the driver discovered by running SELECT * FROM system.peers.

Persistent sessions

In order to limit the startup time and total number of connections to a DSE cluster, the PHP Driver enables persistent sessions by default. All cluster and sessions using the same initial configuration will be shared across requests when persistent sessions are enabled. You can toggle this setting using Dse\Cluster\Builder::withPersistentSessions().

<?php

$cluster = Dse::cluster()
               ->withPersistentSessions(false)
               ->build();
$session = $cluster->connect();

Note that disabling persistent sessions will cause a significant slow down of cluster initialization as the connections will be forced to get re-established for every request.

Once persistent sessions are enabled, you can view how many of them are currently active. They will be exposed in the Dse extension section of phpinfo().

Persistent sessions stay alive for the duration of the parent process, typically a php-fpm worker or apache worker. These sessions will be reused for all requests served by that worker process. Once a worker process has reached its end of life, sessions will get cleaned up automatically and will be re-create in the new process.

Configuring load balancing policy

The PHP Driver comes with a variety of load balancing policies. By default it uses a combination of latency aware, token aware and data center aware round robin load balancing.

The token aware load balancing policy uses the same hashing algorithms as the Apache Cassandra to directly route the execution of prepared statements to the replica node, avoiding an additional network hop to/from the coordinator. You can toggle its usage with Dse\Cluster\Builder::withTokenAwareRouting().

<?php

$cluster = Dse::cluster()
               ->withTokenAwareRouting(false)
               ->build();
$session = $cluster->connect();

The default datacenter aware round robin load balancing policy is configured to keep all traffic in the same datacenter. Upon connecting to a host from the initial list of contact points, the driver will consider that host’s datacenter to be local. Only hosts from the same datacenter will be connected to and used for executing statements. You can override the name of the local datacenter. The number of hosts from remote datacenters that the driver may use and whether it should execute statements with local consistencies on those hosts in case none of the local hosts are available. All of that is configurable via Dse\Cluster\Builder::withDatacenterAwareRoundRobinLoadBalancingPolicy().

<?php

$cluster = Dse::cluster()
               ->withDatacenterAwareRoundRobinLoadBalancingPolicy("us-west", 2, true)
               ->build();
$session = $cluster->connect();

You may disable datacenter awareness by calling Dse\Cluster\Builder::withRoundRobinLoadBalancingPolicy().

<?php

$cluster = Dse::cluster()
               ->withRoundRobinLoadBalancingPolicy()
               ->build();
$session = $cluster->connect();

Finally, latency-aware routing ensures that requests are routed to the hosts that respond the fastest. You can switch it off via Dse\Cluster\Builder::withLatencyAwareRouting().

<?php

$cluster = Dse::cluster()
               ->withLatencyAwareRouting(false)
               ->build();
$session = $cluster->connect();

Setting protocol version

The PHP driver will automatically negotiate native protocol version of TCP connections to the latest supported by both the driver and Apache Cassandra servers. It does this by attempting connection at the highest supported protocol version (currently 2) and negotiating it down upon unsupported version responses from the server.

In a scenario with an Apache Cassandra cluster consisting of nodes of mixed versions (e.g. 1.2.x and 2.0.x), this might pose problems as the driver could establish native protocol version to be 2, while some of the nodes don’t support it, causing connections to the rest of the cluster to fail.

You can force the driver to start negotiation at a lower protocol version by using Dse\Cluster\Builder::withProtocolVersion().

<?php

$cluster = Dse::cluster()
               ->withProtocolVersion(1)
               ->build();
$session = $cluster->connect();

Tweaking driver’s throughput

There are a few variables affecting the total throughput of the driver that can be tweaked client-side. The maximum number of requests that can be executed at the same time is calculated with the following formula:

inflight_requests = io_threads * requests_per_connection * maximum_number_of_connections_per_host * connected_hosts

Where io_threads by default is 1, requests_per_connection for the currently supported protocol versions is 128, maximum_number_of_connections_per_host by default is 2 and connected_hosts is the total number of hosts that can be connected to. This last variable depends on the load balancing policy used, data center aware policy only connects to the hosts in the same data center by default.

You can change the value of io_threads from the formula above by using Dse\Cluster\Builder::withIOThreads().

<?php

$cluster = Dse::cluster()
               ->withIOThreads(4)
               ->build();
$session = $cluster->connect();

You can change the value of maximum_number_of_connections_per_host from the formula above by using Dse\Cluster\Builder::withConnectionsPerHost().

<?php

$cluster = Dse::cluster()
               ->withConnectionsPerHost(4, 8)
               ->build();
$session = $cluster->connect();

Disabling TCP nodelay

By default, the driver enables TCP nodelay (Nagle’s algorithm) on all connections it uses. Disabling it is not recommended but possible via Dse\Cluster\Builder::withTCPNodelay().

<?php

$cluster = Dse::cluster()
               ->withTCPNodelay(false)
               ->build();
$session = $cluster->connect();

Enabling TCP keepalive

By default, TCP keepalive is disabled. It can be useful to make sure TCP connections are not silently dropped by a firewall or some other intermediary network device. You can enable it using Dse\Cluster\Builder::withTCPKeepalive().

<?php

// enable keepalive with a 10 second interval.

$cluster = Dse::cluster()
               ->withTCPKeepalive(10)
               ->build();
$session = $cluster->connect();

Authenticating via `PasswordAuthenticator`

The PHP Driver supports Apache Cassandra’s built-in password authentication mechanism. To enable it, use Dse\Cluster\Builder::withCredentials().

<?php

$cluster = Dse::cluster()
               ->withCredentials("username", "password")
               ->build();
$session = $cluster->connect();

Enabling SSL encryption

The PHP Driver supports SSL encryption of network connections. You must configure Dse\SSLOptions using the Dse\SSLOptions\Builder.

<?php

$ssl     = Dse::ssl()
               ->withTrustedCerts('node1.pem', 'node2.pem')
               ->withVerifyFlags(Dse::VERIFY_PEER_CERT | Dse::VERIFY_PEER_IDENTITY)
               ->withClientCert('client.pem')
               ->withPrivateKey('id_rsa', 'passphrase')
               ->build()
$cluster = Dse::cluster()
               ->withSSL($ssl)
               ->build();
$session = $cluster->connect();

Executing queries

You run CQL statements by passing them to Dse\Session::execute().

<?php

$result = $session->execute('SELECT keyspace_name, columnfamily_name FROM system.schema_columnfamilies');

foreach ($result as $row) {
    printf("The keyspace \"%s\" has a table \"%s\".\n", $row['keyspace_name'], $row['columnfamily_name']);
}

Parameterized queries

If you’re using Cassandra 2.0 or later you no longer have to build CQL strings when you want to insert a value in a query, there’s a new feature that lets you bind values with regular statements:

<?php

$session->execute(
    "UPDATE users SET age = ? WHERE user_name = ?",
    array('arguments' => array(41, 'Sam'))
);

For frequently executed queries, it’s strongly recommended to use prepared statements. As a rule of thumb, if your application is sending a request more than once, a prepared statement is almost always the right choice.

Prepared statements

The driver supports prepared statements. Use Dse\Session::prepare() to create a Dse\PreparedStatement object, and then call Dse\Session::execute().

<?php

$statement = $session->prepare('INSERT INTO users (username, email) VALUES (?, ?)');

$session->execute($statement, array(
    'arguments' => array('avalanche123', 'bulat.shakirzyanov@datastax.com')
));

A prepared statement can be run many times, but the CQL parsing will only be done once on each node. Use prepared statements for queries you run over and over again.

Executing statements in parallel

With fully asynchronous API, it is very easy to run queries in parallel:

<?php

$data = array(
    array(41, 'Sam'),
    array(35, 'Bob')
);

$statement = $session->prepare("UPDATE users SET age = ? WHERE user_name = ?");
$futures   = array();

// execute all statements in background
foreach ($data as $arguments) {
    $futures[] = $session->executeAsync($statement, array(
                     'arguments' => $arguments
                ));
}

// wait for all statements to complete
foreach ($futures as $future) {
    // we will not wait for each result for more than 5 seconds
    $future->get(5);
}

Note that it is not enough to simply create a Dse\Future by calling one of the *Async() methods, you must ensure that this future has enough time to be executed by calling Dse\Future::get().

Creating keyspaces and tables

There is no special facility for creating keyspaces and tables, they are created by executing CQL:

<?php

$createKeyspace = <<<EOD
CREATE KEYSPACE measurements
WITH replication = {
  'class': 'SimpleStrategy',
  'replication_factor': 1
}
EOD;

$createTable = <<<EOD
CREATE TABLE events (
  id INT,
  date DATE,
  comment VARCHAR,
  PRIMARY KEY (id)
)
EOD;

$session->execute($createKeyspace);
$session->execute('USE measurements');
$session->execute($createTable);

You can also ALTER keyspaces and tables, and you can read more about that in the CQL3 syntax documentation.

Batch statements

If you’re using Cassandra 2.0 or later you can build batch requests, either from simple or prepared statements. Batches must not contain any select statements, only INSERT, UPDATE and DELETE statements are allowed.

You can mix any combination of statements in a batch:

<?php

$batch = new Dse\BatchStatement();

$statement = $session->prepare("UPDATE users SET name = ? WHERE user_id = ?");
$batch->add($statement, array('Sue', 'unicorn31'));

$batch->add("UPDATE users SET age = 19 WHERE user_id = 'unicorn31'");

$batch->add(
    "INSERT INTO activity (user_id, what, when) VALUES (?, 'login', NOW())",
    array('unicorn31')
);

$session->execute($batch);

Batches can have one of three different types: logged, unlogged or counter, where logged is the default. Their exact semantics are defined in the Cassandra documentation, but this is how you specify which one you want:

<?php

$batch = new Dse\BatchStatement(Dse::BATCH_LOGGED);
$batch = new Dse\BatchStatement(Dse::BATCH_UNLOGGED);
$batch = new Dse\BatchStatement(Dse::BATCH_COUNTER);

Result paging

If you’re using Cassandra 2.0 or later you can page your query results.

By default, a page size of 5000 will be used, you can override the default page size via Dse\Cluster\Builder::withDefaultPageSize().

<?php

$cluster = Dse::cluster()
               ->withDefaultPageSize(200)
               ->build();
$session = $cluster->connect();

You can also override the page size on a per-execute basis by adding the page_size execution option to a call to Dse\Session.executeAsync or Dse\Session.execute:

<?php

$statement = "SELECT * FROM large_table WHERE id = 'partition_with_lots_of_data'";
$result    = $session->execute($statement, array('page_size' => 100));

while ($result) {
    foreach ($result as $row) {
        var_dump($row);
    }
    $result = $result->nextPage();
}

Consistency

You can specify the default consistency to use for statements execution when you create a new Dse\Cluster:

<?php

$cluster = Dse::cluster()
               ->withDefaultConsistency(Dse::CONSISTENCY_LOCAL_QUORUM)
               ->build();
$session = $cluster->connect();

Consistency can also be passed via execution options.

<?php

$session->execute(
    'SELECT * FROM users',
    array('consistency' => Dse::CONSISTENCY_LOCAL_QUORUM)
);

$statement = $session->prepare('SELECT * FROM users');
$session->execute($statement, array(
    'consistency' => Dse::CONSISTENCY_LOCAL_QUORUM
));

$batch = new Dse\BatchStatement();
$batch->add("UPDATE users SET email = 'sue@foobar.com' WHERE id = 'sue'");
$batch->add("UPDATE users SET email = 'tom@foobar.com' WHERE id = 'tom'");
$session->execute($batch, array(
    'consistency' => Dse::CONSISTENCY_LOCAL_QUORUM
));

Schema Metadata

The DataStax PHP driver exposes schema metadata via Dse\Schema object, available using Dse\Session::schema(). Schema metadata includes information about keyspace, tables and columns and it automatically kept up-to-date with the Cassandra cluster.

<?php

$schema = $session->schema();

foreach ($schema->keyspaces() as $keyspace) {
    printf("Keyspace: %s\n", $keyspace->name());
    printf("    Replication Strategy: %s\n", $keyspace->replicationClassName());
    printf("    Replication Options:\n");
    $options = $keyspace->replicationOptions();
    $keys    = $options->keys();
    $values  = $options->values();
    foreach (array_combine($keys, $values) as $key => $value) {
        printf("        %s: %s\n", $key, $value);
    }
    printf("    Durable Writes:       %s\n", $keyspace->hasDurableWrites() ? 'true' : 'false');

    foreach ($keyspace->tables() as $table) {
        printf("    Table: %s\n", $table->name());
        printf("        Comment:                    %s\n", $table->comment());
        printf("        Read Repair Chance:         %f\n", $table->readRepairChance());
        printf("        Local Read Repair Chance:   %f\n", $table->localReadRepairChance());
        printf("        GC Grace Seconds:           %d\n", $table->gcGraceSeconds());
        printf("        Caching:                    %s\n", $table->caching());
        printf("        Bloom Filter FP Chance:     %f\n", $table->bloomFilterFPChance());
        printf("        Memtable Flush Period Ms:   %d\n", $table->memtableFlushPeriodMs());
        printf("        Default Time To Live:       %d\n", $table->defaultTTL());
        printf("        Speculative Retry:          %s\n", $table->speculativeRetry());
        printf("        Index Interval:             %d\n", $table->indexInterval());
        printf("        Compaction Strategy:        %s\n", $table->compactionStrategyClassName());
        printf("        Populate IO Cache On Flush: %s\n", $table->populateIOCacheOnFlush() ? 'yes' : 'no');
        printf("        Replicate On Write:         %s\n", $table->replicateOnWrite() ? 'yes' : 'no');
        printf("        Max Index Interval:         %d\n", $table->maxIndexInterval());
        printf("        Min Index Interval:         %d\n", $table->minIndexInterval());

        foreach ($table->columns() as $column) {
            printf("        Column: %s\n", $column->name());
            printf("            Type:          %s\n", $column->type());
            printf("            Order:         %s\n", $column->isReversed() ? 'desc' : 'asc');
            printf("            Frozen:        %s\n", $column->isFrozen() ? 'yes' : 'no');
            printf("            Static:        %s\n", $column->isStatic() ? 'yes' : 'no');

            if ($column->indexName()) {
                printf("            Index:         %s\n", $column->indexName());
                printf("            Index Options: %s\n", $column->indexOptions());
            }
        }
    }
}

NOTE A new instance of Dse\Schema is returned each time Dse\Session::schema() is called. This instance is a simple value object and its information, such as keyspaces, tables and columns will not be kept up-to-date with the state of the cluster. In order to obtain the latest schema metadata, you have to call Dse\Session::schema() again.

Data Types

The PHP driver for Apache Cassandra supports a variety of datatypes.

You can also use the rich type metadata API to define and inspect types, as well as validate data objects.

The example below defines and creates a Dse\Map using Dse\Type interface.

<?php

$map = Dse\Type::map(Dse\Type::varchar(), Dse\Type::int())
           ->create('a', 1, 'b', 2, 'c', 3, 'd', 4);

var_dump(array_combine($map->keys(), $map->values()));

NOTE The create() method or various types validates and coerces provided values into the target type.

Logging

You can configure the location of the log file for the driver as well as the log level using the following php.ini settings:

[dse]
dse.log=syslog
dse.log_level=INFO

You can specify any file path as dse.log.

The special value syslog can be used to for the driver to use syslog for logging. Syslog is only supported on *nix systems.

The possible log levels are:

CRITICAL
ERROR
WARN
INFO
DEBUG
TRACE

Most of the logging will be when the driver connects and discovers new nodes, when connections fail and so on. The logging is designed to not cause much overhead and only relatively rare events are logged (e.g. normal requests are not logged).

Architecture

The PHP Driver follows the architecture of the C/C++ Driver that it wraps.

Persistent sessions

By default, the driver uses persistent sessions to prevent each request from creating completely new TCP connections to a DSE cluster. You can toggle this functionality using Dse\Cluster\Builder::withPersistentSessions

Core

Usage

Specifying addresses of DSE nodes

Discovering nodes in the cluster

Persistent sessions

Configuring load balancing policy

Setting protocol version

Tweaking driver’s throughput

Disabling TCP nodelay

Enabling TCP keepalive

Authenticating via PasswordAuthenticator

Enabling SSL encryption

Executing queries

Parameterized queries

Prepared statements

Executing statements in parallel

Creating keyspaces and tables

Batch statements

Result paging

Consistency

Schema Metadata

Data Types

Logging

Architecture

Persistent sessions

Contents

Authenticating via `PasswordAuthenticator`