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 withJSONDB::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)
- When used with
'not_null'
: Can take valuestrue
orfalse
. 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 valuestrue
orfalse
. Defines if a column will be an auto incremented column. When used, the column is automatically set to UNIQUE KEY'primary_key'
: Can take valuestrue
orfalse
. Defines if a column is a PRIMARY KEY'unique_key'
: Can take valuestrue
orfalse
. 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();