orm

NodeJS ORM

Warning

If you're using the latest version (and always updating when possible), be very carefull, because I'm going to change a lot of things preparing for 0.2.0. Here's some of the planned changes:

• Strictly use (I mean always) the callback "standard" cb(err, ..);
• Force using at least node v0.6;

About

Node-ORM is a NodeJS module for multiple databases using Object-Relational Mapping with some cool features like validators and hooks. New features are added by suggestion issues or when I remember I need something. I make a strong effort not to change the API, but sometimes it can happen. If you don't want to get into trouble I suggest you to define your package.json (in project) to use a specific version of ORM (and not >= x.y.z).

Installing

Install using NPM:

npm install orm

Connecting to a Database (MySQL in the example)

You can check the API for a more detailed overview.

var orm = require("orm");
var db = orm.connect("mysql://username:password@hostname/database", function (success, db) {
    if (!success) {
        console.log("Could not connect to database!");
        return;
    }

    // you can now use db variable to define models
});

Connecting via raw database API

var orm = require("orm");
var mysql = require("mysql");
var client = mysql.createClient({
    user: 'root',
    password: 'root'
});
var db = orm.connect("mysql", client, function (success, db) {
    // same as above...
});

This allows you to generate your own database objects that conform to the following postgres and mysql libraries:

• Mysql: https://github.com/felixge/node-mysql
• Postgres: https://github.com/brianc/node-postgres

Defining a model

var Person = db.define("person", {
    "name"   : { "type": "string" },
    "surname": { "type": "string", "default": "" },
    "age"    : { "type": "int" }
}, {
    "methods" : {
        "fullName" :function () {
            return this.name + " " + this.surname;
        }
    }
});

Adding associations

Person.hasOne("father", Person);
// or just
Person.hasOne("mother"); // defaults to same model

Person.hasMany("friends", Person, "friend"); // will create a table "person_friends" with 2 fields (person_id and friend_id)

Creating the model on the database

Person.sync();

Note: sync() only creates tables at the moment; table modifications will be added in an upcoming version.

Creating and using a record

var John = new Person({
	"name"		: "John",
	"surname"	: "Doe",
	"age"		: 20
});
console.log("Hello, my name is " + John.fullName() + " and I'm " + John.age + " years old");

Saving record to database

John.save(function (err, JohnCopy) {
	if (!err) {
		console.log("Saved! ID=" + John.id); // you can use John or JohnCopy
	} else {
		console.log("Something went wrong...");
		console.dir(err);
	}
});

Changing associations

I think an example is better to explain.

John.setFather(Jeremy, function () {
	John.setMother(Jane, function () {
		John.addFriends(Jeremy, Jane, function () {
			console.log("Jeremy and Jane (John's parents) are now his friends too");
		});
	});
});

If you want there's also this methods:

John.getFather(function (JohnFather) {
	console.log("John's father is " + JohnFather.name);
});
John.unsetMother(function () {
	console.log("John has no mother now!");
});
John.removeFriends(Jeremy, Jane, function () {
	console.log("John has no friends now!");
});
// or just don't send any, all will be removed
John.removeFriends(function () {
	console.log("John has no friends now!");
});

Database Support

Currently this module supports the following database types:

1. MySQL
2. PostgreSQL
3. MongoDB (alpha)

Supported Types

This values are still just supported for .sync() (table creations), not for other instance operations like .save() (yet).

Name	Description	MySQL Type	PostgreSQL Type	MongoDB Type
string	Small text	VARCHAR(255)	VARCHAR(255)	String
text	Big text	TEXT	TEXT	String
int, integer, num, number	Signed integer	INT	INTEGER	Int
float	Floating point number	FLOAT	REAL	Float
bool, boolean	True or false value	TINYINT(1) (true=1, false=0)	BOOLEAN	Boolean
date	Date/time value (seconds precision)	DATETIME	TIMESTAMP	?
data	Binary data	BLOB	BYTEA	String
enum	Enumerated value	ENUM	ENUM	String
struct, object	Generic (and simple) object	TEXT (saved as JSON)	TEXT (saved as JSON)	Object