Marv

Common errors

• Error: Duplicate migration level detected: [level] - [filename1] and [filename2]

  cause Two or more migration files have the same numeric level in their filenames, which violates Marv's strict ordering requirement.
  fix Rename one of the conflicting migration files to ensure all numeric levels are unique within the migrations directory.

• Error: Migration [level] has been run out of sequence.

  cause A migration script was detected that should have been run earlier based on its numeric level but was not, indicating an inconsistent database state or a deployment issue.
  fix Investigate the database history to understand which migration was skipped or run incorrectly. If necessary, manually revert the database to a consistent state, or adjust the schema history table (if safe) to reflect the actual applied migrations, then re-run. Ensure migration files are applied in strict ascending order of their levels.

• Error: Cannot find module 'marv-pg-driver' (or similar for other drivers)

  cause The specific database driver package required by Marv for your chosen database (e.g., PostgreSQL, MySQL) has not been installed.
  fix Install the correct Marv driver package for your database using npm, e.g., `npm install marv-pg-driver` or `npm install marv-mysql-driver`.

Warnings

• gotcha Marv deliberately does not run migration scripts within a transaction. This means that if a script fails mid-execution, partial changes may be applied, and manual cleanup might be required. It is strongly recommended to make migration scripts idempotent (e.g., using `CREATE TABLE IF NOT EXISTS`).
  Fix: Ensure all SQL migration scripts are idempotent. For example, use `CREATE TABLE IF NOT EXISTS` instead of `CREATE TABLE` where applicable. Plan for manual rollback/cleanup strategies for non-idempotent operations.
• breaking Marv enforces a strict sequential order for migrations. Attempting to run migrations with duplicate numeric levels or running migrations out of their detected sequence will result in errors. This has implications for branching strategies where multiple developers might create migrations concurrently.
  Fix: Adopt a clear branching and merge strategy for migrations (e.g., rebase and renumber migrations before merging). Ensure migration filenames adhere to the `<level><separator><comment>.<extension>` format with unique numeric levels. Manually resolve ordering conflicts before running migrations.
• gotcha Marv requires a specific database driver package (e.g., `marv-pg-driver`, `marv-mysql-driver`) to be installed alongside it. Forgetting to install the correct driver for your target database will lead to runtime errors when attempting to connect or migrate.
  Fix: Always install the appropriate `marv-*` driver package for your database (e.g., `npm install marv-pg-driver`). Check the `marv` documentation for the correct driver name.
• gotcha When using `marv-mysql-driver` with MySQL 8.0+, you may encounter authentication issues because MySQL 8.0 changed its default authentication plugin to `caching_sha2_password`. The underlying `mysql` library might not support this, requiring `mysql2` or a server configuration change.
  Fix: Install `mysql2` alongside `marv-mysql-driver` (`npm install mysql2`), as `marv-mysql-driver` will automatically use it. Alternatively, configure your MySQL 8.0 server to use `mysql_native_password` as the default authentication plugin.

Install

• npm install marv npm
• yarn add marv yarn
• pnpm add marv pnpm

Imports

• marv (Promise API)
  wrong:

  import marv from 'marv/api/promise';

  correct:

  const marv = require('marv/api/promise');

  Marv exports its API as a default CommonJS object from specific paths. The promise-based API is accessed via `marv/api/promise`. Destructuring like `const { scan } = require('marv/api/promise');` is incorrect as the module exports a single object, not named properties. Direct ESM `import` is not natively supported without a CJS wrapper or bundler due to the package's CommonJS module type.
• marv (Callback API)
  wrong:

  import marv from 'marv/api/callback';

  correct:

  const marv = require('marv/api/callback');

  Similar to the promise API, the callback-based API is accessed via `marv/api/callback` using CommonJS `require`.
• marv-pg-driver
  wrong:

  import pgDriver from 'marv-pg-driver';

  correct:

  const pgDriver = require('marv-pg-driver');

  Database drivers like `marv-pg-driver` are separate packages and must be installed alongside `marv`. They typically export a default function via CommonJS `require`.

Quickstart

This quickstart demonstrates how to use Marv with its Promise API and a PostgreSQL driver to scan for and apply migrations from a local directory. It includes boilerplate for database connection configuration and creates a sample migration file if none exists for immediate execution.

const path = require('path');
const marv = require('marv/api/promise');
const pgDriver = require('marv-pg-driver');

const migrationsDirectory = path.resolve(__dirname, 'migrations');

// Create a dummy migrations directory and file for demonstration
const fs = require('fs');
if (!fs.existsSync(migrationsDirectory)) {
  fs.mkdirSync(migrationsDirectory);
}
const migrationFile = path.join(migrationsDirectory, '001.create-test-table.sql');
if (!fs.existsSync(migrationFile)) {
  fs.writeFileSync(migrationFile, 'CREATE TABLE IF NOT EXISTS test_table (id SERIAL PRIMARY KEY, name VARCHAR(255));');
}

async function runMigrations() {
  try {
    // Placeholder for actual PostgreSQL connection details
    const connection = {
      host: process.env.DB_HOST ?? 'localhost',
      port: parseInt(process.env.DB_PORT ?? '5432', 10),
      user: process.env.DB_USER ?? 'postgres',
      password: process.env.DB_PASSWORD ?? 'password',
      database: process.env.DB_NAME ?? 'mydatabase',
      // Optional: ssl: { rejectUnauthorized: false } for local testing if needed
    };

    const migrations = await marv.scan(migrationsDirectory);
    await marv.migrate(migrations, pgDriver({ connection }));
    console.log('Migrations applied successfully!');
  } catch (err) {
    console.error('Migration failed:', err.message);
    process.exit(1);
  }
}

runMigrations();