Node.js driver for Apache Cassandra. This driver works exclusively with the Cassandra Query Language version 3 (CQL3) and Cassandra's native protocol.
$ npm install cassandra-driver
- Nodes discovery
- Configurable load balancing
- Transparent failover
- Tunability
- Row streaming
- Prepared statements and query batches
var cassandra = require('cassandra-driver');
var client = new cassandra.Client({contactPoints: ['host1', 'host2'], keyspace: 'ks1'});
var query = 'SELECT email, last_name FROM user_profiles WHERE key=?';
client.execute(query, ['guy'], function(err, result) {
console.log('got user profile with email ' + result.rows[0].email);
});You can use the project Mailing list or create a ticket on the Jira issue tracker.
- SSL support
- Automatic paging
- Token-aware load balancing policy
The Client maintains a pool of opened connections to the hosts to avoid several time-consuming steps that are involved with the setup of a CQL binary protocol connection (socket connection, startup message, authentication, ...).
Usually you need one Client instance per Cassandra cluster.
Constructs a new client object.
Connects / warms up the pool.
It ensures the pool is connected. It is not required to call it, internally the driver will call to connect when executing a query.
The optional callback parameter will be executed when the pool is connected. If the pool is already connected, it will be called instantly.
The query is the cql query to execute, with ? marker for parameter placeholder.
To prepare an statement, provide {prepare: true} in the queryOptions. It will prepare (the first time) and execute the prepared statement.
Using prepared statements increases performance compared to plain executes, especially for repeated queries. It has the additional benefit of providing metadata of the parameters to the driver, allowing better type mapping between javascript and Cassandra without the need of additional info (hints) from the user.
In the case the query is already being prepared on a host, it queues the executing of a prepared statement on that host until the preparing finished (the driver will not issue a request to prepare statement more than once).
callback should take two arguments err and result.
queryOptions is an Object that may contain the following optional properties:
prepare: if set, prepares the query (once) and executes the prepared statement.consistency: the consistency level for the operation (defaults to one). The possible consistency levels are defined indriver.types.consistencies.fetchSize: The maximum amount of rows to be retrieved per request (defaults to 5000)
var query = 'UPDATE user_profiles SET birth=? WHERE key=?';
var queryOptions = {
consistency: cassandra.types.consistencies.quorum,
prepare: true};
var params = [new Date(1942, 10, 1), 'jimi-hendrix'];
client.execute(query, params, queryOptions, function(err) {
if (err) return console.log('Something went wrong', err);
console.log('Row updated on the cluster');
});Executes a query and streams the rows as soon as they are received.
It executes rowCallback(n, row) per each row received, where n is the index of the row.
It executes callback(err, rowLength) when all rows have been received or there is an error retrieving the row.
client.eachRow('SELECT time, temperature FROM temperature WHERE station_id=', ['abc'],
function(n, row) {
//the callback will be invoked per each row as soon as they are received
minTemperature = Math.min(row.temperature, minTemperature);
},
function (err, rowLength) {
if (err) console.error(err);
console.log('%d rows where returned', rowLength);
}
);Executes batch of queries on an available connection, where queries is an Array of string containing the CQL queries
or an Array of objects containing the query and the parameters.
callback should take two arguments err and result.
#####Example: Update multiple column families
var userId = cassandra.types.uuid();
var messageId = cassandra.types.uuid();
var queries = [
{
query: 'INSERT INTO users (id, name) values (?, ?)',
params: [userId, 'jimi-hendrix']
},
{
query: 'INSERT INTO messages (id, user_id, body) values (?, ?, ?)',
params: [messageId, userId, 'Message from user jimi-hendrix']
}
];
var queryOptions: { consistency: cassandra.types.consistencies.quorum };
client.batch(queries, queryOptions, function(err) {
if (err) return console.log('The rows were not inserted', err);
console.log('Data updated on cluster');
});Executes the query and returns a Readable Streams2 object in objectMode.
When a row can be read from the stream, it will emit a readable event.
It can be piped downstream and provides automatic pause/resume logic (it buffers when not read).
It executes callback(err) when all rows have been received or there is an error retrieving the row.
client.stream('SELECT time1, value1 FROM timeseries WHERE key=', ['key123'])
.on('readable', function () {
//readable is emitted as soon a row is received and parsed
var row;
while (row = this.read()) {
console.log('time %s and value %s', row.time1, row.value1);
}
})
.on('end', function () {
//stream ended, there aren't any more rows
})
.on('error', function (err) {
//Something went wrong: err is a response error from Cassandra
});Disconnects the pool.
Closes all connections in the pool. Normally, it should be called once in your application lifetime.
The optional callback parameter will be executed when the pool is disconnected.
The types module contains field definitions that are useful to interact with Cassandra nodes.
Object that contains the CQL consistencies defined as properties. For example: consistencies.one, consistencies.quorum, ...
Object that contains all the CQL data types defined as properties.
Object containing all the possible response error codes returned by Cassandra defined as properties.
Constructs a 64-bit two's-complement integer. See Long API Documentation.
Function to generate a uuid v1. It uses node-uuid module to generate and accepts the same arguments.
Function to generate a uuid v4. It uses node-uuid module to generate and accepts the same arguments.
The policies module contains load balancing, retry and reconnection classes.
Load balancing policies lets you decide which node of the cluster will be used for each query.
- RoundRobinPolicy: This policy yield nodes in a round-robin fashion (default).
- DCAwareRoundRobinPolicy: A data-center aware round-robin load balancing policy. This policy provides round-robin queries over the node of the local data center. It also includes in the query plans returned a configurable number of hosts in the remote data centers, but those are always tried after the local nodes.
To use it, you must provide load balancing policy the instance in the clientOptions of the Client instance.
//You can specify the local dc relatively to the node.js app
var localDc = 'us-east';
var lbPolicy = new cassandra.policies.loadBalancing.DCAwareRoundRobinPolicy(localDc);
var clientOptions = {
policies: {loadBalancing: loadBalancingPolicy}
};
var client = new Client(clientOptions);Load balancing policy classes inherit from LoadBalancingPolicy. If you want make your own policy, you should use the same base class.
Retry policies lets you configure what the driver should do when there certain types of exceptions from Cassandra are received.
- RetryPolicy: Default policy and base class for retry policies. It retries once in case there is a read or write timeout and the alive replicas are enough to satisfy the consistency level.
Reconnection policies lets you configure when the driver should try to reconnect to a Cassandra node that appears to be down.
- ConstantReconnectionPolicy: It waits a constant time between each reconnection attempt.
- ExponentialReconnectionPolicy: waits exponentially longer between each reconnection attempt, until maximum delay is reached.
The auth module provides the classes required for authentication.
- PlainTextAuthProvider: Authentication provider for Cassandra's PasswordAuthenticator.
Using an authentication provider on an auth-enabled Cassandra cluster:
var authProvider = new cassandra.auth.PlainTextAuthProvider('my_user', 'p@ssword1!');
//Setting the auth provider in the clientOptions
var client = new Client({authProvider: authProvider});Authenticator provider classes inherit from AuthProvider. If you want to create your own auth provider, use the that as your base class.
Instances of Client() are EventEmitter and emit log events:
client.on('log', function(level, className, message, furtherInfo) {
console.log('log event: %s -- %s', level, message);
});The level being passed to the listener can be verbose, info, warning or error.
See documentation on CQL data types and ECMAScript types.
This driver is based on the original work of Jorge Bay on node-cassandra-cql and adds a series of advanced features that are common across all other DataStax drivers for Apache Cassandra.
The development effort to provide an up to date, high performance, fully featured Node.js Driver for Apache Cassandra will continue on this project, while node-cassandra-cql will be discontinued.
Copyright 2014 DataStax
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.