node-cassandra-cql is a Node.js CQL driver for Apache Cassandra CQL3 binary protocol.
CQL is a query language for Apache Cassandra.
$ npm install node-cassandra-cql
- Connection pooling to multiple hosts
- Parameters in queries (even for sets/lists/maps collections)
- Plain Old Javascript: no need to generate thrift files
- Get cell by column name:
row.get('first_name') - Bigints support (using node-int64)
// Creating a new connection pool to multiple hosts.
var Client = require('node-cassandra-cql').Client;
var hosts = ['host1:9042', 'host2:9042', 'host3', 'host4'];
var cqlClient = new Client({hosts: hosts, keyspace: 'Keyspace1'});Client() accepts an object with these slots, only hosts is required:
hosts: String list in host:port format. Port is optional (defaults to 9042).
keyspace: Name of keyspace to use.
username: User for authentication.
password: Password for authentication.
version: Currently only '3.0.0' is supported.
staleTime: Time in milliseconds before trying to reconnect.
maxExecuteRetries: Maximum amount of times an execute can be retried
using another connection, in case the server is unhealthy.
getAConnectionTimeout: Maximum time in milliseconds to wait for a connection from the pool.
Queries are performed using the execute() method. For example:
// Reading
cqlClient.execute('SELECT key, email, last_name FROM user_profiles WHERE key=?', ['jbay'],
function(err, result) {
if (err) console.log('execute failed');
else console.log('got user profile with email ' + result.rows[0].get('email'));
}
);
// Writing
cqlClient.execute('UPDATE user_profiles SET email=? WHERE key=?', ['my@email.com', 'jbay'],
types.consistencies.quorum,
function(err) {
if (err) console.log("failure");
else console.log("success");
}
);execute() accepts the following arguments
cqlQuery : The cql query to execute, with ? as parameters
arguments: Array of arguments that will replace the ? placeholders, can be null.
consistency : The level of consistency.
callback : The callback function with 2 arguments: err and result
When you are finished with a Client instance, call shutdown(callback).
Shutting down the pool prevents further work from being enqueued, and closes all
open connections after pending requests are complete.
// Shutting down a pool
cqlClient.shutdown(function() { console.log("connection pool shutdown"); });The Client maintains a pool of opened connections to the hosts to avoid several time-consuming steps that are involed with the set up of a CQL binary protocol connection (socket connection, startup message, authentication, ...).
If you want to get lower level fine-grained control you could use the Connection class.
var Connection = require('node-cassandra-cql').Connection;
var con = new Connection({host:'host1', port:9042, username:'cassandra', password:'cassandra'});
con.open(function(err) {
if(err) {
console.error(err);
}
else {
var query = 'SELECT key, email, last_name FROM user_profiles WHERE key=?';
con.execute(query, ['jbay'], function(err, result){
if (err) console.log('execute failed');
else console.log('got user profile with email ' + result.rows[0].get('email'));
con.close();
});
}
});Instances of Client() and Connection() are EventEmitter's and emit log events:
var Connection = require('node-cassandra-cql').Connection;
var con = new Connection({host:'host1', port:9042, keyspace:'Keyspace1'});
con.on('log', function(level, message) {
console.log('log event: %s -- %j', level, message);
});The level being passed to the listener can be info or error.
Cassandra's bigint data types are parsed as int64.
List / Set datatypes are encoded from / decoded to Javascript Arrays.
Map datatype are encoded from / decoded to Javascript objects with keys as props.
Decimal and Varint are not parsed yet, they are yielded as byte Buffers.
node-cassandra-cql is distributed under the MIT license.
Feel free to join in if you feel like helping this project progress!
FrameReader and FrameWriter are based on node-cql3's FrameBuilder and FrameParser.