README.md

@eggjs/redis

Valkey / Redis client (support redis protocol) based on iovalkey for egg framework

Install

npm i @eggjs/redis

Valkey / Redis Plugin for egg, support egg application access to Valkey / Redis Service.

This plugin based on ioredis. If you want to know specific usage, you should refer to the document of ioredis.

Configuration

Change ${app_root}/config/plugin.js to enable redis plugin:

exports.redis = {
  enable: true,
  package: '@eggjs/redis',
};

Configure redis information in ${app_root}/config/config.default.js:

Single Client

config.redis = {
  client: {
    port: 6379,          // Redis port
    host: '127.0.0.1',   // Redis host
    password: 'auth',
    db: 0,
  },
}

Multi Clients

config.redis = {
  clients: {
    foo: {                 // instanceName. See below
      port: 6379,          // Redis port
      host: '127.0.0.1',   // Redis host
      password: 'auth',
      db: 0,
    },
    bar: {
      port: 6379,
      host: '127.0.0.1',
      password: 'auth',
      db: 1,
    },
  }
}

Sentinel

config.redis = {
  client: {
    // Sentinel instances
    sentinels: [
      {
        port: 26379,         // Sentinel port
        host: '127.0.0.1',   // Sentinel host
      },
      // other sentinel instance config
    ],
    name: 'mymaster',      // Master name
    password: 'auth',
    db: 0
  },
}

No password

Redis support no authentication access, but we are highly recommend you to use redis requirepass in redis.conf.

$vim /etc/redis/redis.conf

requirepass xxxxxxxxxx  // xxxxxxxxxx is your password

Because it may be cause security risk, refer:

• https://ruby-china.org/topics/28094
• https://zhuoroger.github.io/2016/07/29/redis-sec/

If you want to access redis with no password, use password: null.

See ioredis API Documentation for all available options.

Customize ioredis version

@eggjs/redis using ioredis@5 now, if you want to use other version of iovalkey or ioredis, you can pass the instance by config.redis.Redis:

// config/config.default.js
config.redis = {
  Redis: require('ioredis'), // customize ioredis version, only set when you needed
  client: {
    port: 6379,          // Redis port
    host: '127.0.0.1',   // Redis host
    password: 'auth',
    db: 0,
  },
}

weakDependent

config.redis = {
  client: {
    port: 6379,          // Redis port
    host: '127.0.0.1',   // Redis host
    password: 'auth',
    db: 0,
    weakDependent: true, // the redis instance won't block app start
  },
}

Usage

In controller, you can use app.redis to get the redis instance, check ioredis to see how to use.

// app/controller/home.js

module.exports = app => {
  return class HomeController extends app.Controller {
    async index() {
      const { ctx, app } = this;
      // set
      await app.redis.set('foo', 'bar');
      // get
      ctx.body = await app.redis.get('foo');
    }
  };
};

Multi Clients

If your Configure with multi clients, you can use app.redis.get(instanceName) to get the specific redis instance and use it like above.

// app/controller/home.js

module.exports = app => {
  return class HomeController extends app.Controller {
    async index() {
      const { ctx, app } = this;
      // set
      await app.redis.get('instance1').set('foo', 'bar');
      // get
      ctx.body = await app.redis.get('instance1').get('foo');
    }
  };
};

Clients Depend on Redis Cluster

Before you start to use Redis Cluster, please checkout the document first, especially confirm cluster-enabled yes in Redis Cluster configuration file.

In controller, you also can use app.redis to get the redis instance based on Redis Cluster.

// app/config/config.default.js
exports.redis = {
  client: {
    cluster: true,
    nodes: [
      {
        host: '127.0.0.1',
        port: '6379',
        family: 'user',
        password: 'password',
        db: 'db',
      },
      {
        host: '127.0.0.1',
        port: '6380',
        family: 'user',
        password: 'password',
        db: 'db',
      },
    ],
  },
};

// app/controller/home.js
module.exports = app => {
  return class HomeController extends app.Controller {
    async index() {
      const { ctx, app } = this;
      // set
      await app.redis.set('foo', 'bar');
      // get
      ctx.body = await app.redis.get('foo');
    }
  };
};

Questions & Suggestions

Please open an issue here.

License

MIT

Contributors

Made with contributors-img.