Local MongoDB Replica Set Runner

0.7.7 verified Thu Apr 23 auth: no javascript

run-rs is a zero-configuration command-line utility designed for spinning up a local MongoDB replica set quickly for development and testing purposes. It eliminates the need for manual MongoDB installations by downloading and managing the MongoDB binaries itself, functioning as a completely self-contained solution. The current stable version is 0.7.7. While there isn't a specified release cadence, the project appears actively maintained with support for various MongoDB versions. A key differentiator is its 'batteries-included' approach, providing a functional replica set with a single command, automatically clearing database data by default for fresh test runs. It supports Linux, macOS, and Windows 10 (via Git Bash/PowerShell).

Common errors

error Error: connect ECONNREFUSED 127.0.0.1:27017 ↓

cause Attempting to connect to a `run-rs` instance on Windows using `localhost` or `127.0.0.1` in the connection string.

fix

Replace localhost or 127.0.0.1 with your computer's network hostname in the MongoDB connection string.

error run-rs: command not found ↓

cause The `run-rs` executable is not in your system's PATH, typically because it was not installed globally or `npx` was not used.

fix

Install run-rs globally using npm install -g run-rs or execute it directly via npx run-rs.

Warnings

gotcha On Windows, do not use `localhost` or `127.0.0.1` in your MongoDB connection string when connecting to a `run-rs` instance. Use your computer's network hostname instead. ↓

fix Use your machine's actual hostname (e.g., `mongodb://YOUR_HOSTNAME:27017,...?replicaSet=rs`) in your connection string.

breaking For MongoDB version 4.2.0 on Linux, `run-rs` defaults to downloading the `ubuntu1604` build. If you require a different Linux distribution's build (e.g., `ubuntu1804`), you must explicitly specify it. ↓

fix Use the `-l` or `--linuxDistro` flag, e.g., `run-rs -v 4.2.0 -l ubuntu1804`.

gotcha By default, `run-rs` purges the database (deletes all data) every time it starts. This is intended for development and testing, ensuring a clean slate. ↓

fix To preserve data across restarts, use the `--keep` (`-k`) flag: `run-rs --keep`.

breaking This tool is strictly for local development and testing. It is explicitly NOT recommended for production environments due to lack of production-grade security and operational features. ↓

fix For production MongoDB deployments, consider managed services like MongoDB Atlas or a self-managed replica set with proper security and backup configurations.

Install

npm install run-rs

yarn add run-rs

pnpm add run-rs

Imports

run-rs command (global)
```
run-rs [options]
```
This package is primarily a command-line interface (CLI) tool. After global installation (`npm install -g run-rs`), execute it directly from your terminal.
run-rs command (npx)
```
npx run-rs [options]
```
Use `npx` to execute the `run-rs` command without a global installation. This is useful for ad-hoc use or in CI environments.

Programmatic usage

wrong

import { startReplicaSet } from 'run-rs';
const runRs = require('run-rs');

correct

// The 'run-rs' package does not expose a programmatic JavaScript API for direct import/require.

This package is strictly a CLI tool. There are no exported symbols or functions for use within Node.js applications via `import` or `require`.

Quickstart

This quickstart demonstrates installing `run-rs` globally, starting a MongoDB 4.0.0 replica set, and immediately connecting a MongoDB shell to interact with it.

npm install -g run-rs

# Start a MongoDB 4.0.0 replica set and connect a shell
run-rs -v 4.0.0 --shell

# Once the shell starts, you can interact with MongoDB
rs:PRIMARY> db.version()
rs:PRIMARY> db.myCollection.insertOne({ name: 'test' })
rs:PRIMARY> db.myCollection.find()

# To stop, exit the shell (Ctrl+C or .exit)