sequelize-simple-cache

sequelize-simple-cache

This is a simple, transparent, client-side, in-memory cache for Sequelize v4. Cache invalidation is based on time-to-live (ttl). Selectively add your Sequelize models to the cache. Works with all storage engines supported by Sequelize.

This cache might work for you if you have a few database tables that (1) are frequently read but very rarely written and (2) contain only few rows of data.

In a project, we had a couple of database tables that were holding a sort of system configuration. Something like 4 or 5 tables with some 50 rows of data. Nearly every request needed this data, i.e., it was read all the time. But updated only very rarely, once a day maybe. So, pre-fetching or simple caching would work for us.

If that's not matching your scenario, better look for something more sophisticated such as Redis, memcached and alike.

Install

npm install sequelize-simple-cache

Usage

Setup the cache along with loading your Sequelize models like this:

const Sequelize = require('sequelize');
const SequelizeSimpleCache = require('sequelize-simple-cache');

const sequelize = new Sequelize('database', 'username', 'password', { ... });

// initialize cache
const cache = new SequelizeSimpleCache({
  User: { ttl: 5 * 60 }, // 5 minutes
  Page: { }, // default ttl is 1 hour
});

// add your models to the cache like this
const User = cache.init(sequelize.import('./models/user'));
const Page = cache.init(sequelize.import('./models/page'));

// no caching for this one
const Balance = sequelize.import('./models/balance');

// still no caching for this one (because it's not configured to be cached)
// will add dummy decorators to the model for a homogeneous interface to all models
const Order = cache.init(sequelize.import('./models/order'));

// the Sequelize model API is fully transparent, no need to change anything.
// first time resolved from database, subsequent times from local cache.
const fred = User.findOne({ where: { username: 'fred' }});

More Details

Supported methods

Currently, the following methods on Sequelize model instances are supported for caching: findById, findOne, findAll, findAndCountAll, count, min, max, sum.

Non-cacheable queries / bypass caching

You need to avoid non-cacheable queries, e.g., queries containing dynamic timestamps.

const { Op, fn } = require('sequelize');
// this is not good
Model.findOne({ where: { startDate: { [Op.lte]: new Date() }, } });
// you should do it this way
Model.findOne({ where: { startDate: { [Op.lte]: fn('NOW') }, } });
// if you don't want a query to be cached, bypass the cache like this
Model.cacheBypass().findOne({ where: { startDate: { [Op.lte]: fn('NOW') }, } });

Clear cache

There are these ways to clear the cache.

const cache = new SequelizeSimpleCache({...});
// clear all
cache.clear();
// clear all entries of one specific model
cache.clear('User');
// or do the same on any model
Model.cacheClear();
Model.cacheClearAll();

Bypass caching

Caching can explicitly be bypassed like this:

Model.cacheBypass().findOne(...);

Debug output

You can activate debug output to console.debug() like this:

const cache = new SequelizeSimpleCache({
  // ...
}, {
  debug: true,
});

Unit testing your models

If you are unit testing your Sequelize models using Sinon et al., caching might be somewhat counterproductive. So, either clear the cache as needed in your unit tests. For example (using mocha):

describe('My Test Suite', () => {
  beforeEach(() => {
    Model.cacheClearAll(); // on any model with the same effect
  });
  // ...

Or disable the cache right from the beginning. A quick idea... have a specific config value in your project's /config/default.js and /config/test.js to enable or disable the cache respectively. And start your unit tests with setting NODE_ENV=test before. This is actually the way I am doing it; plus a few extra unit tests for explicitly testing the cache.

const config = require('config');
const useCache = config.get('database.cache');
// initializing the cache
const cache = useCache ? new SequelizeSimpleCache({...}) : undefined;
// loading the models
const model = sequelize.import('./models/model');
const Model = useCache ? cache.init(model) : model;