jamadar

0.3.1 • Public • Published

Jamadar

Simplified database, table and index management functions for rethinkdb.

Build Status npm version

How To Install?

npm install --save jamadar

Features

  • Promise based
  • Uses Bluebird, so it should be fast
  • Uses rethinkdbdash, so that you don't have to deal with connection pooling etc.
  • Extensive test converage.

How To Use?

Sample configuration file config.js.

'use strict';
 
module.exports = {
  hosts: {
    servers: [
      { host: 'localhost', port: 28015 }
    ],
    buffer: 20, //Minimum connections in pool
    max: 100, //Maximum connections in pool
    discovery: false,
    db: 'lolstack_dev'
  },
  tableConfig: {
    url: {
      table_name: 'urls',
      indexes: [
        { name: 'url' },
        { name: 'post_id' },
        { name: 'created_at' },
        { name: 'updated_at' },
        { name: 'url_and_post_id', columns: [ 'url', 'post_id' ] }
      ]
    },
    user: {
      table_name: 'users',
      indexes: [
        { name: 'username' },
        { name: 'email' }
      ]
    },
    network: {
      table_name: 'networks',
      indexes: [
        { name: 'name' }
      ]
    },
    schedule: {
      table_name: 'schedules',
      indexes: [
        { name: 'nickname' },
        { name: 'user_id' }
      ]
    },
    post: {
      table_name: 'posts',
      indexes: [
        { name: 'user_id' },
        { name: 'network_id' },
        { name: 'schedule_id' }
      ]
    },
    picture: {
      table_name: 'pictures',
      indexes: [
        { name: 'user_id' }
      ]
    }
  }
};

Sample application using Jamadar with migration.

'use strict';
 
var Jamadar = require('jamadar');
var path = require('path');
 
var config = require(path.join(__dirname, 'config'));
 
var jamadar = new Jamadar(config.hosts);
 
jamadar.migrate(config.hosts.db, config.tableConfig)
  .then(function(result) {
    debug('Database setup complete.');
    // Database is migrated
    // Continue with regular tasks here.
    // Start express server may be.
  })
  .catch(function(error) {
    debug('Error in migrating database', error.message);
    debug(error.stack);
  });

The config.hosts options Object must be same as options you'd provide to rethinkdbdash.

Checkout a detailed example at express app with models.

Need Access to r?

If you need quick access to r for using it in cases like r.args, you can require r directly like this

'use strict';
 
var r = require('jamadar/r');

Please note that r won't have any connection or will not able to execute commands which require an active database connection.

Testing

npm test

Check test/config.js if your rethinkdb is not listening on default ports.

Documentation

Reference

#### Jamadar

Jamadar constructor. Needs a configuration object same as you'd pass to rethinkdbdash. It initialized rethinkdbdash internally.

var Jamadar = require('jamadar');
var db = Jamadar({
    servers: [
      { host: 'localhost', port: 28015 }
    ],
    db: 'jamadar_test_afj928dfas'
  });
#### Jamadar#r

Returns the rethinkdbdash instance in case you need it.

#### `function getDbList()`

Get a list of databases. Takes no callback.

  • Returns: {Promise} Returns a promise resolved on successful fetch and rejected on error
#### `function dbExists(dbName)`

Checks if a database exists or not. Takes no callback.

  • Parameters: {String} — dbName The name of the database to check
  • Returns: {Promise} Returns a promise resolved on successful calcuation and rejected on error
#### `function dbsExist(dbNames)`

Checks if databases exist and returns and array of dbs found. Takes no callback.

  • Parameters: {Array} — dbNames The names of the databases to check
  • Returns: {Promise} Returns a promise resolved on successful calcuation and rejected on error
#### `function createDb(dbName)`

Creates a new database with given name. Takes no callback.

  • Parameters: {String} — dbName Database name
  • Returns: {Promise} Returns a promise resolved on successful creation and rejected on error
#### `function dropDb(dbName)`

Drops a database. Takes no callback.

  • Parameters: {String} — dbName Database name
  • Returns: {Promise} Returns a promise resolved on successful drop and rejected on error
#### `function createDbIfNotExists(dbName)`

Checks if a database exists and creates it if it doesn't. Takes no callback.

  • Parameters: {String} — dbName Database name
  • Returns: {Promise} Returns a promise resolved on successful creation/existence and rejected on error
#### `function createDbsIfNotExist(dbNames)`

Checks if databases exist and creates them if they don't. Takes no callback.

  • Parameters: {String} — dbNames Database name(s)
  • Returns: {Promise} Returns a promise resolved on successful creation and rejected on error
#### `function dropDbIfExists(dbName)`

Checks if a database exists and drops it if it does. Takes no callback.

  • Parameters: {String} — dbName Database name
  • Returns: {Promise} Returns a promise resolved on successful drop and rejected on error
#### `function dropDbsIfExist(dbNames)`

Checks if databases exist and drops them if they do. Takes no callback.

  • Parameters: {String} — dbNames Database name(s)
  • Returns: {Promise} Returns a promise resolved on successful drop and rejected on error
#### `function resetDb(dbName)`

Reset all the tables of a database. It doesn't delete the tables but delete the rows in tables. Takes no callback.

  • Parameters: {String} — dbName Database name
  • Returns: {Promise} Returns a promise resolved on successful reset and rejected on error
#### `function getTableList(dbName)`

Retrieves the list of tables in a database. Takes no callback.

  • Parameters: {String} — dbName Database name
  • Returns: {Promise} Returns a promise resolved on successful retrieval and rejected on error
#### `function tableExists(dbName, tableName)`

Checks if a table exists in database. Takes no callback.

  • Parameters:
    • {String} — dbName Database name
    • {String} — tableName Table name
  • Returns: {Promise} Returns a promise resolved on successful check and rejected on error
#### `function tablesExist(dbName, tableNames)`

Checks if tables exist in database. Takes no callback.

  • Parameters:
    • {String} — dbName Database name
    • {Array} — tableNames Table names
  • Returns: {Promise} Returns a promise resolved on successful check and rejected on error
#### `function createTable(dbName, tableName)`

Creates a table in the database. Takes no callback.

  • Parameters:
    • {String} — dbName Database name
    • {String} — tableName Table name
  • Returns: {Promise} Returns a promise resolved on successful creation and rejected on error
#### `function dropTable(dbName, tableName)`

Drops a table in the database. Takes no callback.

  • Parameters:
    • {String} — dbName Database name
    • {String} — tableName Table name
  • Returns: {Promise} Returns a promise resolved on successful drop and rejected on error
#### `function createTableIfNotExists(dbName, tableName)`

Checks if a table exists and creates it if it doesn't. Takes no callback.

  • Parameters:
    • {String} — dbName Database name
    • {String} — tableName Table name
  • Returns: {Promise} Returns a promise resolved on successful creation/existence and rejected on error
#### `function createTablesIfNotExist(dbName, tableNames)`

Checks if tables exist and creates them if they don't. Takes no callback.

  • Parameters:
    • {String} — dbName Database name
    • {String} — tableNames Table name(s)
  • Returns: {Promise} Returns a promise resolved on successful creation/existence and rejected on error
#### `function dropTableIfExists(dbName, tableName)`

Checks if a table exists and drops it if it does. Takes no callback.

  • Parameters:
    • {String} — dbName Database name
    • {String} — tableName Table name
  • Returns: {Promise} Returns a promise resolved on successful drop and rejected on error
#### `function dropTablesIfExist(dbName, tableNames)`

Checks if tables exist and drops them if they do. Takes no callback.

  • Parameters:
    • {String} — dbName Database name
    • {String} — tableNames Table name(s)
  • Returns: {Promise} Returns a promise resolved on successful drop and rejected on error
#### `function resetTable(dbName, tableName)`

Deletes all rows in a table. Takes no callback.

  • Parameters:
    • {String} — dbName Database name
    • {String} — tableName Table name
  • Returns: {Promise} Returns a promise resolved on successful deletion and rejected on error
#### `function resetTables(dbName, tableNames)`

Deletes all rows in given tables. Takes no callback.

  • Parameters:
    • {String} — dbName Database name
    • {Array|String} — tableNames Table name(s)
  • Returns: {Promise} Returns a promise resolved on successful deletion and rejected on error
#### `function getIndexList(dbName, tableName)`

Fetches all indexes on a given table. Takes no callback.

  • Parameters:
    • {String} — dbName Database name
    • {String} — tableName Table name
  • Returns: {Promise} Returns a promise resolved on successful fetch and rejected on error
#### `function indexExists(dbName, tableName, indexName)`

Checks if an index exists for a table or not. Takes no callback.

  • Parameters:
    • {String} — dbName Database name
    • {String} — tableName Table name
    • {String} — indexName Index name
  • Returns: {Promise} Returns a promise resolved on successful check and rejected on error
#### `function indexesExist(dbName, tableName, indexNames)`

Checks if indexes exists for a table or not. Takes no callback.

  • Parameters:
    • {String} — dbName Database name
    • {String} — tableName Table name
    • {Array} — indexNames Index names
  • Returns: {Promise} Returns a promise resolved on successful check and rejected on error
#### `function createIndex(dbName, tableName, indexName, fn)`

Creates specified index and waits on it. Takes no callback.

  • Parameters:
    • {String} — dbName Database name
    • {String} — tableName Table name
    • {String} — indexName Index name
    • {Function} — fn An optional function describing index
  • Returns: {Promise} Returns a promise resolved on successful creation of index and rejected on error
#### `function dropIndex(dbName, tableName, indexName)`

Drops specified index. Takes no callback.

  • Parameters:
    • {String} — dbName Database name
    • {String} — tableName Table name
    • {String} — indexName Index name
  • Returns: {Promise} Returns a promise resolved on successful deletion of index and rejected on error
#### `function createIndexIfNotExists(dbName, tableName, indexName, fn)`

Check if an index exists and creates if it doesn't. Takes no callback.

  • Parameters:
    • {String} — dbName Database name
    • {String} — tableName Table name
    • {String} — indexName Index name
    • {Function} — fn An optional function describing index
  • Returns: {Promise} Returns a promise resolved on successful creation/existence of index and rejected on error
#### `function createIndexesIfNotExist(dbName, tableName, indexData)`

Checks if supplied indexes exist and create them if they don't exist. Takes no callback.

  • Parameters:
    • {String} — dbName Database name
    • {String} — tableName Table name
    • {Array} — indexData Array containing individual index data.
  • Returns: {Promise} Returns a promise resolved on successful creation/existence of indexes and rejected on error

indexData example:

  [
    { name: 'field1' },
    { name: 'field2' },
    { name: 'field1_and_field2',
      fn: function(row) {
        return [row('field1'), row('field2')];
      }
    },
    ...
  ]
#### `function dropIndexIfExists(dbName, tableName, indexName)`

Checks if an index exists and drops if it does. Takes no callback.

  • Parameters:
    • {String} — dbName Database name
    • {String} — tableName Table name
    • {String} — indexName Index name
  • Returns: {Promise} Returns a promise resolved on successful deletion of index and rejected on error
#### `function dropIndexesIfExist(dbName, tableName, indexNames)`

Checks if indexes exist and drops them if they do. Takes no callback.

  • Parameters:
    • {String} — dbName Database name
    • {String} — tableName Table name
    • {String} — indexNames Index name(s)
  • Returns: {Promise} Returns a promise resolved on successful deletion of index and rejected on error
#### `function migrate(dbName, tables, indexes)`

Migrates database to a provided configuration. Takes no callback.

  • Parameters:
    • {String} — dbName Database name
    • {Object} — tableData Object describing tables.
    • {Array} — indexData Array of objects containing index data.
  • Returns: {Promise} Returns a promise resolved on and rejected on error

tableData example:

  {
    tableId: 'tableName',
    user: 'users',
    schedule: 'schedules'
  }

indexData example:

  {
    tableId: [
      { name: 'field1' },
      { name: 'field2' },
      { name: 'field2_and_field3_index', [ 'field2', 'field3' ] }
    ],
    user: [
      { name: 'username' },
      { name: 'email' }
    ]
  }
#### `function Model(dbName, tableName)`

Returns a database Model on the lines on ActiveRecord in Rails. It exposes most internal ReQL functions.

  • Parameters:
    • {Object} — r Rethinkdbdash instance
    • {String} — dbName The database name
    • {String} — tableName The table name
  • Returns: {Object} Return an object exposing wrappers around ReQL functions.

Example:

var Jamadar = require('Jamadar')(dbConfig);
var User = Jamadar.Model('databasename', 'users').table();
// Now User is same as r.db('databasename').table('users');
 
User.get(id).update({ name: 'Kulbir Saini' }).run()
  .then(function(result) {
    console.log(result);
  });

License

(The MIT License)

Copyright (c) 2015 Kulbir Saini

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.

Package Sidebar

Install

npm i jamadar

Weekly Downloads

0

Version

0.3.1

License

MIT

Last publish

Collaborators

  • kulbirsaini