@eggjs/redis

@eggjs/redis

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

Version Notes

@eggjs/redis only supports egg@4 now, if you are using egg@3 or egg@2, you should use egg-redis.

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.ts to enable redis plugin:

import redisPlugin from '@eggjs/redis';

export default {
  ...redisPlugin(),
};

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

Single Client

import { defineConfig } from 'egg';

export default defineConfig({
  redis: {
    client: {
      port: 6379, // Redis port
      host: '127.0.0.1', // Redis host
      password: 'auth',
      db: 0,
    },
  },
});

Multi Clients

import { defineConfig } from 'egg';

export default defineConfig({
  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

import { defineConfig } from 'egg';

export default defineConfig({
  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.ts

import { defineConfig } from 'egg';

export default defineConfig({
  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

import { defineConfig } from 'egg';

export default defineConfig({
  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.ts

import { Controller } from 'egg';

export default class HomeController extends 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.ts

export default class HomeController extends Controller {
  async index() {
    const { ctx, app } = this;
    // set
    await app.redis.getSingletonInstance('instance1').set('foo', 'bar');
    // get
    ctx.body = await app.redis.getSingletonInstance('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.ts
import { defineConfig } from 'egg';

export default defineConfig({
  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.ts
import { Controller } from 'egg';

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

For the local dev

Run docker compose to start test redis service

docker compose -f docker-compose.yml up -d

Run the unit tests

pnpm test

Stop test redis service

docker compose -f docker-compose.yml down

Using ioredis-mock for Unit Tests

You can use ioredis-mock to replace the real Redis client in unit tests. This eliminates the need for a running Redis server during testing, making your CI faster and local development simpler.

Install

npm i --save-dev ioredis-mock @types/ioredis-mock

Configure

In your test config (e.g., config/config.unittest.ts), override the Redis class:

import RedisMock from 'ioredis-mock';
import type { EggAppInfo, PartialEggConfig } from 'egg';

export default function (_appInfo: EggAppInfo): PartialEggConfig {
  return {
    redis: {
      Redis: RedisMock,
      client: {
        host: '127.0.0.1',
        port: 6379,
        password: '',
        db: 0,
        weakDependent: true,
      },
    },
  };
}

Important: You must set weakDependent: true when using ioredis-mock. Mock clients emit the ready event synchronously during construction, before the plugin's listener is attached. Without weakDependent: true, the app will hang on startup waiting for a ready event that was already emitted.

Notes

• ioredis-mock provides an in-memory Redis implementation that supports most common commands (get, set, setex, del, incr, zadd, zpopmin, zcount, etc.)
• Each test worker gets an isolated in-memory Redis instance
• For production deployment testing, you should still use a real Redis server
• You can remove redis service containers from your CI workflow when using ioredis-mock for unit tests

Questions & Suggestions

Please open an issue here.

License

MIT

Contributors

Made with contributors-img.