About
JugglingDB is cross-db ORM for nodejs, providing
common interface to access most popular database formats. Currently
supported are: mysql, sqlite3, postgres, mongodb, redis and
js-memory-storage (yep, self-written engine for test-usage only). You can add
your favorite database adapter, checkout one of the existing adapters to learn
how.
Jugglingdb also works on client-side (using WebService and Memory adapters),
which allows to write rich client-side apps talking to server using JSON API.
Installation
npm install jugglingdb
and you should install appropriate adapter, for example for redis:
npm install jugglingdb-redis-hq
check following list of available adapters
JugglingDB adapters
Participation
If you want to create your own jugglingdb adapter, you should publish your
adapter package with name jugglingdb-ADAPTERNAME
. Creating adapter is simple,
check jugglingdb/redis-adapter for example. JugglingDB core
exports common tests each adapter should pass, you could create your adapter in
TDD style, check that adapter pass all tests defined in test/common_test.js
.
Usage
var Schema = require('jugglingdb').Schema;
var schema = new Schema('redis', {port: 6379});
var Post = schema.define('Post', {
title: { type: String, length: 255 },
content: { type: Schema.Text },
date: { type: Date, default: function () { return new Date;} },
timestamp: { type: Number, default: Date.now },
published: { type: Boolean, default: false, index: true }
});
var User = schema.define('User', {
name: String,
bio: Schema.Text,
approved: Boolean,
joinedAt: Date,
age: Number
}, {
restPath: '/users'
});
var Group = schema.define('Group', {name: String});
User.prototype.getNameAndAge = function () {
return this.name + ', ' + this.age;
};
schema.models.User;
schema.models.Post;
SEE schema(3) for details schema usage.
User.hasMany(Post, {as: 'posts', foreignKey: 'userId'});
Post.belongsTo(User, {as: 'author', foreignKey: 'userId'});
User.hasAndBelongsToMany('groups');
schema.automigrate();
var user = new User;
user.save(function (err) {
var post = user.posts.build({title: 'Hello world'});
post.save(console.log);
});
var user = User();
user.save(...);
new Post({ published: 0, userId: 1 });
Post.create();
Post.all();
Post.all({ where: { userId: user.id }, order: 'id', limit: 10, skip: 20 });
user.posts(cb)
Post.findOne({ where: { published: true }, order: 'date DESC' });
user.posts.build({ published: 1 });
user.posts.create();
User.find(1);
User.fetch(1)
.then(user => console.log('found user', user))
.catch(err => console.error('can not fetch user with id 1:', err));
User.count([conditions])
user.destroy();
User.destroyAll();
Post.bulkUpdate({ update: { published: 0 }, where: { id: [1, 2, 3] }});
Post.update(1, { published: 1 });
SEE model(3) for more information about
jugglingdb Model API. Or man jugglingdb-model
in terminal.
User.validatesPresenceOf('name', 'email')
User.validatesLengthOf('password', {min: 5, message: {min: 'Password is too short'}});
User.validatesInclusionOf('gender', {in: ['male', 'female']});
User.validatesExclusionOf('domain', {in: ['www', 'billing', 'admin']});
User.validatesNumericalityOf('age', {int: true});
User.validatesUniquenessOf('email', {message: 'email is not unique'});
user.isValid(function (valid) {
if (!valid) {
user.errors
}
})
SEE ALSO jugglingdb-validations(3) or
man jugglingdb-validations
in terminal. Validation tests: ./test/validations.test.js
Hooks
The following hooks supported:
- afterInitialize
- beforeCreate
- afterCreate
- beforeSave
- afterSave
- beforeUpdate
- afterUpdate
- beforeDestroy
- afterDestroy
- beforeValidate
- afterValidate
Each callback is class method of the model, it should accept single argument: next
, this is callback which should be called after end of the hook. Except afterInitialize
because this method is syncronous (called after new Model
).
During beforehooks the next
callback accepts one argument, which is used to terminate flow. The argument passed on as the err
parameter to the API method callback.
Object lifecycle:
var user = new User;
user.save(callback);
user.updateAttribute('email', 'email@example.com', callback);
user.destroy(callback);
User.create(data, callback);
SEE jugglingdb-hooks or type this command
in your fav terminal: man jugglingdb-hooks
. Also check tests for usage
examples: ./test/hooks.test.js
Your own database adapter
To use custom adapter, pass it's package name as first argument to Schema
constructor:
var mySchema = new Schema('mycouch', {host:.., port:...});
In that case your adapter should be named as 'jugglingdb-mycouch' npm package.
Testing [outdated]
TODO: upd this section
Core of jugglingdb tests only basic features (database-agnostic) like
validations, hooks and runs db-specific tests using memory storage. It also
exports complete bucket of tests for external running. Each adapter should run
this bucket (example from jugglingdb-redis
):
var jdb = require('jugglingdb'),
Schema = jdb.Schema,
test = jdb.test;
var schema = new Schema(__dirname + '/..', {host: 'localhost', database: 1});
test(module.exports, schema);
Each adapter could add specific tests to standart bucket:
test.it('should do something special', function (test) {
test.done();
});
Or it could tell core to skip some test from bucket:
test.skip('name of test case');
To run tests use this command:
npm test
Before running make sure you've installed package (npm install
) and if you
running some specific adapter tests, ensure you've configured database
correctly (host, port, username, password).
Contributing
If you have found a bug please try to write unit test before reporting. Before
submit pull request make sure all tests still passed. Check
roadmap, github issues if you want to
help. Contribution to docs highly appreciated. Contents of man pages and
http://1602.github.com/jugglingdb/ generated from md files stored in this repo at ./docs repo
MIT License
Copyright (C) 2011 by Anatoliy Chakkaev <mail [åt] anatoliy [døt] in>
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.