{"id":16419,"library":"larvitdbmigration","title":"Larvit Database Migration Tool","description":"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.","status":"active","version":"7.0.188","language":"javascript","source_language":"en","source_url":"https://github.com/larvit/larvitdbmigration","tags":["javascript","db","mysql","mariadb","migration","elasticsearch","typescript"],"install":[{"cmd":"npm install larvitdbmigration","lang":"bash","label":"npm"},{"cmd":"yarn add larvitdbmigration","lang":"bash","label":"yarn"},{"cmd":"pnpm add larvitdbmigration","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for MariaDB/MySQL database connectivity when using the 'mariadb' dbType. Provides the `dbDriver` instance.","package":"larvitdb","optional":false},{"reason":"Used internally for Elasticsearch connectivity. Can be optionally provided by the user to customize HTTP client behavior.","package":"axios","optional":true}],"imports":[{"note":"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.","wrong":"const DbMigration = require('larvitdbmigration');","symbol":"DbMigration","correct":"import { DbMigration } from 'larvitdbmigration';"},{"note":"For type-checking and autocompletion when configuring `DbMigration` in TypeScript projects.","symbol":"IDbMigrationOptions","correct":"import type { IDbMigrationOptions } from 'larvitdbmigration';"},{"note":"For type-checking parameters passed to individual migration script functions (e.g., `db`, `url`, `log`).","symbol":"IMigrationScriptOptions","correct":"import type { IMigrationScriptOptions } from 'larvitdbmigration';"}],"quickstart":{"code":"import { DbMigration } from 'larvitdbmigration';\nimport Db from 'larvitdb'; // Assuming 'larvitdb' is installed for MariaDB/MySQL\n\nconst log = {\n  silly: (...args: any[]) => console.log('[SILLY]', ...args),\n  debug: (...args: any[]) => console.debug('[DEBUG]', ...args),\n  verbose: (...args: any[]) => console.log('[VERBOSE]', ...args),\n  info: (...args: any[]) => console.info('[INFO]', ...args),\n  warn: (...args: any[]) => console.warn('[WARN]', ...args),\n  error: (...args: any[]) => console.error('[ERROR]', ...args),\n};\n\nasync function runMigrations() {\n  // Ensure environment variables are set or provide fallbacks\n  const dbConfig = {\n    host: process.env.DB_HOST ?? '127.0.0.1',\n    user: process.env.DB_USER ?? 'root',\n    password: process.env.DB_PASSWORD ?? 'password',\n    database: process.env.DB_NAME ?? 'test_db',\n  };\n\n  const dbDriver = new Db(dbConfig);\n\n  const dbMigration = new DbMigration({\n    dbType: 'mariadb',\n    dbDriver,\n    tableName: 'db_version', // Optional, default is 'db_version'\n    migrationScriptPath: './dbmigration_scripts', // Ensure this directory exists with migration files\n    log, // Pass a logger instance\n  });\n\n  try {\n    console.log('Starting database migrations...');\n    await dbMigration.run();\n    console.log('Database migrations completed successfully!');\n  } catch (err) {\n    console.error('Database migration failed:', err);\n    process.exit(1);\n  }\n}\n\n// To run this example, create a './dbmigration_scripts/1.js' file like this:\n/*\n  // ./dbmigration_scripts/1.js\n  import type { IMigrationScriptOptions } from 'larvitdbmigration';\n\n  export = async function (options: IMigrationScriptOptions) {\n    const { db } = options;\n    await db.query('CREATE TABLE IF NOT EXISTS test_table (id INT AUTO_INCREMENT PRIMARY KEY, name VARCHAR(255));');\n    options.log.info('Created test_table');\n  };\n*/\n\nrunMigrations();","lang":"typescript","description":"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."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":">=7.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=6.0.0 <7.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[],"ecosystem":"npm"}