Larvit Database Migration Tool

7.0.188 · active · verified Wed Apr 22

larvitdbmigration is a Node.js utility designed for managing database schema and data evolution through a versioned script approach. It supports both traditional relational databases like MariaDB (and MySQL) and NoSQL solutions such as Elasticsearch. Currently stable at version 7.0.188, the package appears to have an active release cadence, frequently publishing patches and minor features as indicated by the high patch number within the 7.x series. A key differentiator is its ability to handle migrations across diverse database types within a single framework. It utilizes simple JavaScript or SQL files for migration scripts, providing flexibility for complex logic or straightforward DDL statements. The tool automatically creates and updates a `db_version` table or index to track the current database state, ensuring migrations are applied only once and in the correct order.

Warnings

breaking Version 7.0.0 replaced `got` with `axios` for HTTP requests. If you were passing a custom `got` instance to the Elasticsearch driver, this will no longer work and must be updated to an `axios` instance.
Fix: Review Elasticsearch configurations. If a custom HTTP client was provided, replace `got` with `axios`. Ensure any migration scripts using `got` are updated to `axios`.
breaking Version 6.0.0 introduced significant changes: The library was rewritten in TypeScript, `request` was replaced with `got` (later replaced by `axios` in v7), and the Elasticsearch migration driver now only passes `url` and `log` instances to migration scripts, no longer the full driver instance. Additionally, the locking mechanism for Elasticsearch migrations was removed as it's not supported.
Fix: Update imports to TypeScript syntax (`import { ... } from 'pkg'`). Review Elasticsearch migration scripts to ensure they only rely on `url` and `log` from the options object. Remove any code relying on Elasticsearch locking.
gotcha When both a `.js` and a `.sql` file exist for the same migration version (e.g., `1.js` and `1.sql`), the `.sql` file will be ignored. The JavaScript file takes precedence.
Fix: Ensure only one migration file type (.js or .sql) exists per version. Use `.js` files for complex logic and `.sql` for simple DDL statements only when no `.js` file is present for that version.
gotcha The migration tool creates a `db_version` table (for MariaDB/MySQL) or an index (for Elasticsearch) by default to track the current database version. Ensure this name (`db_version`) does not conflict with existing tables/indices, or specify a custom `tableName`/`indexName` in the configuration.
Fix: Check for name conflicts with `db_version`. If a conflict exists or a different name is preferred, set the `tableName` or `indexName` option in the `DbMigration` constructor to a unique name.

Install

npm install larvitdbmigration npm
yarn add larvitdbmigration yarn
pnpm add larvitdbmigration pnpm

Imports

DbMigration
wrong:
```
const DbMigration = require('larvitdbmigration');
```
correct:
```
import { DbMigration } from 'larvitdbmigration';
```
Since version 6.0.0, the library was rewritten in TypeScript and is primarily designed for ESM usage. While CommonJS `require` might still work in some environments, ESM `import` is the recommended and type-safe approach.
IDbMigrationOptions
```
import type { IDbMigrationOptions } from 'larvitdbmigration';
```
For type-checking and autocompletion when configuring `DbMigration` in TypeScript projects.
IMigrationScriptOptions
```
import type { IMigrationScriptOptions } from 'larvitdbmigration';
```
For type-checking parameters passed to individual migration script functions (e.g., `db`, `url`, `log`).

Quickstart

Demonstrates how to initialize and run database migrations for MariaDB using environment variables for sensitive credentials, including a basic logger and an example migration script.

import { DbMigration } from 'larvitdbmigration';
import Db from 'larvitdb'; // Assuming 'larvitdb' is installed for MariaDB/MySQL

const log = {
  silly: (...args: any[]) => console.log('[SILLY]', ...args),
  debug: (...args: any[]) => console.debug('[DEBUG]', ...args),
  verbose: (...args: any[]) => console.log('[VERBOSE]', ...args),
  info: (...args: any[]) => console.info('[INFO]', ...args),
  warn: (...args: any[]) => console.warn('[WARN]', ...args),
  error: (...args: any[]) => console.error('[ERROR]', ...args),
};

async function runMigrations() {
  // Ensure environment variables are set or provide fallbacks
  const dbConfig = {
    host: process.env.DB_HOST ?? '127.0.0.1',
    user: process.env.DB_USER ?? 'root',
    password: process.env.DB_PASSWORD ?? 'password',
    database: process.env.DB_NAME ?? 'test_db',
  };

  const dbDriver = new Db(dbConfig);

  const dbMigration = new DbMigration({
    dbType: 'mariadb',
    dbDriver,
    tableName: 'db_version', // Optional, default is 'db_version'
    migrationScriptPath: './dbmigration_scripts', // Ensure this directory exists with migration files
    log, // Pass a logger instance
  });

  try {
    console.log('Starting database migrations...');
    await dbMigration.run();
    console.log('Database migrations completed successfully!');
  } catch (err) {
    console.error('Database migration failed:', err);
    process.exit(1);
  }
}

// To run this example, create a './dbmigration_scripts/1.js' file like this:
/*
  // ./dbmigration_scripts/1.js
  import type { IMigrationScriptOptions } from 'larvitdbmigration';

  export = async function (options: IMigrationScriptOptions) {
    const { db } = options;
    await db.query('CREATE TABLE IF NOT EXISTS test_table (id INT AUTO_INCREMENT PRIMARY KEY, name VARCHAR(255));');
    options.log.info('Created test_table');
  };
*/

runMigrations();

view raw JSON →