npm

mongo-cleaner

An npm module to quickly clean your mongodb, both from code and cli.

Install

To install mongo-cleaner as a local module:

$ npm install mongo-cleaner

To install mongo-cleaner as a global module:

$ npm install -g mongo-cleaner

Usage (local module)

Clear everything

const mongoCleaner = require('mongoCleaner');
await mongoCleaner.clean();

Specify connection

const mongoCleaner = require('mongoCleaner');
const uri = 'mongodb://localhost:27017';
const mongoClientOptions = { numberOfRetries: 10 };

await mongoCleaner.clean(uri, mongoClientOptions);

Ask a confirm and show logs

const mongoCleaner = require('mongoCleaner');
const options = {
    noConfirm: false,
    log: true
};

await mongoCleaner.clean(null, null, options);

Keep some databases

const mongoCleaner = require('mongoCleaner');
const options = {
    keep: ['animals', /test$/]
};

await mongoCleaner.clean(null, null, options);

Only remove collections' documents

const mongoCleaner = require('mongoCleaner');
const options = {
    dropDatabases: false,
    emptyDatabases: false,
    emptyCollections: true
};

await mongoCleaner.clean(null, null, options);

Only drop collections or remove their documents as a fallback

const mongoCleaner = require('mongoCleaner');
const options = {
    dropDatabases: true,
    emptyDatabases: true,
    emptyCollections: true
};

await mongoCleaner.clean(null, null, options);

Throw an error if only partially cleaned

const mongoCleaner = require('mongoCleaner');
const options = {
    throwIfNotTotal: true
};

await mongoCleaner.clean(null, null, options);

Usage (global module)

Clear everything

$ mongo-cleaner clean

This way everything on mongodb://localhost:27017 will be cleaned

Skip confirmation

$ mongo-cleaner clean -y

This way no proceeding-confirmation will be asked.

Keep databases

$ mongo-cleaner clean --keep first second /test$/i

This way first, second and all databases that end with "test" (case-insensitive) will be keeped.

Specify uri

$ mongo-cleaner clean --uri mongodb://localhost:8080

This way everything on mongodb://localhost:8080 will be cleaned.

Specify uri with other options

$ mongo-cleaner clean --host localhost --port 27017 --username euber --password secret --srv

This way everything on srv+mongodb://euber:pass@localhost:27017 will be cleaned.

Specify options file

$ mongo-cleaner clean -o mongo-cleaner.config.json -y

This way options will be taken by the file ./mongo-cleaner.config.json. These options do not overwrite the command ones, so in every case of this example no confirmation to proceed will be asked.

See all options

$ mongo-cleaner --help

API

clean

Syntax:

mongoCleaner.clean(uri, connectionOptions, options)

Description:

Tries to remove all the databases of MongoDB. The function is asynchronous and returns nothing. See Usage to have an example.

Parameters:

uri: Optional. The string uri of the mongodb connection. Default: mongodb://localhost:27017.
connectionOptions: Optional. The options for the MongoDB connection. This function uses the npm module mongodb under the hood, so these are the MongoClientOptions. By default, if not explicitly set to false, "useUnifiedTopology" and "useNewUrlParser" are set to true.
options: Optional. The MongoCleanerOptions object for the cleaner. You can specify things such as asking a confirm before cleaning, databases to be kept, keeping collections and removing their documents.

MongoCleanerOptions parameters:

noConfirm: Default value: true. If you want the method to skip asking confirm before cleaning the MongoDB.
keep: Default value: []. A string, a RegExp, a (db: name) => boolean or an array of all of them specifying databases that will not be cleaned.
log: Default value: false. If you want to display the clean method's log on console.
dropDatabases: Default value: true. If you want to drop the whole database. NB: The admin database cannot be dropped and is ignored.
emptyDatabases: Default value: false. If you want to drop databases' collections without dropping the databases. If both "dropDatabases" and this options are true, this option will be used as a fallback if a database drop fails.
emptyCollections: Default value: false. If you want to empty collections without dropping them and their databases. If both "emptyDatabases" and this options are true, this option will be used as a fallback if a collection drop fails. NB: If "dropDatabases", "emptyDatabases" and "emptyCollections" are all false, this option will eventually become true.
numberOfRetries: Default value: 1. The number of times a drop or empty operation is retried before throwing an error or passing to a fallback.
retryMilliseconds: Default value: 20. The number of milliseconds between two attempts of a drop or empty operation.
throwIfNotTotal: Default value: false. If you want to throw a MongoCleanerCleanError when MongoDB is only partially cleaned.

Project structure

Made with dree.

mongo-cleaner
 ├─> dist
 ├─> source
 │   ├─> bin
 │   │   ├── index.ts
 │   │   └─> utils
 │   │       └── index.ts
 │   └─> lib
 │       ├─> errors
 │       │   ├── index.ts
 │       │   ├── mongoCleanerCleanError.ts
 │       │   ├── mongoCleanerConnectionError.ts
 │       │   ├── mongoCleanerDisconnectionError.ts
 │       │   ├── mongoCleanerError.ts
 │       │   ├── mongoCleanerListCollectionsError.ts
 │       │   └── mongoCleanerListDatabasesError.ts
 │       ├── index.ts
 │       ├─> interfaces
 │       │   └── index.ts
 │       └─> utils
 │           ├── askConfirm.ts
 │           ├── cleaner.ts
 │           ├── logger.ts
 │           └── options.ts
 ├─> test
 │   ├── clean.test.js
 │   ├─> mock
 │   └── test.js
 ├─> docs
 │   ├─> html
 │   └─> tree
 │       ├── dree.config.json
 │       └── tree.txt
 ├── LICENSE
 ├── .npmignore
 ├── package-lock.json
 ├── package.json
 ├── tsconfig.json
 └── tslint.json

Development

To build the module make sure you have the dev dependencies installed.

The project is written in Typescript, bundled with Webpack and linted with ESLint.

Lint

In order to lint the code:

$ npm run lint

In order to lint and fix the code:

$ npm run lint:fix

There are also the :source and :test suffix after lint in order to lint only the source code or the test code.

Transpile

To transpile the source code:

$ npm run transpile

The source folder will be transpiled in the dist folder. Also the type declarations will be generated.

Test

Note: Running tests will delete permanently your MongoDB data. Do not do it if you have important data on it.

After having transpiled the code, run:

$ npm test

in order to run the tests with mocha.

If a coverage report is to be generated, run:

$ npm run nyc

Bundle

$ npm run bundle

The source folder will be compiled in the bundled folder. It will contain the bundled lib/index.js, lib/index.d.ts and bin/index.js files.