README.md

Knextancy - knex with multitenancy

Small library that provides a way of implementing multi-tenancy using table prefixes.

It has a very simple API:

var knextancy = require('knextancy');

knextancy.tenant(knex, tenantId).then(function (tenantKnex) {

  // the tenantKnex object contains the tenantId as an attribute
  console.log(tenantKnex.tenantId);

  tenantKnex('$_users').where({
    first_name: 'Test',
    last_name:  'User'
  }).select('id')

});

Its tenant method expects a knex instance and a tenantId and returns Promise for a special tenantKnex instance that scopes every queries to the particular tenant.

The only requirement is that every query is written using the special $_ prefix for every table name.

Check out this example using knextancy with express and PostgreSQL database

Migrations

Knextancy assures that all migrations are ran on a tenant's tables before returning its knex instance.

This special naming convention also applies while writing migrations, for example:

'use strict';

exports.up = function(knex, Promise) {
  return knex.schema.createTable('$_users', function (table) {
    table.string('name');
  });
};

exports.down = function(knex, Promise) {
  return knex.schema.dropTable('users');
};

PS: You may have problems creating custom column index. I created a pull request fixing it few months ago. But knex team have not accepted it yet. While that pull request is not accepted is possible to fix it using a custom name for the index:

table.integer('groupId').index('index_$_groupId');

Connect Middleware

It also provides a handy Connect middleware that automatically creates a knex instance and attaches it to the request object for a kiven tetant based on a special HTTP header.

Bellow is a usage example:

var app = express();

app.use(knextancy.middleware(knex, { header: 'x-client-id' }));

app.get('/', function (req, res, next) {
  req.knex.select().from('$_users').then(function (users) {
    res.send(users);
  }, next);
});

The knextancy.middleware expects two parameters:

• knex instance;
• options.header the name of the HTTP header that will contain the tenant id.

Setup All Tenants

Allow execute all migrations/seed for all existing tenants at once.

Bellow is a usage example:

knextancy.setupAllTenants(knex).then(function () {
  // done
});

Fetch Tenants

Based in the migration tables in the current database is possible to fetch the existing tenants.

Bellow is a usage example:

knextancy.fetchTenants(knex).then(function (tenants) {
  // ['01', '02']
});

Tests

To run the tests using Docker Compose:

docker-compose run --rm test bash
npm install # in case you have not installed yet
npm test

License

Licensed under The MIT License Redistributions of files must retain the above copyright notice.