MongoDB Database Cleaner

Common errors

• TypeError: clean is not a function

  cause Incorrect import statement. `mongo-clean` exports a single default function.
  fix For CommonJS, use `const clean = require('mongo-clean');`. For ESM, use `import clean from 'mongo-clean';`

• MongoServerError: Authentication failed.

  cause The MongoDB connection URL, username, or password provided are incorrect, or the user lacks the necessary authentication for the database.
  fix Double-check your MongoDB connection string (`mongodb://user:pass@host:port/dbName`) and ensure the user credentials are valid and have access to the target database.

• MongoServerError: command drop requires authentication

  cause The authenticated MongoDB user lacks the required permissions to perform `dropCollection` or `deleteMany` operations on the specified database or collections.
  fix Grant the MongoDB user appropriate roles (e.g., `dbOwner`, `readWrite`) on the target database or specific collections. For testing, a user with `dbOwner` is often sufficient.

Warnings

• gotcha Using 'mongo-clean' on a production database can lead to irreversible data loss. Always ensure your connection string or environment variables are configured to target only test or development instances.
  Fix: Implement robust environment checks (e.g., `if (process.env.NODE_ENV !== 'production')`) before invoking `mongo-clean` in any application logic that might run in a production context.
• gotcha The default 'drop' action completely removes collections, including their indexes, schema, and data. If you need to preserve existing indexes or collection structures while clearing data, use `{ action: 'remove' }`.
  Fix: Pass `{ action: 'remove' }` as the second argument to the `clean` function for soft clearing: `await clean(db, { action: 'remove' });`
• gotcha Ensure the MongoDB client connection is properly closed after cleaning operations. Failing to do so can lead to resource leaks, prevent your script from exiting, or cause unexpected behavior in testing environments.
  Fix: Always include `client.close()` within a `finally` block or ensure your test runner (e.g., Jest, Mocha) handles connection teardown appropriately after tests complete.
• breaking Breaking changes in the underlying `mongodb` driver (e.g., from v3.x to v4.x or v4.x to v5.x) may affect `mongo-clean`'s ability to interact with the database. While `mongo-clean` itself might not change, its runtime compatibility with the `mongodb` package is crucial.
  Fix: Refer to the `mongodb` driver's release notes for compatibility when updating. Ensure your `mongodb` package version aligns with the version `mongo-clean` was developed against, and update `mongo-clean` if a newer version explicitly supports later `mongodb` drivers.

Install

• npm install mongo-clean npm
• yarn add mongo-clean yarn
• pnpm add mongo-clean pnpm

Imports

• clean
  wrong:

  import { clean } from 'mongo-clean'

  correct:

  const clean = require('mongo-clean')

  The primary export for CommonJS is a default function. Do not use named imports with `require`.
• clean (ESM)
  wrong:

  import { clean } from 'mongo-clean'

  correct:

  import clean from 'mongo-clean'

  For ESM projects, `mongo-clean` typically provides a default export. Do not use named imports with `import`.

Quickstart

Demonstrates connecting to MongoDB, populating dummy data, cleaning the database by dropping collections (with exclusions), and then cleaning by removing documents from all collections, illustrating both primary cleaning methods and proper client closure.

const clean = require('mongo-clean');
const { MongoClient } = require('mongodb');

const url = "mongodb://localhost:27017";
const dbName = 'mongocleantest';

async function run() {
  let client;
  try {
    // Connect to MongoDB using recommended options for modern driver
    client = await MongoClient.connect(url, { useNewUrlParser: true, useUnifiedTopology: true });
    const db = client.db(dbName);

    // Optional: insert some dummy data to demonstrate cleaning
    await db.collection('users').insertOne({ name: 'Alice' });
    await db.collection('products').insertOne({ item: 'Laptop' });
    console.log('Database populated with dummy data (users, products).');

    // Clean the database by dropping collections, excluding 'products'
    // This will remove the 'users' collection and its data, but 'products' will remain intact.
    await clean(db, { exclude: ['products'] });
    console.log('Database cleaned (dropping collections, excluding products).');

    let usersCount = await db.collection('users').countDocuments();
    let productsCount = await db.collection('products').countDocuments();
    console.log(`Users collection count: ${usersCount}`); // Should be 0 (collection dropped)
    console.log(`Products collection count: ${productsCount}`); // Should be 1 (original item still exists in retained collection)

    // Re-populate a collection for the next step demonstration
    await db.collection('temp_data').insertOne({ value: 123 });
    console.log('Database re-populated with temporary data for "remove" action.');

    // Clean the database by removing documents from all collections
    // This will empty all collections including 'products' and 'temp_data' (unless explicitly excluded).
    await clean(db, { action: 'remove' });
    console.log('Database cleaned by removing documents from all collections.');

    usersCount = await db.collection('users').countDocuments(); // 'users' collection might be recreated if accessed, but will be empty
    productsCount = await db.collection('products').countDocuments();
    const tempDataCount = await db.collection('temp_data').countDocuments();

    console.log(`Users collection count after 'remove': ${usersCount}`); // Should be 0
    console.log(`Products collection count after 'remove': ${productsCount}`); // Should be 0
    console.log(`Temp Data collection count after 'remove': ${tempDataCount}`); // Should be 0

  } catch (err) {
    console.error('An error occurred:', err);
  } finally {
    if (client) {
      await client.close();
      console.log('MongoDB connection closed.');
    }
  }
}

run();