{"id":17208,"library":"east","title":"east - Database Migration Tool","description":"east is a Node.js database migration tool designed to manage schema changes across various database systems including MongoDB, SQLite, PostgreSQL, MySQL, and Couchbase. Currently stable at version 2.0.3, it primarily focuses on providing a robust CLI for migration management but also offers programmatic access. Its core philosophy is to integrate with existing database drivers, allowing developers to use their familiar database-specific syntax within migration scripts rather than imposing a universal ORM or query builder. This tool supports Node.js versions 10.17.0 and higher, with specific adapter requirements potentially varying. It actively supports modern JavaScript features, including TypeScript for migration files and ECMAScript Modules (ESM) for configuration and migrations, making it adaptable to contemporary Node.js project setups. Releases appear to be driven by feature development and maintenance needs.","status":"active","version":"2.0.3","language":"javascript","source_language":"en","source_url":"git://github.com/okv/east","tags":["javascript","migrate","migration","database","db","mongodb","sqlite","postgres","mysql","typescript"],"install":[{"cmd":"npm install east","lang":"bash","label":"npm"},{"cmd":"yarn add east","lang":"bash","label":"yarn"},{"cmd":"pnpm add east","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"east exports named functions for its core commands (migrate, rollback, create, init, list). While CommonJS `require` is supported, ESM `import` is generally preferred in modern Node.js environments with `\"type\": \"module\"` in `package.json` or the `--es-modules` flag.","wrong":"const east = require('east'); east.migrate(...);","symbol":"migrate","correct":"import { migrate } from 'east';"},{"note":"This named export is used programmatically to generate new migration files. Typically, this action is initiated via the `east create` CLI command.","wrong":"import East from 'east'; East.create(...);","symbol":"create","correct":"import { create } from 'east';"},{"note":"east ships with TypeScript type definitions. For type-safe programmatic usage, you can import `EastConfig` and other relevant types to define the configuration object and parameters.","symbol":"EastConfig","correct":"import type { EastConfig } from 'east';"}],"quickstart":{"code":"import { migrate, create } from 'east';\nimport path from 'node:path';\nimport { fileURLToPath } from 'node:url';\nimport { promises as fs } from 'node:fs';\n\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = path.dirname(__filename);\nconst migrationsDir = path.join(__dirname, 'my-app-migrations');\n\n// A minimal mock adapter for demonstration purposes.\n// In a real application, you would install and use an official adapter\n// like `east-adapter-mongodb` or `east-adapter-pg`.\nconst mockAdapter = {\n  connect: async (url) => {\n    console.log(`[Mock DB] Attempting connection to ${url}...`);\n    return { client: {}, db: { // Simulate a minimal DB object\n      collection: (name) => ({ // Mock a collection for storing migration names\n        find: () => ({ toArray: async () => [] }), // No executed migrations initially\n        insertOne: async (doc) => { console.log(`[Mock DB] Storing migration record: ${doc.name}`); },\n        deleteOne: async (query) => { console.log(`[Mock DB] Removing migration record: ${query.name}`); }\n      })\n    } };\n  },\n  disconnect: async () => { console.log('[Mock DB] Disconnecting...'); },\n  getExecutedMigrationNames: async (db) => {\n    // In a real adapter, this would query a specific collection/table.\n    return db.collection('east_migrations').find().toArray().then(docs => docs.map(d => d.name));\n  },\n  markMigrationExecuted: async (db, name) => {\n    await db.collection('east_migrations').insertOne({ name, createdAt: new Date() });\n    console.log(`[Mock DB] Marked migration '${name}' as executed.`);\n  },\n  unmarkMigrationExecuted: async (db, name) => {\n    await db.collection('east_migrations').deleteOne({ name });\n    console.log(`[Mock DB] Unmarked migration '${name}' (rolled back).`);\n  }\n};\n\nasync function runEastProgrammatically() {\n  // Ensure migration directory exists (equivalent to parts of `east init` CLI)\n  await fs.mkdir(migrationsDir, { recursive: true });\n  console.log(`Migration directory created or already exists: ${migrationsDir}`);\n\n  // Create a new migration file\n  console.log('\\n--- Creating a new migration file ---');\n  const { filepath, basename } = await create({\n    dir: migrationsDir,\n    basename: 'initial-setup-db',\n    // Optional: template: path.join(__dirname, 'custom-template.js')\n  });\n  console.log(`Created migration: ${filepath}`);\n\n  // Write some simple content into the created migration file\n  const migrationContent = `\nexport async function migrate(db) {\n  console.log('Running migration: ${basename}');\n  // Simulate a database operation\n  await db.collection('users').insertOne({ name: 'Alice', email: 'alice@example.com' });\n  console.log('Added initial user data.');\n}\n\nexport async function rollback(db) {\n  console.log('Rolling back migration: ${basename}');\n  await db.collection('users').deleteOne({ name: 'Alice' });\n  console.log('Removed initial user data.');\n}\n`;\n  await fs.writeFile(filepath, migrationContent);\n  console.log('Populated migration file with sample content.');\n\n  // Run the migrations\n  console.log('\\n--- Running migrations ---');\n  try {\n    await migrate({\n      url: 'mockdb://localhost:9999/test-db',\n      dir: migrationsDir,\n      adapter: mockAdapter,\n      // esModules: true, // Necessary if your migration files use 'import/export' and you're not in 'type: module'\n      silent: false, // Show detailed logs\n      trace: true // Show error stack traces\n    });\n    console.log('\\nMigrations completed successfully.');\n  } catch (error) {\n    console.error('\\nMigration failed:', error);\n    process.exit(1);\n  }\n}\n\nrunEastProgrammatically().catch(console.error);\n","lang":"typescript","description":"This quickstart demonstrates the programmatic usage of `east` to initialize a migration directory, create a new migration file, populate it with sample migration logic, and then execute the migrations. It includes a minimal mock adapter to illustrate how `east` interacts with a database, emphasizing its adapter-based design."},"warnings":[{"fix":"Ensure your Node.js version meets both `east`'s requirements and those of all database adapters in use. Update Node.js if necessary using a tool like `nvm` or your system's package manager.","message":"east itself requires Node.js >= 10.17.0. However, specific database adapters might have different or stricter Node.js version requirements, which could lead to compatibility issues if not checked. Always consult the documentation for the particular adapter you are using.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"For CLI usage, add the `--es-modules` flag to your commands. For programmatic usage or if your project is ESM-first, ensure `\"type\": \"module\"` is present in your `package.json` and use `.mjs` or `.ts` file extensions as appropriate for migration and config files.","message":"When using `east` with ECMAScript Modules (ESM) for configuration, migration files, or custom adapters, you must either enable the `--es-modules` flag via the CLI or ensure your `package.json` specifies `\"type\": \"module\"` for proper module resolution. Otherwise, you may encounter `SyntaxError` related to `import`/`export` statements.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Install the appropriate database client library for your chosen database (e.g., `npm install mongodb` or `npm install pg`). Your migration files will then interact directly with this client library using the provided database connection object.","message":"east does not provide universal database APIs. Instead, it expects you to use your database's native driver or ORM within migration files. This means you need to install and configure the specific database client (e.g., `mongodb` for MongoDB, `pg` for PostgreSQL) separately and correctly handle its connection from within your migration scripts.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Periodically run `npm audit` or `snyk test` in your project. Refer to the official Snyk report link provided in the `east` README for detailed vulnerability information and recommended fixes, and update dependencies as advised.","message":"The `snyk.io` badge indicates that `east` might have known vulnerabilities or dependencies with vulnerabilities. While actively maintained, it is crucial to regularly check the Snyk report for `east` to ensure supply chain security and address any critical issues promptly.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Install the specific adapter package for your database: `npm install east-adapter-mongodb` (replace `mongodb` with your database of choice). Verify that your `east` configuration (e.g., `east.config.js`) or CLI command correctly specifies the adapter name.","cause":"The required database adapter package (e.g., `east-adapter-mongodb`, `east-adapter-pg`) was not installed, or the specified adapter name in your `east` configuration does not match an installed package.","error":"Error: Cannot find module 'east-adapter-mongodb' (or similar adapter module)"},{"fix":"If using the `east` CLI, add the `--es-modules` flag. If your project is ESM-first, ensure your `package.json` has `\"type\": \"module\"` or use `.mjs` file extensions for your migration and config files. For TypeScript, ensure your `tsconfig.json` `module` option is set appropriately (e.g., `esnext`, `nodenext`).","cause":"You are attempting to use ES Module `import`/`export` syntax in a migration file or configuration without Node.js being configured to treat the file as an ES module. This typically happens when using `.js` files without `\"type\": \"module\"` in `package.json` or without the `--es-modules` CLI flag.","error":"SyntaxError: Cannot use import statement outside a module"},{"fix":"Examine the database-specific error message in the stack trace provided by `east` (enable `--trace` for verbose errors). Debug your migration file (`xxxxxxxxxxxx-my-migration-name.js` or `.ts`) to fix the logic, database interaction, or connection issues. Ensure the target database is accessible and credentials are correct.","cause":"An error occurred during the execution of a specific migration script. This is typically due to issues within the migration logic itself, such as incorrect SQL queries, invalid MongoDB operations, or problems with the database connection from within the migration.","error":"Error: Migration 'xxxxxxxxxxxx-my-migration-name' failed: [Database specific error]"},{"fix":"Increase the timeout by using the `--timeout <ms>` CLI option or by setting the `timeout` property in your programmatic configuration. Investigate the migration script for long-running operations or optimize database queries to run within the default or specified timeout. Additionally, check network connectivity and database server load.","cause":"A migration script took longer than the configured timeout to complete, or the database connection itself timed out while `east` was waiting for an operation to finish.","error":"Error: Timeout of XXXms reached for migration 'YYYYY'"}],"ecosystem":"npm","meta_description":null}