https://github.com/eggjs/redis
redis plugin for egg
https://github.com/eggjs/redis
egg egg-plugin redis-client
Last synced: 3 months ago
JSON representation
redis plugin for egg
- Host: GitHub
- URL: https://github.com/eggjs/redis
- Owner: eggjs
- License: mit
- Created: 2017-02-12T17:43:51.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2024-04-07T09:46:35.000Z (about 1 year ago)
- Last Synced: 2024-10-29T21:05:54.314Z (8 months ago)
- Topics: egg, egg-plugin, redis-client
- Language: JavaScript
- Size: 71.3 KB
- Stars: 270
- Watchers: 14
- Forks: 68
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Changelog: History.md
- License: LICENSE
Awesome Lists containing this project
- awesome-egg - egg-redis - redis plugin for egg   (仓库 / 插件)
- awesome-egg - egg-redis - redis plugin for egg (Plugins)
README
# @eggjs/redis
[![NPM version][npm-image]][npm-url]
[](https://github.com/eggjs/redis/actions/workflows/nodejs.yml)
[![Test coverage][codecov-image]][codecov-url]
[![Known Vulnerabilities][snyk-image]][snyk-url]
[![npm download][download-image]][download-url]
[](https://nodejs.org/en/download/)
[](https://makeapullrequest.com)
[npm-image]: https://img.shields.io/npm/v/@eggjs/redis.svg?style=flat-square
[npm-url]: https://npmjs.org/package/@eggjs/redis
[codecov-image]: https://codecov.io/gh/eggjs/redis/branch/master/graph/badge.svg
[codecov-url]: https://codecov.io/gh/eggjs/redis
[snyk-image]: https://snyk.io/test/npm/@eggjs/redis/badge.svg?style=flat-square
[snyk-url]: https://snyk.io/test/npm/@eggjs/redis
[download-image]: https://img.shields.io/npm/dm/@eggjs/redis.svg?style=flat-square
[download-url]: https://npmjs.org/package/@eggjs/redis
Valkey / Redis client (support [redis protocol](https://redis.io/docs/latest/develop/reference/protocol-spec/)) based on iovalkey for egg framework
## Install
```bash
npm i @eggjs/redis
```
Valkey / Redis Plugin for egg, support egg application access to Valkey / Redis Service.
This plugin based on [ioredis](https://github.com/redis/ioredis).
If you want to know specific usage, you should refer to the document of [ioredis](https://github.com/redis/ioredis).
## Configuration
Change `${app_root}/config/plugin.js` to enable redis plugin:
```js
exports.redis = {
enable: true,
package: '@eggjs/redis',
};
```
Configure redis information in `${app_root}/config/config.default.js`:
**Single Client**
```javascript
config.redis = {
client: {
port: 6379, // Redis port
host: '127.0.0.1', // Redis host
password: 'auth',
db: 0,
},
};
```
**Multi Clients**
```javascript
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**
```javascript
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`.
```bash
$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](https://github.com/redis/ioredis#basic-usage) 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`:
```js
// 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**
```javascript
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](https://github.com/redis/ioredis#basic-usage) to see how to use.
```js
// 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.
```js
// 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](https://redis.io/topics/cluster-tutorial) 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.
```js
// 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');
}
};
};
```
## For the local dev
Run docker compose to start test redis service
```bash
docker compose -f docker-compose.yml up -d
```
Run the unit tests
```bash
npm test
```
Stop test redis service
```bash
docker compose -f docker-compose.yml down
```
## Questions & Suggestions
Please open an issue [here](https://github.com/eggjs/egg/issues).
## License
[MIT](LICENSE)
## Contributors
[](https://github.com/eggjs/redis/graphs/contributors)
Made with [contributors-img](https://contrib.rocks).