DBMS / 03. Methods
Updated: 11. November 2018
Author: Peter Širka

03. Methods

Professional Support Chat with contributors

  • DBMS(name) is a global variable for entire project
var db = DBMS();

Quick links:

Methods

db.avg(name, prop)

Performs AVG to DB according to name argument. A response is a number.

// db.avg(name, prop);
// @name {String} A collection/table name
// @prop {String} A property name
// returns QueryBuilder
// response: Number

db.avg('users', 'age');

db.blob([name])

This method can store a file stream as a blob. Currently it works with PostgreSQL only.

// db.blob([name]);
// @name {String} Optional, A collection/table name (default: 'default' database)
// returns Object

// Writing:
db.blob().write(read_stream, [name], callback(err, id));

// Reading:
db.blob().read(id, callback(err, read_stream));

db.callback(fn)

Executes fn when the module ends all DB operations.

// db.callback(fn);
// @fn {Function} A callback
// returns DBMS

db.callback(function(err, response) {
    // @err {ErrorBuilder} can be "null"
    // @response {Object} with results
    console.log(err, response);  
});

db.count(name)

Performs COUNT to DB according to name argument. A response is a number.

// db.count(name);
// @name {String} A collection/table name
// returns QueryBuilder
// response: Number

db.count('users');

db.data(fn)

Executes fn when the module ends without any error.

// db.data(fn);
// @fn {Function} A callback
// returns DBMS

db.data(function(response) {
    // @response {Object} with results
    console.log(response);
});

db.fail(fn)

Executes fn when the module ends with some error.

// db.fail(fn);
// @fn {Function} A callback
// returns DBMS

db.fail(function(err) {
    // @err {ErrorBuilder}
    console.log(err);
});

db.find(name)

Performs SELECT to DB according to name argument.

// db.find(name);
// @name {String} A collection/table name
// returns QueryBuilder
// response: Array

db.find('users');

db.get(path)

Reads a value from DB response. It can read a value from Array of responses or with a plain Object.

// db.find(name);
// @path {String} A path to resopnse
// returns Function

db.find('invoices').in('id', db.get('users.id'));

db.insert(name, doc, [unique])

Performs INSERT to DB according to name argument.

// db.insert(name, doc, [unique]);
// @name {String} A collection/table name
// @doc {Object} A document
// @unique {Boolean} Checks if the record doesn't exist
// returns QueryBuilder
// response: Number

db.insert('users', { name: 'Peter', age: 33 });

// Or with "unique" argument:
db.insert('users', { name: 'Peter', age: 33 }, true).where('name', 'Peter');

db.list(name)

Performs COUNT and SELECT to DB according to name argument. A response is in a specific format.

// db.list(name);
// @name {String} A collection/table name
// returns QueryBuilder
// response: Object

db.list('users');

// Output will be:
// { items: [...], count: 100, page: 1, pages: 10, limit: 10 }

db.make(fn)

Creates a scope.

// db.make(fn);
// @fn {Function}
// returns DBMS

db.make(function(db) {
    db.find();
    db.read();
    db.must();
    // etc..
});

db.max(name, prop)

Performs MAX to DB according to name argument. A response is a number.

// db.max(name, prop);
// @name {String} A collection/table name
// @prop {String} A property name
// returns QueryBuilder
// response: Number

db.max('users', 'age');

db.min(name, prop)

Performs MIN to DB according to name argument. A response is a number.

// db.min(name, prop);
// @name {String} A collection/table name
// returns QueryBuilder
// response: Number

db.min('users', 'age');

db.modify(name, doc, [insert])

Performs UPDATE for the specific fields. A response is a number with count of modified documents.

// db.modify(name, doc, [insert]);
// @name {String} A collection/table name
// @doc {Object} A document
// @insert {Boolean} Performs "insert" if the document won't exist.
// returns QueryBuilder
// response: Number

db.modify('users', { '+age': 1, dateupdated: NOW }, true).where('name', 'Peter');

// Supports incremental values
// +prop performs val + 1
// -prop performs val - 1
// *prop performs val * 1
// /prop performs val / 1

db.must(err, [reverse])

Performs a small validation for the last received data.

// db.must(err, [reverse]);
// @err {String/Function} A collection/table name
// @reverse {Boolean} Performs a reverse validation
// returns QueryBuilder

db.must('usernotfound');
// or 
db.must(val => val != null ? true : 'usernotfound');

// A real example:
db.read('users').where('name', 'Peter');
db.must('usernotfound');
db.find('orders').in('userid', db.get('users.id'));
db.callback(console.log);

db.output(obj)

Sets a default output object.

// db.output(output);
// @obj {Object}

db.output({ type: 'detail' });
db.read('users').where('name', 'Peter').set('user');

// Output:
// { type: 'detail', user: { ... }}

db.read(name)

Performs SELECT with LIMIT 1 to DB according to name argument. A response is an object with the record data.

// db.read(name);
// @name {String} A collection/table name
// returns QueryBuilder
// response: Object

db.read('users');

db.remove(name)

Performs DELETE in DB according to name argument. A response is a number with count of removed documents.

// db.remove(name);
// @name {String} A collection/table name
// returns QueryBuilder
// response: Number

db.remove('users').where('name', 'Peter');

db.sum(name, prop)

Performs SUM to DB according to name argument. A response is a number.

// db.sum(name, prop);
// @name {String} A collection/table name
// @prop {String} A property name
// returns QueryBuilder
// response: Number

db.sum('users', 'age');

db.task(fn)

Performs a sync task in a row.

// db.task(fn);
// @fn {Function}

db.task(function(responses, lastresponse) {
    lastresponse.user.name = lastresponse.user.name.toUpperCase();
});

db.query(query, [value])

Executes a query. IMPORTANT: each DB engine can have own implementation of query arguments.

// db.query(query, [value]);
// @query {String} Raw query
// @value {Object} Optional, query arguments
// returns QueryBuilder

// Example for PostgreSQL
db.query('SELECT * FROM tbl_users WHERE id=$1', [12345]).callback(console.log);
db.query('SELECT * FROM tbl_users').where('id', 12345).callback(console.log);

db.update(name, doc, [insert])

Performs UPDATE to DB according to name argument. A response is a number with count of updated documents.

// db.update(name, doc, [insert]);
// @name {String} A collection/table name
// @doc {Object} A document
// @insert {Boolean} Performs "insert" if the document won't exist.
// returns QueryBuilder
// response: Number

db.update('users', { name: 'Peter', age: 33 }, true).where('name', 'Peter');