Registry / database / east
library0.3.8jsnpmunverified

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.

npm install east
INSTALL
IMPORT
SIG · EAST
E
east
databasejavascriptv0.3.8
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

migrate
import { migrate } from 'east';
const east = require('east'); east.migrate(...);
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.
create
import { create } from 'east';
import East from 'east'; East.create(...);
This named export is used programmatically to generate new migration files. Typically, this action is initiated via the `east create` CLI command.
EastConfig
import type { EastConfig } from 'east';
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.

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.

import { migrate, create } from 'east'; import path from 'node:path'; import { fileURLToPath } from 'node:url'; import { promises as fs } from 'node:fs'; const __filename = fileURLToPath(import.meta.url); const __dirname = path.dirname(__filename); const migrationsDir = path.join(__dirname, 'my-app-migrations'); // A minimal mock adapter for demonstration purposes. // In a real application, you would install and use an official adapter // like `east-adapter-mongodb` or `east-adapter-pg`. const mockAdapter = { connect: async (url) => { console.log(`[Mock DB] Attempting connection to ${url}...`); return { client: {}, db: { // Simulate a minimal DB object collection: (name) => ({ // Mock a collection for storing migration names find: () => ({ toArray: async () => [] }), // No executed migrations initially insertOne: async (doc) => { console.log(`[Mock DB] Storing migration record: ${doc.name}`); }, deleteOne: async (query) => { console.log(`[Mock DB] Removing migration record: ${query.name}`); } }) } }; }, disconnect: async () => { console.log('[Mock DB] Disconnecting...'); }, getExecutedMigrationNames: async (db) => { // In a real adapter, this would query a specific collection/table. return db.collection('east_migrations').find().toArray().then(docs => docs.map(d => d.name)); }, markMigrationExecuted: async (db, name) => { await db.collection('east_migrations').insertOne({ name, createdAt: new Date() }); console.log(`[Mock DB] Marked migration '${name}' as executed.`); }, unmarkMigrationExecuted: async (db, name) => { await db.collection('east_migrations').deleteOne({ name }); console.log(`[Mock DB] Unmarked migration '${name}' (rolled back).`); } }; async function runEastProgrammatically() { // Ensure migration directory exists (equivalent to parts of `east init` CLI) await fs.mkdir(migrationsDir, { recursive: true }); console.log(`Migration directory created or already exists: ${migrationsDir}`); // Create a new migration file console.log('\n--- Creating a new migration file ---'); const { filepath, basename } = await create({ dir: migrationsDir, basename: 'initial-setup-db', // Optional: template: path.join(__dirname, 'custom-template.js') }); console.log(`Created migration: ${filepath}`); // Write some simple content into the created migration file const migrationContent = ` export async function migrate(db) { console.log('Running migration: ${basename}'); // Simulate a database operation await db.collection('users').insertOne({ name: 'Alice', email: 'alice@example.com' }); console.log('Added initial user data.'); } export async function rollback(db) { console.log('Rolling back migration: ${basename}'); await db.collection('users').deleteOne({ name: 'Alice' }); console.log('Removed initial user data.'); } `; await fs.writeFile(filepath, migrationContent); console.log('Populated migration file with sample content.'); // Run the migrations console.log('\n--- Running migrations ---'); try { await migrate({ url: 'mockdb://localhost:9999/test-db', dir: migrationsDir, adapter: mockAdapter, // esModules: true, // Necessary if your migration files use 'import/export' and you're not in 'type: module' silent: false, // Show detailed logs trace: true // Show error stack traces }); console.log('\nMigrations completed successfully.'); } catch (error) { console.error('\nMigration failed:', error); process.exit(1); } } runEastProgrammatically().catch(console.error);
east --version
Debug
Known issues
gotchaeast 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.
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.
affects: >=2.0.0
gotchaWhen 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.
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.
affects: >=2.0.0
gotchaeast 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.
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.
affects: >=1.0.0
gotchaThe `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.
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.
affects: *
Errors
Common errors & fixes
Error: Cannot find module 'east-adapter-mongodb' (or similar adapter module)
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.
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.
SyntaxError: Cannot use import statement outside a module
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.
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`).
Error: Migration 'xxxxxxxxxxxx-my-migration-name' failed: [Database specific error]
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.
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.
Error: Timeout of XXXms reached for migration 'YYYYY'
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.
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.
Upgrade
Version history
0.3.8latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
6 hits · last 30 days
node
6
Resources
east — npm install east · libregistry