loopback-datasource-juggler/README.md

## About

JugglingDB - cross-db ORM, providing common ORM to access most popular database formats. Currently supported: mysql, mongodb, redis, neo4j and js-memory-storage (yep, self-written engine for test-usage only). You can add your favorite database adapter, checkout one of existing adapters to learn how, it's super-easy, I guarantee.

## Installation

    git clone git://github.com/1602/jugglingdb.git

## Usage

```javascript
var Schema = require('./juggling').Schema;
var s = new Schema('redis');
// define models
var Post = schema.define('Post', {
    title:     { type: String, length: 255 },
    content:   { type: Schema.Text },
    date:      { type: Date,    detault: Date.now },
    published: { type: Boolean, default: false }
});
var User = schema.define('User', {
    name:         String,
    bio:          Text,
    approved:     Boolean,
    joinedAt:     Date,
    age:          Number
});

// setup relationships
User.hasMany(Post,   {as: 'posts',  foreignKey: 'userId'});
// creates instance methods:
// user.posts(conds)
// user.buildPost(data) // like new Post({userId: user.id});
// user.createPost(data) // build and save

Post.belongsTo(User, {as: 'author', foreignKey: 'userId'});
// creates instance methods:
// post.author(callback) -- getter when called with function
// post.author() -- sync getter when called without params
// post.author(user) -- setter when called with object

s.automigrate(); // required only for mysql NOTE: it will drop User and Post tables

// work with models:
var user = new User;
user.save(function (err) {
    var post = user.buildPost({title: 'Hello world'});
    post.save(console.log);
});

// Common API methods

// just instantiate model
new Post
// save model (of course async)
Post.create(cb);
// all posts
Post.all(cb)
// all posts by user
Post.all({userId: user.id});
// the same as prev
user.posts(cb)
// same as new Post({userId: user.id});
user.buildPost
// save as Post.create({userId: user.id}, cb);
user.createPost(cb)
// find instance by id
User.find(1, cb)
// count instances
User.count(cb)
// destroy instance
user.destroy(cb);
// destroy all instances
User.destroyAll(cb);
```

Read the tests for usage examples: ./test/common_test.js

## Your own database adapter

To use custom adapter, pass it package name as first argument to Schema constructor:

    mySchema = new Schema('couch-db-adapter', {host:.., port:...});

Make sure, your adapter can be required (just put it into ./node_modules):

    require('couch-db-adapter');

## Running tests

All tests written using nodeunit:

    nodeunit test/common_test.js

If you run this line, of course it will fall, because it requres different databases to be up and running, but you can use js-memory-engine out of box! Specify ONLY env var:

    ONLY=memory nodeunit test/common_test.js

of course, if you have redis running, you can run

    ONLY=redis nodeunit test/common_test.js

## Package structure

Now all common logic desribed in ./index.js, and database-specific stuff in ./lib/*.js. It super-tiny, yep?

## Project status

This project written in one weekend (1,2 oct 2011), and of course it not pretend to be preduction-ready, but I plan to use this project as default ORM for RailwayJS in nearest future. So, if you familiar with some database engines - please help me to improve adapter for that database.

For example, I know, mysql implementation sucks now, 'cause I'm not digging too deep into SequelizeJS code, and I think would be better to replace sequelize with something low-level in nearest future, such as `mysql` package from npm.

## Contributing

If you have found a bug please write unit test, and make sure all other tests still pass before pushing code to repo.

## Roadmap

### Common:

+ validations
+ -before and -after hooks on save, update, destroy
+ default values
+ more relationships stuff
+ docs

### Databases:

+ riak
+ couchdb
+ low-level mysql
+ postgres
+ sqlite

## License

MIT