MariaDB-Redis

A redis cache layer for mariadb.

How it works:

Checks redis for cached queries and falls back to mariadb if they don't exist. Caches the query when obtained from mariadb.

npm i mariadb-redis

Use Case

This package is to be used with mariadb and redis, it is not a replacement for either.

• Static data
• Data that is not bound to be updated after creation

Note: Using this for data that may be updated will lead to queries returning old data.

Getting Started

Prerequisites

Mariadb (mariadb/mariadb2*)

For callbacks based api:

Redis (redis/ioredis)

For async/await based api:

async-redis

Note: This package has not been tested with mariadb2 yet.

Installation

Run the following command in your project folder containing the package.json file:

npm i mariadb-redis

Usage (With callbacks)

An instance of MariadbRedis requires:

• A mariadb connection or pool
• A redis client

A basic example of how this package would be used:

Import mariadb-redis

const MariadbRedis = require("mariadb-redis");

Create a mariadb connection.

Create a redis client.

Create an instance of MariadbRedis

const mariadbRedis = new MariadbRedis(mariadbConnection, redisClient);

MariadbRedis parameters:

Getting data from queries:

mariadbRedis.query("SELECT * FROM animals WHERE id = ?", [7], (error, result) => {
    console.log(result);
});

query parameters:

Usage (With promises)

An instance of MariadbRedisAsync requires:

• A mariadb connection or pool promise
• An async redis client

A basic example of how this package would be used:

Import mariadb-redis

const MariadbRedisAsync = require("mariadb-redis");

Create a mariadb connection promise.

Create an async redis client.

Create an instance of MariadbRedisAsync

const mariadbRedisAsync = new MariadbRedisAsync(mariadbConnection, redisClient);

MariadbRedisAsync parameters:

Getting data from queries:

//Inside an async function
try {
    var result = await mariadbRedisAsync.query("SELECT * FROM animals WHERE id = ?", [7]);
}
catch (error) {
    //Handle error
}

query parameters:

CacheOptions

Cache options can be specified when creating an instance of MariadbRedis or MariadbRedisAsync.

They can also be overridden in the query function for that specific query.

An example of cache options:

//These are the default cache options that are used if none are provided
const cacheOptions = {
  expire: 86400,
  keyPrefix: "maria.",
  hashType: HashTypes.md5,
  cacheType: CacheTypes.CACHE
};

Specifying cache options in MariadbRedis:

const { MariadbRedis, HashTypes, CacheTypes } = require("mariadb-redis");

const cacheOptions = {
  expire: 21600,
  keyPrefix: "dev.",
  hashType: HashTypes.md5,
  cacheType: CacheTypes.CACHE
};

//Initialize mariadb connection and redis client

const mariadbRedis = new MariadbRedis(mariadbConnection, redisClient, cacheOptions);

Overriding cache options in query (Using callbacks):

mariadbRedis.query("SELECT * FROM animals WHERE id = ?", [7],
  {
    expire: 3600,
    keyPrefix: "dev.animals."
  },
  (error, result) => {
    console.log(result);
});

Specifying cache options in MariadbRedisAsync:

const { MariadbRedisAsync, HashTypes, CacheTypes } = require("mariadb-redis");

const cacheOptions = {
  expire: 21600,
  keyPrefix: "dev.",
  hashType: HashTypes.md5,
  cacheType: CacheTypes.CACHE
};

//Initialize mariadb connection promise and async redis client

const mariadbRedisAsync = new MariadbRedisAsync(mariadbConnection, redisClient, cacheOptions);

Overriding cache options in query (Using promises):

//Inside an async function
try {
    var result = await mariadbRedisAsync.query("SELECT * FROM animals WHERE id = ?", [7],
      {
        expire: 3600,
        keyPrefix: "dev.animals."
      }
    );
}
catch (error) {
    //Handle error
}

HashTypes

Sql statements and values are converted into a hash to be used as a redis key for their results.

A hash type can be specified in the CacheOptions. If none specified, it defaults to HashTypes.md5.

The currently available hash types are:

• HashTypes.full - Full sql statements with values. (Not recommended)
• HashTypes.md5 - md5 hash encoded in base64.
• HashTypes.sha1 - sha1 hash encoded in base64.

CacheTypes

A cache type is used to specify how results for query/queries are obtained.

A cache type can be specified in the CacheOptions. If none specified, it defaults to CacheTypes.CACHE.

The currently available cache types are:

• CacheTypes.CACHE - Check redis for results and fallback to mariadb.
• CacheTypes.SKIP - Skips redis check and gets results from mariadb.
• CacheTypes.REFRESH - Refreshes redis cache by getting results from mariadb.