Redis Database Dump Tool

Common errors

• "redis-dump" is not recognized as an internal or external command, operable program or batch file.

  cause The `redis-dump` CLI tool is not found in your system's PATH. This typically occurs if the package was installed locally (`npm install redis-dump`) but not globally (`npm install -g redis-dump`), or if `node_modules/.bin` is not in your PATH.
  fix Install the package globally using `npm install -g redis-dump`. Alternatively, execute it using `npx redis-dump [OPTIONS]` or by referencing its local binary path: `$(npm bin)/redis-dump [OPTIONS]`.

• Error: connect ECONNREFUSED 127.0.0.1:6379

  cause The `redis-dump` tool failed to establish a connection to the Redis server. This usually means the Redis server is not running, is configured to listen on a different host or port, or is blocked by a firewall.
  fix Ensure your Redis server is running and accessible from the machine where `redis-dump` is executed. Verify the host, port, and password by explicitly passing them to `redis-dump` using the `-h`, `-p`, and `-a` arguments.

• SyntaxError: Unexpected token 'export' or 'import' in redis-dump.js

  cause You are attempting to use `redis-dump`, which is a CommonJS module from 2014, with ES module `import` syntax in a modern Node.js environment or build setup that does not correctly transpile or handle CommonJS imports.
  fix Use CommonJS `require()` syntax to load the module: `const program = require('redis-dump');`. Direct programmatic use of its dumping functionality is limited, as the module exports the Commander.js program object rather than a dump function.

Warnings

• breaking The `redis-dump` package is effectively abandoned, with its last publication dating back to March 2014. It is unlikely to be compatible with newer Node.js versions, modern Redis client libraries, or recent Redis server features and data structures, potentially leading to instability or data loss.
  Fix: Consider using actively maintained alternatives like `ioredis` or `node-redis` for programmatic dumping and backup solutions. For CLI-based backups, `redis-cli --rdb` or `redis-cli --scan | xargs redis-cli dump` provide more robust and current options.
• gotcha Despite its description, programmatic usage of `redis-dump` in Node.js is primarily achieved by spawning its command-line interface as a child process (e.g., using `child_process.spawn`). The `require('redis-dump')` statement directly exposes the Commander.js CLI parser object, not a direct function for dumping Redis data.
  Fix: When integrating `redis-dump` into a Node.js application, use `require('child_process').spawn('redis-dump', args)` to execute the CLI tool with desired arguments, rather than attempting to call methods directly from the required module.
• gotcha The package defaults to connecting to a Redis server on `127.0.0.1:6379` without authentication. If your Redis instance is configured differently, requires a password, or is not running on the default host/port, you must explicitly provide the correct hostname, port, and authentication parameters via the command line arguments (`-h`, `-p`, `-a`).
  Fix: Always specify connection details explicitly: `redis-dump -h <host> -p <port> -a <password>`. Use environment variables or a configuration management system to securely handle sensitive data like passwords.
• gotcha When generating Redis commands, the output includes `DEL` commands before `RPUSH`, `SADD`, `ZADD`, `HMSET`, etc. This behavior ensures a clean slate upon re-import but will unconditionally delete and then recreate keys with matching names, potentially overwriting existing data if not handled carefully.
  Fix: Be aware that importing a generated Redis command dump will overwrite existing data for keys present in the dump. If you need to merge data or selectively restore, manual processing or filtering of the dump file is necessary before importing.

Install

• npm install redis-dump npm
• yarn add redis-dump yarn
• pnpm add redis-dump pnpm

Imports

• program
  wrong:

  import program from 'redis-dump';

  correct:

  const program = require('redis-dump');

  The module exports the Commander.js program object used for parsing CLI arguments. It does NOT export a direct function for dumping Redis data programmatically. To utilize its data dumping functionality from Node.js, you must execute the `redis-dump` command as a child process.

Quickstart

This example demonstrates how to use `redis-dump` programmatically by spawning it as a child process to export Redis data in both JSON and Redis command formats, first populating some example data using a modern Redis client.

const redis = require('redis');
const { spawn } = require('child_process');

async function runDump() {
    const client = redis.createClient({
        url: process.env.REDIS_URL || `redis://${process.env.REDIS_HOST || '127.0.0.1'}:${process.env.REDIS_PORT || '6379'}`,
        password: process.env.REDIS_PASSWORD || ''
    });

    client.on('error', (err) => {
        console.error('Redis Client Error', err);
    });

    try {
        await client.connect();

        // Populate some dummy data for demonstration
        await client.del('mydb:numberlist', 'mydb:numberset', 'mydb:numvisits');
        await client.rPush('mydb:numberlist', 'one', 'two', 'three');
        await client.sAdd('mydb:numberset', 'one', 'two', 'three');
        await client.set('mydb:numvisits', '34');
        console.log('Dummy data populated in Redis.');

        // Define common connection arguments for redis-dump CLI
        const commonDumpArgs = [
            '-h', process.env.REDIS_HOST || '127.0.0.1',
            '-p', process.env.REDIS_PORT || '6379',
            '-a', process.env.REDIS_PASSWORD || '',
            '-f', 'mydb:*'
        ];

        // Dump as JSON
        console.log('\n--- Dumping as JSON ---');
        const jsonDumpProcess = spawn('redis-dump', [...commonDumpArgs, '--json', '--pretty']);

        let jsonOutput = '';
        jsonDumpProcess.stdout.on('data', (data) => { jsonOutput += data.toString(); });
        jsonDumpProcess.stderr.on('data', (data) => { console.error(`stderr (JSON dump): ${data}`); });
        await new Promise((resolve, reject) => {
            jsonDumpProcess.on('close', (code) => {
                if (code === 0) { console.log('JSON Dump Output:\n', jsonOutput); resolve(); }
                else { reject(new Error(`redis-dump JSON process exited with code ${code}`)); }
            });
        });

        // Dump as Redis commands
        console.log('\n--- Dumping as Redis Commands ---');
        const commandDumpProcess = spawn('redis-dump', commonDumpArgs);

        let commandOutput = '';
        commandDumpProcess.stdout.on('data', (data) => { commandOutput += data.toString(); });
        commandDumpProcess.stderr.on('data', (data) => { console.error(`stderr (Command dump): ${data}`); });
        await new Promise((resolve, reject) => {
            commandDumpProcess.on('close', (code) => {
                if (code === 0) { console.log('Command Dump Output:\n', commandOutput); resolve(); }
                else { reject(new Error(`redis-dump Command process exited with code ${code}`)); }
            });
        });

    } catch (error) {
        console.error('An error occurred:', error);
    } finally {
        await client.disconnect();
        console.log('Redis client disconnected.');
    }
}

runDump();