Getting started with JSONDB

Installation

JSONDB is installable through npm:

 npm install jsondb-js

You can also download JSONDB on github and install it yourself: JSONDB on Github

Load JSONDB

var JSONDB = require('jsondb-js');
var jdb = new JSONDB();

Create a server

When JSONDB is instantiated, you can connect to a server. If you haven't created a server, you can create it using JSONDB::createServer()

jdb.createServer('server_name', 'username', 'password', connect);

The parameter connect is an optional boolean used to set if JSONDB have to be connected to the server after the creation. If it's set to true, you have to assign the returned connection handler to a variable:

var database = jdb.createServer('server_name', 'username', 'password', true);

Example:

jdb.createServer('test_server', 'root', '');

Connect to a server

Once instantiated, you have to connect to a server before send queries.

var db = jdb.connect('server_name', 'username', 'password', 'database_name');
  • The 'server_name' is the name to the server. The server have to be created before with JSONDB::createServer()
  • The 'username' and the 'password' are the information used to connect to the database. These information are the same used when creating the server
  • The 'database_name' is the name of the database to use with current connection. This parameter is optional and can be set manually later.

Example:

var db = jdb.connect('test_server', 'root', '');

Create a database

After connected to server, you can create a database:

db.createDatabase('database_name');

Your new database will be a folder in your server in which each table will be a .json file.

Example:

db.createDatabase('test_database');

Use a database

To use a database, you can specify his name when connecting to a server, or use JSONDB::setDatabase() after a connection:

db.setDatabase('database_name')

Example:

db.setDatabase('test_database');

Create a table

Once JSONDB is connected to a server and use a database, you can create a new table with JSONDB::createTable():

db.createTable('table_name', prototype);

The prototype is an array of 'column_name' => column_properties pairs. Each column_properties are also an object which contains a list of 'property_name' => 'property_value' pairs.

There is a list of currently supported column properties:

  • 'type': Defines the type of values that the column accepts. This property can take only one value. Supported types are:
    • 'int', 'integer', 'number'
    • 'decimal', 'float'
    • 'string'
    • 'char'
    • 'bool', 'boolean'
    • 'array'
  • 'default': Sets the default value of column. The default value must be match the 'type' of the column.
  • 'max_length': Used by some type:
    • When used with 'float', the number of decimals is reduced to his value
    • When used with 'string', the number of characters is reduced to his value (starting with the first character)
  • 'not_null': Can take values true or false. Defines if a column have to be set to null when there is no value in the row. Doesn't work when a 'default' value is given
  • 'auto_increment': Can take values true or false. Defines if a column will be an auto incremented column. When used, the column is automatically set to UNIQUE KEY
  • 'primary_key': Can take values true or false. Defines if a column is a PRIMARY KEY
  • 'unique_key': Can take values true or false. Defines if a column is an UNIQUE KEY

Example:

db.createTable('users', {id: {type: 'int', auto_increment: true},
                         name: {type: 'string', max_length: 30, not_null: true},
                         surname: {type: 'string', max_length: 30, not_null: true},
                         pseudo: {type: 'string', max_length: 15, unique_key: true},
                         mail: {type: 'string', unique_key: true},
                         password: {type: 'string', not_null: true},
                         website: {type: 'string'},
                         activated: {type: 'bool', 'default': false},
                         banished: {type: 'bool', 'default': false}});

Send a query

JSONDB can send both direct and prepared queries.

Direct queries

var results = db.query('my_query_string');

//// Specially for select() queries
// You can change the fetch mode
results.setFetchMode(JSONDB.FETCH_ARRAY);
// or...
results.setFetchMode(JSONDB.FETCH_CLASS, MyCustomClass);
// Explore results using a while loop
while (result = results.fetch()) {
    // Do stuff...
}

Prepared queries

var query = db.prepare('my_prepared_query');
query.bindValue(':key1', val1, JSONDB.PARAM_INT);
query.bindValue(':key2', val2, JSONDB.PARAM_STRING);
query.bindValue(':key3', val3, JSONDB.PARAM_BOOL);
query.bindValue(':key4', val4, JSONDB.PARAM_NULL);
query.bindValue(':key5', val5, JSONDB.PARAM_ARRAY);
var results = query.execute();

//// Specially for select() queries
// You can change the fetch mode
results.setFetchMode(JSONDB.FETCH_OBJECT);
// or...
results.setFetchMode(JSONDB.FETCH_CLASS, MyCustomClass);
// Explore results using a while loop
while (result = results.fetch()) {
    // Do stuff...
}

JSONDB support a lot of common database queries, and use JQL, a custom query language...

JQL (JSONDB Query Language)

JQL is the query language used by JSONDB to send queries. It's a very easy language based on extensions. A JQL query is in this form:

db.query('table_name.query(parameters, ...).extensions(parameters, ...)...');

Query example with select():

// Select all from table `users` where `pseudo` = id and `password` = pass or where `mail` = id and `password` = pass
var id = JSONDB.quote(form_data.id);
var pass = JSONDB.quote(form_data.password);
db.query('users.select(*).where(pseudo=' + id + ',password=' + pass + ').where(mail=' + id + ',password=' + pass + ')');

// Select `pseudo` and `mail` from table `users` where `activated` = true, order the results by `pseudo` with `desc`endant method, limit the results to the 10 users after the 5th.
db.query("users.select(pseudo, mail).where(activated = true).order(pseudo, desc).limit(5, 10)");

Query example with insert():

// Insert a new user in table `users`
var pseudo = JSONDB.quote(form_data.pseudo);
var pass = JSONDB.quote(form_data.pass);
var mail = JSONDB.quote(form_data.mail);
db.query('users.insert(' + pseudo + ',' + pass + ',' + mail + ').in(pseudo,password,mail)');

// Multiple insertion...
db.query('users.insert(' + pseudo1 + ',' + pass1 + ',' + mail1 + ').and(' + pseudo2 + ',' + pass2 + ',' + mail2 + ').and(' + pseudo3 + ',' + pass3 + ',' + mail3 + ').in(pseudo,password,mail)');

Query example with replace():

// Replace information of the first user
db.query('users.replace(' + pseudo + ',' + pass + ',' + mail + ').in(pseudo,password,mail)');

// Multiple replacement...
db.query('users.replace(' + pseudo1 + ',' + pass1 + ',' + mail1 + ').and(' + pseudo2 + ',' + pass2 + ',' + mail2 + ').and(' + pseudo3 + ',' + pass3 + ',' + mail3 + ').in(pseudo,password,mail)');

Query example with delete():

// Delete all users
db.query("users.delete()");

// Delete all banished users
db.query("users.delete().where(banished = true)");

// Delete a specific user
db.query('users.delete().where(pseudo = ' + pseudo + ', mail = ' + mail + ')');

Query example with update():

// Activate all users
db.query("users.update(activated).with(true)");

// Update my information ;-)
db.query('users.update(mail, password, activated, banished).with(' + mail + ', ' + pseudo + ', true, false).where(pseudo = \'na2axl\')');

Query example with count():

// Count all `banished` users
db.query("users.count(*).as(banished_nb).where(banished = true)");

// Count all users and group by `activated`
db.query("users.count(*).as(users_nb).group(activated)");

Query example with truncate():

// Reset the table `users`
db.query("users.truncate()");

Full example

var JSONDB = require('jsondb-js');
var jdb = new JSONDB();

var db = jdb.createServer('test_server', 'root', '', true);

db.createDatabase('test_database').setDatabase('test_database'); // Yes, is chainable ! ;-)

db.createTable('users', {id: {type: 'int', auto_increment: true},
                         name: {type: 'string', max_length: 30, not_null: true},
                         surname: {type: 'string', max_length: 30, not_null: true},
                         pseudo: {type: 'string', max_length: 15, unique_key: true},
                         mail: {type: 'string', unique_key: true},
                         password: {type: 'string', not_null: true},
                         website: {type: 'string'},
                         activated: {type: 'bool', 'default': false},
                         banished: {type: 'bool', 'default': false}});

// A prepared query
var query = db.prepare('users.insert(:name, :sname, :pseudo, :mail, :pass).in(name, surname, pseudo, mail, password)');
query.bindValue(':name', 'Nana', JSONDB.PARAM_STRING);
query.bindValue(':sname', 'Axel', JSONDB.PARAM_STRING);
query.bindValue(':pseudo', 'na2axl', JSONDB.PARAM_STRING);
query.bindValue(':mail', 'ax.lnana@outlook.com', JSONDB.PARAM_STRING);
query.bindValue(':pass', '00@a&COmpLEx%PASssworD$00', JSONDB.PARAM_STRING);
query.execute();

// After some insertions...

// Select all users
var results = db.query('users.select(id, name, surname, pseudo)');
// Fetch with class mapping
var User = function () { };
User.prototype.id = 0;
User.prototype.name = '';
User.prototype.surname = '';
User.prototype.pseudo = '';
User.prototype.getInfo = function () {
    return "The user with id: " + this.id + " has the name: " + this.name + " " + this.surname + " and the pseudo: " + this.pseudo + ".";
};
while (result = results.fetch(JSONDB.FETCH_CLASS, User)) {
    console.log(result.getInfo());
}

// All done! Disconnect from the server...
db.disconnect();