redis/node-redis
1
0
Fork 0
mirror of https://github.com/redis/node-redis.git synced 2025-08-07 13:22:56 +03:00
Code Activity

fix #1714 - update README(s)

Browse Source
This commit is contained in:
leibale
2021-11-09 18:07:26 -05:00
parent 8b3daad88a
commit ab339d396a
34 changed files with 464 additions and 11845 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
docs/FAQ.md Normal file
View File

@@ -0,0 +1,13 @@
# F.A.Q.
Nobody has *actually* asked these questions. But, we needed somewhere to put all the important bits and bobs that didn't fit anywhere else. So, here you go!
## What happens when the network goes down?
When a socket closed unexpectedly, all the commands that were already sent will reject as they might have been executed on the server. The rest will remain queued in memory until a new socket is established. If the client is closed—either by returning an error from [`reconnectStrategy`](./client-configuration.md#reconnect-strategy) or by manually calling `.disconnect()`—they will be rejected.
## How are commands batched?
Commands are pipelined using [`queueMicrotask`](https://nodejs.org/api/globals.html#globals_queuemicrotask_callback).
If `socket.write()` returns `false`—meaning that ["all or part of the data was queued in user memory"](https://nodejs.org/api/net.html#net_socket_write_data_encoding_callback:~:text=all%20or%20part%20of%20the%20data%20was%20queued%20in%20user%20memory)—the commands will stack in memory until the [`drain`](https://nodejs.org/api/net.html#net_event_drain) event is fired.

32
docs/client-configuration.md Normal file
View File

@@ -0,0 +1,32 @@
# `createClient` configuration
| Property | Default | Description |
|--------------------------|------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| url | | `redis[s]://[[username][:password]@][host][:port][/db-number]` (see [`redis`](https://www.iana.org/assignments/uri-schemes/prov/redis) and [`rediss`](https://www.iana.org/assignments/uri-schemes/prov/rediss) IANA registration for more details) |
| socket | | Object defining socket connection properties |
| socket.host | `'localhost'` | Hostname to connect to |
| socket.port | `6379` | Port to connect to |
| socket.path | | UNIX Socket to connect to |
| socket.connectTimeout | `5000` | The timeout for connecting to the Redis Server (in milliseconds) |
| socket.noDelay | `true` | Enable/disable the use of [`Nagle's algorithm`](https://nodejs.org/api/net.html#net_socket_setnodelay_nodelay) |
| socket.keepAlive | `5000` | Enable/disable the [`keep-alive`](https://nodejs.org/api/net.html#net_socket_setkeepalive_enable_initialdelay) functionality |
| socket.tls | | Set to `true` to enable [TLS Configuration](https://nodejs.org/api/tls.html#tls_tls_connect_options_callback) |
| socket.reconnectStrategy | `retries => Math.min(retries * 50, 500)` | A function containing the [Reconnect Strategy](#reconnect-strategy) logic |
| username | | ACL username ([see ACL guide](https://redis.io/topics/acl)) |
| password | | ACL password or the old "--requirepass" password |
| database | | Database number to connect to (see [`SELECT`](https://redis.io/commands/select) command) |
| modules | | Object defining which [Redis Modules](../../README.md#modules) to include |
| scripts | | Object defining Lua Scripts to use with this client (see [Lua Scripts](../README.md#lua-scripts)) |
| commandsQueueMaxLength | | Maximum length of the client's internal command queue |
| readonly | `false` | Connect in [`READONLY`](https://redis.io/commands/readonly) mode |
| legacyMode | `false` | Maintain some backwards compatibility (see the [Migration Guide](v3-to-v4.md)) |
| isolationPoolOptions | | See the [Isolated Execution Guide](./isolated-execution.md) |
## Reconnect Strategy
You can implement a custom reconnect strategy as a function that should:
- Receives the number of retries attempted so far.
- Should return `number | Error`:
- `number`: the time in milliseconds to wait before trying to reconnect again.
- `Error`: close the client and flush the commands queue.

56
docs/clustering.md Normal file
View File

@@ -0,0 +1,56 @@
# Clustering
## Basic Example
Connecting to a cluster is a bit different. Create the client by specifying some (or all) of the nodes in your cluster and then use it like a regular client instance:
```typescript
import { createCluster } from 'redis';
(async () => {
const cluster = createCluster({
rootNodes: [
{
url: 'redis://10.0.0.1:30001'
},
{
url: 'redis://10.0.0.2:30002'
}
]
});
cluster.on('error', (err) => console.log('Redis Cluster Error', err));
await cluster.connect();
await cluster.set('key', 'value');
const value = await cluster.get('key');
})();
```
## `createCluster` configuration
> See the [client configuration](./client-configuration.md) page for the `rootNodes` and `defaults` configuration schemas.
| Property | Default | Description |
|------------------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| rootNodes | | An array of root nodes that are part of the cluster, which will be used to get the cluster topology. Each element in the array is a client configuration object. There is no need to specify every node in the cluster, 3 should be enough to reliably connect and obtain the cluster configuration from the server |
| defaults | | The default configuration values for every client in the cluster. Use this for example when specifying an ACL user to connect with |
| useReplicas | `false` | When `true`, distribute load by executing readonly commands (such as `GET`, `GEOSEARCH`, etc.) across all cluster nodes. When `false`, only use master nodes |
| maxCommandRedirections | `16` | The maximum number of times a command will be redirected due to `MOVED` or `ASK` errors |
| modules | | Object defining which [Redis Modules](../../README.md#modules) to include |
| scripts | | Object defining Lua Scripts to use with this client (see [Lua Scripts](../README.md#lua-scripts)) |
## Command Routing
### Commands that operate on Redis Keys
Commands such as `GET`, `SET`, etc. will be routed by the first key, for instance `MGET 1 2 3` will be routed by the key `1`.
### [Server Commands](https://redis.io/commands#server)
Admin commands such as `MEMORY STATS`, `FLUSHALL`, etc. are not attached to the cluster, and should be executed on a specific node using `.getSlot()` or `.getAllMasters()`.
### "Forwarded Commands"
Some commands (e.g. `PUBLISH`) are forwarded to other cluster nodes by the Redis server. The client will send these commands to a random node in order to spread the load across the cluster.

67
docs/isolated-execution.md Normal file
View File

@@ -0,0 +1,67 @@
# Isolated Execution
Sometimes you want to run your commands on an exclusive connection. There are a few reasons to do this:
- You're using [transactions]() and need to `WATCH` a key or keys for changes.
- You want to run a blocking command that will take over the connection, such as `BLPOP` or `BLMOVE`.
- You're using the `MONITOR` command which also takes over a connection.
Below are several examples of how to use isolated execution.
> NOTE: Behind the scences we're using [`generic-pool`](https://www.npmjs.com/package/generic-pool) to provide a pool of connections that can be isolated. Go there to learn more.
## The Simple Secnario
This just isolates execution on a single connection. Do what you want with that connection:
```typescript
await client.executeIsolated(async isolatedClient => {
await isolatedClient.set('key', 'value');
await isolatedClient.get('key');
});
```
## Transactions
Things get a little more complex with transactions. Here we are `.watch()`ing some keys. If the keys change during the transaction, a `WatchError` is thrown when `.exec()` is called:
```typescript
try {
await client.executeIsolated(async isolatedClient => {
await isolatedClient.watch('key');
const multi = isolatedClient.multi()
.ping()
.get('key');
if (Math.random() > 0.5) {
await isolatedClient.watch('another-key');
multi.set('another-key', await isolatedClient.get('another-key') / 2);
}
return multi.exec();
});
} catch (err) {
if (err instanceof WatchError) {
// the transaction aborted
}
}
```
## Blocking Commands
For blocking commands, you can execute a tidy little one-liner:
```typescript
await client.executeIsolated(isolatedClient => isolatedClient.blPop('key'));
```
Or, you can just run the command directly, and provide the `isolated` option:
```typescript
await client.blPop(
commandOptions({ isolated: true }),
'key'
);
```

35
docs/v3-to-v4.md Normal file
View File

@@ -0,0 +1,35 @@
# v3 to v4 Migration Guide
Version 4 of Node Redis is a major refactor. While we have tried to maintain backwards compatibility where possible, several interfaces have changed. Read this guide to understand the differences and how to implement version 4 in your application.
## Breaking Changes
See the [Change Log](../CHANGELOG.md).
## Promises
Node Redis now uses native [Promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) by default for all functions.
## Legacy Mode
Use legacy mode to preserve the backwards compatibility of commands while still getting access to the updated experience:
```typescript
const client = createClient({
legacyMode: true
});
// legacy mode
client.set('key', 'value', 'NX', (err, reply) => {
// ...
});
// version 4 interface is still accessible
await client.v4.set('key', 'value', {
NX: true
});
```
## `createClient`
The configuration object passed to `createClient` has changed significantly with this release. See the [client configuration guide](./client-configuration.md) for details.