plugins/redis/README.md
Valkey / Redis client (support redis protocol) based on iovalkey for egg framework
@eggjs/redis only supports egg@4 now, if you are using egg@3 or egg@2, you should use egg-redis.
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.
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:
If you want to access redis with no password, use password: null.
See ioredis API Documentation for all available options.
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
},
},
});
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');
}
}
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');
}
}
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');
}
}
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
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.
npm i --save-dev ioredis-mock @types/ioredis-mock
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: truewhen usingioredis-mock. Mock clients emit thereadyevent synchronously during construction, before the plugin's listener is attached. WithoutweakDependent: true, the app will hang on startup waiting for areadyevent that was already emitted.
ioredis-mock provides an in-memory Redis implementation that supports most common commands (get, set, setex, del, incr, zadd, zpopmin, zcount, etc.)redis service containers from your CI workflow when using ioredis-mock for unit testsPlease open an issue here.
Made with contributors-img.