Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
marv (Promise API)
✓ const marv = require('marv/api/promise');
✗ import marv from '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)
✓ const marv = require('marv/api/callback');
✗ import marv from 'marv/api/callback';
Similar to the promise API, the callback-based API is accessed via `marv/api/callback` using CommonJS `require`.
marv-pg-driver
✓ const pgDriver = require('marv-pg-driver');
✗ import pgDriver from '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`.
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();
marv --version
Debug
Known issues
gotchaMarv 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`).fixEnsure 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.
affects: >=4.0.0
breakingMarv 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.fixAdopt 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.
affects: >=4.0.0
gotchaMarv 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.fixAlways 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.
affects: >=4.0.0
gotchaWhen 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.fixInstall `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.
affects: >=4.0.0 (when using `marv-mysql-driver` with MySQL 8.0+)
Errors
Common errors & fixes
Error: Duplicate migration level detected: [level] - [filename1] and [filename2]
Two or more migration files have the same numeric level in their filenames, which violates Marv's strict ordering requirement.
fixRename 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.
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.
fixInvestigate 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)
The specific database driver package required by Marv for your chosen database (e.g., PostgreSQL, MySQL) has not been installed.
fixInstall the correct Marv driver package for your database using npm, e.g., `npm install marv-pg-driver` or `npm install marv-mysql-driver`.
Audit
Dependencies
marv-pg-driverrequiredRequired for PostgreSQL database migrations.
marv-mysql-driverrequiredRequired for MySQL database migrations.
@open-fidias/marv-better-sqlite3-driverrequiredRequired for SQLite database migrations.
@infinitaslearning/marv-mssql-driverrequiredRequired for Microsoft SQL Server database migrations.
marv-oracledb-driverrequiredRequired for Oracle DB database migrations.