Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

NodeJS Object-Relational Mapping

tree: 64c26e6ecb

Fetching latest commit…

Cannot retrieve the latest commit at this time

README.md

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:

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
Something went wrong with that request. Please try again.