Tutorial: Getting Started with the NoSQL JavaScript / Node.js API for MySQL Cluster
- by Mat Keep
Tutorial authored by Craig Russell and JD Duncan
The MySQL Cluster team are working on a new NoSQL JavaScript connector for MySQL. The objectives are simplicity and high performance for JavaScript users:
- allows end-to-end JavaScript development, from the browser to the server and now to the world's most popular open source database
- native "NoSQL" access to the storage layer without going first through SQL transformations and parsing.
Node.js is a complete web platform built around JavaScript designed to deliver millions of client connections on commodity hardware. With the MySQL NoSQL Connector for JavaScript, Node.js users can easily add data access and persistence to their web, cloud, social and mobile applications.
While the initial implementation is designed to plug and play with Node.js, the actual implementation doesn't depend heavily on Node, potentially enabling wider platform support in the future.
Implementation
The architecture and user interface of this connector are very different from other MySQL connectors in a major way: it is an asynchronous interface that follows the event model built into Node.js.
To make it as easy as possible, we decided to use a domain object model to store the data. This allows for users to query data from the database and have a fully-instantiated object to work with, instead of having to deal with rows and columns of the database. The domain object model can have any user behavior that is desired, with the NoSQL connector providing the data from the database.
To make it as fast as possible, we use a direct connection from the user's address space to the database. This approach means that no SQL (pun intended) is needed to get to the data, and no SQL server is between the user and the data.
The connector is being developed to be extensible to multiple underlying database technologies, including direct, native access to both the MySQL Cluster "ndb" and InnoDB storage engines.
The connector integrates the MySQL Cluster native API library directly within the Node.js platform itself, enabling developers to seamlessly couple their high performance, distributed applications with a high performance, distributed, persistence layer delivering 99.999% availability.
The following sections take you through how to connect to MySQL, query the data and how to get started.
Connecting to the database
A Session is the main user access path to the database. You can get a Session object directly from the connector using the openSession function:
var nosql = require("mysql-js");
var dbProperties = {
"implementation" : "ndb",
"database" : "test"
};
nosql.openSession(dbProperties, null, onSession);
The openSession function calls back into the application upon creating a Session. The Session is then used to create, delete, update, and read objects.
Reading data
The Session can read data from the database in a number of ways. If you simply want the data from the database, you provide a table name and the key of the row that you want. For example, consider this schema:
create table employee (
id int not null primary key,
name varchar(32),
salary float
) ENGINE=ndbcluster;
Since the primary key is a number, you can provide the key as a number to the find function.
function onSession = function(err, session) {
if (err) {
console.log(err);
... error handling
}
session.find('employee', 0, onData);
};
function onData = function(err, data) {
if (err) {
console.log(err);
... error handling
}
console.log('Found: ', JSON.stringify(data));
... use data in application
};
If you want to have the data stored in your own domain model, you tell the connector which table your domain model uses, by specifying an annotation, and pass your domain model to the find function.
var annotations = new nosql.Annotations();
function Employee = function(id, name, salary) {
this.id = id;
this.name = name;
this.salary = salary;
this.giveRaise = function(percent) {
this.salary *= percent;
}
};
annotations.mapClass(Employee, {'table' : 'employee'});
function onSession = function(err, session) {
if (err) {
console.log(err);
... error handling
}
session.find(Employee, 0, onData);
};
Updating data
You can update the emp instance in memory, but to make the raise persistent, you need to write it back to the database, using the update function.
function onData = function(err, emp) {
if (err) {
console.log(err);
... error handling
}
console.log('Found: ', JSON.stringify(emp));
emp.giveRaise(0.12); // gee, thanks!
session.update(emp); // oops, session is out of scope here
};
Using JavaScript can be tricky because it does not have the concept of block scope for variables. You can create a closure to handle these variables, or use a feature of the connector to remember your variables.
The connector api takes a fixed number of parameters and returns a fixed number of result parameters to the callback function. But the connector will keep track of variables for you and return them to the callback. So in the above example, change the onSession function to remember the session variable, and you can refer to it in the onData function:
function onSession = function(err, session) {
if (err) {
console.log(err);
... error handling
}
session.find(Employee, 0, onData, session);
};
function onData = function(err, emp, session) {
if (err) {
console.log(err);
... error handling
}
console.log('Found: ', JSON.stringify(emp));
emp.giveRaise(0.12); // gee, thanks!
session.update(emp, onUpdate); // session is now in scope
};
function onUpdate = function(err, emp) {
if (err) {
console.log(err);
... error handling
}
Inserting data
Inserting data requires a mapped JavaScript user function (constructor) and a session. Create a variable and persist it:
function onSession = function(err, session) {
var data = new Employee(999, 'Mat Keep', 20000000);
session.persist(data, onInsert);
}
};
Deleting data
To remove data from the database, use the session remove function. You use an instance of the domain object to identify the row you want to remove. Only the key field is relevant.
function onSession = function(err, session) {
var key = new Employee(999);
session.remove(Employee, onDelete);
}
};
More extensive queries
We are working on the implementation of more extensive queries along the lines of the criteria query api. Stay tuned.
How to evaluate
The MySQL Connector for JavaScript is available for download from labs.mysql.com. Select the build:
MySQL-Cluster-NoSQL-Connector-for-Node-js
You can also clone the project on GitHub
Since it is still early in development, feedback is especially valuable (so don't hesitate to leave comments on this blog, or head to the MySQL Cluster forum). Try it out and see how easy (and fast) it is to integrate MySQL Cluster into your Node.js platforms.
You can learn more about other previewed functionality of MySQL Cluster 7.3 here
