miracle-migrate

library0.1.9jsnpmunverified

RethinkDB migration tool providing up/down migrations with checksum verification to prevent altered migration files. Version 0.1.9 is the latest stable release, with no fixed release cadence. Ships TypeScript types. Key differentiator: it integrates directly with RethinkDB, manages a `miracle-migrations` table for tracking, and supports both CLI and programmatic use via `doUp`/`doDown`. Compared to other RethinkDB migration tools like `rethink-migrate`, it offers the uniqueness of checksumming and config-driven setup.

database

npm install miracle-migrate

package ↗

INSTALL

IMPORT

SIG · MIRACLE-MIGRATE

miracle-migrate

databasejavascriptv0.1.9

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

doUp

✓ import { doUp } from 'miracle-migrate'

✗ import doUp from 'miracle-migrate'

Named export, not default export. Must use named import syntax.

doDown

✓ import { doDown } from 'miracle-migrate'

✗ const { doDown } = require('miracle-migrate')

CommonJS require works, but TypeScript types require ESM import. For Node.js CJS, use destructured require.

MiracleMigrateConfig

✓ import type { MiracleMigrateConfig } from 'miracle-migrate'

✗ import { MiracleMigrateConfig } from 'miracle-migrate'

This is a type-only import. Use `import type` for type checking to avoid runtime issues.

Shows how to programmatically run migrations using doUp with a custom connection and optional filename.

import { doUp } from 'miracle-migrate'; import { r } from 'rethinkdb'; const connectionOptions = { host: 'localhost', port: 28015, db: 'my_database' }; doUp('my_database', connectionOptions, '20200101000000_initial_migration.js').then(() => { console.log('Migrations applied successfully'); }).catch((err: Error) => { console.error('Migration failed:', err); });

Debug

Known issues

gotchaThe CLI command `miracle-migrate create-migration <name>` is the only way to generate migration templates; manual creation may omit required exports.

fix

Use `npx miracle-migrate create-migration <name>` to generate properly structured migration files.

affects: >=0.0.0

gotchaMigrations are applied in alphabetical order by filename. Ensure filenames are sortable (e.g., use timestamps like `20200101000000`).

fix

Use a naming convention with ISO 8601-like timestamps or sequential numbers.

affects: >=0.0.0

gotchaA `miracle-migrate.json` config file is required in the project root for CLI commands, but programmatic usage with doUp/doDown bypasses this requirement.

fix

For programmatic usage, you don't need config file; pass connection options directly.

affects: >=0.0.0

breakingThe package creates a `miracle-migrations` table in the specified database. If that table already exists (e.g., from a previous version), migration may fail.

fix

Before running migrations, check if the `miracle-migrations` table exists and is compatible. You may need to drop or back it up.

affects: >=0.0.0

deprecatedThe library is not actively maintained; last release was 0.1.9 and there have been no updates for years. No support for RethinkDB version differences.

fix

Consider alternatives like `rethink-migrate` or migration scripts using the RethinkDB driver directly.

affects: <0.2.0

Errors

Common errors & fixes

Error: Cannot find module 'miracle-migrate'

Package not installed or not in node_modules.

fix

Run `npm install miracle-migrate` or `yarn add miracle-migrate`.

TypeError: doUp is not a function

Incorrect import syntax (default import instead of named import).

fix

Use `import { doUp } from 'miracle-migrate';` instead of `import doUp from 'miracle-migrate';`.

Error: Config file not found: miracle-migrate.json

CLI command but no config file in project root.

fix

Create a `miracle-migrate.json` file with migration directory and connection settings, or use programmatic API.

Error: Table 'miracle-migrations' already exists

The library tries to create the migrations table on first run, but it may already exist from a previous run or manual creation.

fix

Drop the existing `miracle-migrations` table manually using the RethinkDB admin console or a script, then retry.

Upgrade

Version history

0.1.9latest on npm

Audit

Dependencies

rethinkdbrequiredRequired peer dependency for database operations. The migration library interacts with RethinkDB and relies on the `rethinkdb` driver.

yargsoptionalUsed for CLI argument parsing. Required for the command-line interface.

Agent activity

9 hits · last 30 days

node

Amazon

Resources

packagemiracle-migrate ↗