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.
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
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.
fixInstall 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.
fixIf 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.
fixExamine 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.
fixIncrease 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.
Audit
Dependencies
No dependency data recorded yet.