Initial (functional) commit of node.dbslayer.js!

Author: rauchg

README.md

@@ -0,0 +1,75 @@
+node.dbslayer.js
+=================
+
+node.dbslayer.js is a very basic and easy-to-use library to connect to a DBSlayer server, which effectively provides non-blocking and scalable MySQL support for Node.JS. 
+
+DBSlayer benefits include:
+
+* It's Node.JS/V8/JavaScript friendly, since the the messages are delivered in JSON format over HTTP.
+
+* Developed by the New York Times, it's designed with scalability in mind, doing connection pooling for you. This is what makes DBSlayer arguably better than implementing an async MySQL client directly into Node (through mysac for example).
+
+Requirements
+------------
+
+
+* [Node.js](http://nodejs.org/) (tested with v0.1.21)
+* [DBSlayer](http://code.nytimes.com/projects/dbslayer/) (tested with beta-12)
+
+How to Use
+----------
+	
+From your node.js script, require the `dbslayer` package
+
+	var db = require('dbslayer');
+
+Initialize a connection
+
+	var connection = db.Server('localhost', 9090);
+	
+and then perform a query:
+
+	connection.query("SELECT * FROM table");
+	
+To be truly non-blocking, `Server::fetch` has to return a promise and not the result immediately. This means that in order to be able to perform queries in a designated order or access the result, you'll have to use callbacks:
+
+	connection.query("SELECT * FROM TABLE").addCallback(function(result){
+		// insert ready
+		for (var i = 0, l = result.rows.length; )
+	});
+	
+If you want to capture MySQL errors, subscribe to the 'error' event
+
+	connection.query("...").addErrback(function(){
+		alert('mysql error!');
+	});
+	
+Aside from query, the commands `stat`, `client_info`, `host_info`, `server_version` and `client_version` are available, which provide the corresponding information.
+
+Installing DBSlayer
+-------------------
+
+Compile it according to the instructions [here](http://code.nytimes.com/projects/dbslayer/wiki).
+
+Then create a /etc/dbslayer.conf file defining a database. Here I'm defining the `cool` server which connects to my `mysql` database
+
+	[cool]
+	database=mysql
+	host=localhost
+	user=root
+	pass=1234
+	
+Then run DBSlayer for that connection:
+
+	dbslayer -c /etc/dbslayer.conf -s cool
+	
+Test it by running test.js like this:
+
+	node test.js "SELECT * FROM help_category"
+	
+If you get a bunch of entries like in this [screenshot](http://cld.ly/9aosh) then dbslayer (and node.dbslayer.js) work!
+
+Author
+------
+
+Guillermo Rauch <[http://devthought.com](http://devthought.com)>

dbslayer.js

@@ -0,0 +1,62 @@
+/*
+---
+name: dbslayer.js
+
+description: Interface to DBSlayer for Node.JS
+
+author: [Guillermo Rauch](http://devthought.com)
+...
+*/
+
+var sys = require('sys'),
+    http = require('http'),
+    
+    booleanCommands = ['STAT', 'CLIENT_INFO', 'HOST_INFO', 'SERVER_VERSION', 'CLIENT_VERSION'],
+
+Server = this.Server = function(host, port, timeout){
+  this.host = host || 'localhost';
+  this.port = port || 9090;
+  this.timeout = timeout;
+};
+
+Server.prototype.fetch = function(object, key){
+  var connection = http.createClient(this.port, this.host),
+      request = connection.get('/db?' + escape(JSON.stringify(object)), {'host': this.host}),
+      promise = new process.Promise();
+  
+  promise.timeout(this.timeout);
+
+  request.finish(function(response){
+    response.addListener('body', function(data){  
+      try {
+        var object = JSON.parse(data);
+      } catch(e){
+        return promise.emitError(e);
+      }      
+      
+      if (object.MYSQL_ERROR !== undefined){
+        promise.emitError(object.MYSQL_ERROR, object.MYSQL_ERRNO);
+      } else if (object.ERROR !== undefined){
+        promise.emitError(object.ERROR);
+      } else {
+        promise.emitSuccess(key ? object[key] : object);
+      }      
+    });
+  });
+  
+  return promise;
+};
+
+Server.prototype.query = function(query){
+  return this.fetch({SQL: query}, 'RESULT');
+};
+
+for (var i = 0, l = booleanCommands.length; i < l; i++){
+  Server.prototype[booleanCommands[i].toLowerCase()] = (function(command){
+    return function(){
+      var obj = {};
+      obj[command] = true;
+      return this.fetch(obj, command);
+    };
+  })(booleanCommands[i]);
+}

test.js

@@ -0,0 +1,43 @@
+/*
+---
+name: tools.js
+
+description: <
+  This is a demonstration of how dbslayer.js can be used.
+  It takes three parameters from the SQL query, a host
+
+author: [Guillermo Rauch](http://devthought.com)
+...
+*/
+
+var sys = require('sys')
+    dbslayer = require('./dbslayer'),    
+    sql = process.ARGV[2],
+    db = new dbslayer.Server();
+    
+if (!sql){
+  sys.puts('Please provide the SQL query');
+  return;
+}
+
+db.query(sql)
+  // on success
+  .addCallback(function(result){
+    sys.puts('-------------------------');        
+    for (var i = 0, l = result.ROWS.length; i < l; i++){
+      sys.puts('Row ' + i + ': ' + result.ROWS[i].join(' '));
+    }
+  })
+  
+  // on error :(
+  .addErrback(function(error, errno){
+    sys.puts('-------------------------');        
+    sys.puts('MySQL error (' + (errno || '') + '): ' + error);
+  });
+
+['stat', 'client_info', 'host_info', 'server_version', 'client_version'].forEach(function(command){  
+  db[command]().addCallback(function(result){
+    sys.puts('-------------------------');    
+    sys.puts(command.toUpperCase() + ' ' + result);
+  });
+});