Database Schema Updater

Common errors

• Error: Cannot find module 'path/to/my-update.ts' or SyntaxError: Cannot use import statement outside a module

  cause Attempting to use a `.ts` update script without configuring the Node.js runtime to handle TypeScript files, or trying to `require()` an ESM-style `.ts` file in a CJS context.
  fix If using `.ts` files, ensure `ts-node` is installed and registered (e.g., `node -r ts-node/register your-app.js`) or transpile your `.ts` files to `.js` before running. For ESM `.ts` files, ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`) and you're using dynamic `import()` where necessary.

• Error: Update script 'path/to/0.0.1-my-update.js' did not export a function

  cause The update script file does not have the expected function export (`module.exports = function(db){}` or `export default function(db){}`).
  fix Review the update script file to ensure it exports a function with the `(db)` signature correctly. Check for typos in `module.exports` or `export default`.

• MongoError: not master and slaveOk=false

  cause This error occurs when attempting to perform write operations (like creating collections or indexes) on a MongoDB replica set secondary member without appropriate write concerns or read preferences.
  fix Ensure your database connection is directed to the primary replica set member for write operations, or configure appropriate write concerns and read preferences for your `MongoClient` instance if you intend to write to secondaries (which is generally not recommended for migrations).

Warnings

• gotcha TypeScript support is explicitly experimental. It relies on your runtime's ability to dynamically `import()` `.ts` files, which typically requires a specific setup (e.g., using `ts-node` or a custom module loader) and may not work out-of-the-box in standard Node.js environments.
  Fix: Ensure your Node.js runtime environment is configured to handle dynamic TypeScript imports for `.ts` update files. This often involves using a tool like `ts-node/register` or transpiling `.ts` files to `.js` before execution, or configuring Node.js to recognize `.ts` files as modules.
• breaking Update script filenames MUST adhere strictly to Semantic Versioning (SemVer) followed by a dash and description (e.g., `X.Y.Z-description.js`). Incorrect naming will result in scripts not being run or executed in an unexpected order.
  Fix: Verify all update script filenames conform to the `major.minor.patch-description.ext` format. The version part dictates the execution order.
• gotcha Each update script must export a function that accepts the database connection as its first and only argument. This function can be synchronous, asynchronous, or return a Promise. Incorrect export signatures will prevent the script from running.
  Fix: For CommonJS, use `module.exports = function (db) { ... }`. For ES Modules, use `export default function (db) { ... }` or `export default (db) => { ... }`. Ensure the function signature is `(db) => { ... }`.
• gotcha An update script, once successfully run, will never be executed again on the same machine/environment. The applied updates are recorded in a configurable collection (default `databaseUpdates`). If an update needs to be re-run, a new versioned script must be created, or the entry manually removed from the `databaseUpdates` collection.
  Fix: For new changes, create a new update script with an incremented SemVer filename. To force a re-run of an existing script in a development environment, manually delete its entry from the `databaseUpdates` collection in your database.

Install

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

Imports

• databaseUpdates
  wrong:

  const databaseUpdates = require('database-updates').default

  correct:

  import databaseUpdates from 'database-updates'

  For ESM environments, use the default import. The main export is a function that can be called directly.
• databaseUpdates (CommonJS)

  const databaseUpdates = require('database-updates')

  The primary package export is a function, commonly used directly after a CommonJS require.
• DatabaseUpdates (class constructor)
  wrong:

  const { DatabaseUpdates } = require('database-updates').default

  correct:

  import { DatabaseUpdates } from 'database-updates'

  While the quickstart uses the direct function call, the `DatabaseUpdates` class can be instantiated for more control or dependency injection. For CommonJS, use `const { DatabaseUpdates } = require('database-updates');`.

Quickstart

This quickstart demonstrates how to initialize `database-updates` with a MongoDB connection, define an update script, and execute the updates. It creates a temporary update file and ensures the database is updated according to the semver filename.

const { MongoClient } = require('mongodb')
const databaseUpdates = require('database-updates')

async function main() {
  const client = await MongoClient.connect(
    'mongodb://localhost/database-updates-example',
    { useNewUrlParser: true, useUnifiedTopology: true } // Add options for modern MongoClient
  )

  // Optional: Drop the database for a clean run in development
  await client.db().dropDatabase()

  // Define a simple update script path for demonstration
  const updateScriptPath = `${__dirname}/temp_updates`
  require('fs').mkdirSync(updateScriptPath, { recursive: true })
  require('fs').writeFileSync(
    `${updateScriptPath}/0.0.1-initial-collection.js`,
    `module.exports = async (db) => {
      await db.createCollection('users')
      console.log('Created users collection.')
    }`
  )

  console.log('Applying database updates...')
  await databaseUpdates({
    db: client.db(),
    updatePath: updateScriptPath,
    logger: console
  }).run()

  console.log('Done! Check your MongoDB instance for the "users" collection.')
  return client.close()
}

main().catch((e) => {
  console.error('An error occurred:', e)
  process.exit(1)
})