Database Cleaner for Node.js

Common errors

• Error: Cannot find module 'database-cleaner'

  cause The package `database-cleaner` is not installed or not resolvable in the current Node.js environment.
  fix Run `npm install database-cleaner` in your project directory.

• ER_BAD_DB_ERROR: Unknown database 'database_cleaner'

  cause When using MySQL or PostgreSQL, the `database_cleaner` database, which the tests and potentially the cleaner expect, has not been created on the database server.
  fix For MySQL, run `mysql -u root -e 'create database database_cleaner;'`. For PostgreSQL, run `createdb database_cleaner`.

• TypeError: Cannot read properties of undefined (reading 'clean') or TypeError: databaseCleaner.clean is not a function

  cause The `databaseCleaner` object was not correctly instantiated as a new instance of `DatabaseCleaner`, or the `DatabaseCleaner` class itself was not imported correctly.
  fix Ensure you are using `const databaseCleaner = new DatabaseCleaner(type);` after `const DatabaseCleaner = require('database-cleaner');`.

Warnings

• breaking The `database-cleaner` package is effectively abandoned, with its last update approximately nine years ago. It is unlikely to be compatible with modern Node.js versions (e.g., Node.js 14+ or current LTS releases) or contemporary versions of database drivers (e.g., `mongodb` v4+, `redis` v4+, `pg` v8+).
  Fix: Consider using actively maintained alternatives such as `jest-mongodb` for MongoDB, custom database setup/teardown scripts, or frameworks with built-in test utilities for database resets.
• gotcha The `cradle` dependency for CouchDB support is an extremely outdated driver and is no longer maintained. Using it can lead to severe compatibility issues with modern CouchDB versions and Node.js, and may pose security risks.
  Fix: Avoid using the CouchDB cleaner functionality within this package. If CouchDB testing is required, implement custom cleaning logic using a modern CouchDB client.
• gotcha For MySQL and PostgreSQL, specific cleaning strategies ('truncation' or 'deletion') must be explicitly configured in a `config/cleaner-config.js` file, otherwise default behavior might not be as expected. Missing this configuration can lead to incomplete data resets.
  Fix: Ensure a `config/cleaner-config.js` file is present at the root of your project with the desired strategy, e.g., `{ postgresql: { strategy: 'truncation', skipTables: [] } }`.
• gotcha The package's transitive dependencies (e.g., specific versions of `mongodb`, `redis`, `mysql`) are likely very old. Installing this package might pull in insecure or incompatible versions of these drivers, leading to runtime errors or security vulnerabilities in your application.
  Fix: Thoroughly inspect `npm ls` output for `database-cleaner` to identify outdated dependencies. Pin modern versions of database drivers if possible, but be aware this may cause conflicts with `database-cleaner`'s internal requirements.

Install

• npm install database-cleaner npm
• yarn add database-cleaner yarn
• pnpm add database-cleaner pnpm

Imports

• DatabaseCleaner
  wrong:

  import DatabaseCleaner from 'database-cleaner';

  correct:

  const DatabaseCleaner = require('database-cleaner');

  This package primarily uses CommonJS `require` syntax and does not provide an official ESM entry point. Direct ESM import is not supported.
• databaseCleaner instance
  wrong:

  const databaseCleaner = DatabaseCleaner();

  correct:

  const databaseCleaner = new DatabaseCleaner('mongodb');

  The `DatabaseCleaner` class must be instantiated with `new` and requires a database type string ('mongodb', 'redis', 'couchdb', 'mysql', 'postgres', 'elasticsearch').
• clean method
  wrong:

  DatabaseCleaner.clean(dbConnection, () => {});

  correct:

  databaseCleaner.clean(dbConnection, () => console.log('Database cleaned'));

  The `clean` method is an instance method, not a static method of the `DatabaseCleaner` class.

Quickstart

Demonstrates how to import the `database-cleaner` module, instantiate it for a specific database type, and call the `clean` method with a placeholder database connection and callback.

const DatabaseCleaner = require('database-cleaner');

// Example for MongoDB. In a real application, 'db' would be a connected database object.
// The exact 'database' object type depends on the specific driver (e.g., mongoose connection, node-mongodb-native Db object).
const type = 'mongodb'; // Can be 'mongodb', 'redis', 'couchdb', 'mysql', 'postgres', 'elasticsearch'

// For demonstration, we'll use a placeholder for the database connection object.
// In a real scenario, this would be an active connection instance.
const dummyDbConnection = { name: 'myTestDb', close: () => console.log('Dummy DB closed.') };

const databaseCleaner = new DatabaseCleaner(type);

console.log(`Attempting to clean database of type: ${type}...`);

databaseCleaner.clean(dummyDbConnection, (err) => {
  if (err) {
    console.error('Error cleaning database:', err.message);
    process.exit(1);
  } else {
    console.log(`Successfully simulated cleaning ${type} database.`);
    // In a real test suite, you might close the connection here or let the test runner handle it.
    // dummyDbConnection.close();
    process.exit(0);
  }
});