Driver-Agnostic Database Migrations

Common errors

• Ley: No migrations found in './migrations'

  cause The configured 'migrations' directory is missing, empty, or the path is incorrect.
  fix Ensure the `migrations` directory exists in your project root or at the path specified in `ley.config.js` or via CLI options. Use `npx ley new <name>` to create your first migration file.

• TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".ts" for <path>/ley.config.ts

  cause Node.js cannot directly execute TypeScript files without a module loader.
  fix Install `tsm` (`npm install --save-dev tsm`) and update your `package.json` scripts to invoke `ley` using the `tsm` loader, e.g., `"migrate:up": "node --loader tsm ley up"`.

• Error: Unknown driver: 'my-custom-driver-name' or TypeError: driver.connect is not a function

  cause The database driver specified in `ley.config.js` or via CLI is not installed, or the provided driver object does not conform to Ley's driver interface.
  fix Install the required database driver (e.g., `npm install pg`). If using a custom driver, ensure it exports an object with a `connect` method that returns an object conforming to Ley's `LeyClient` interface (e.g., `query`, `release`, `start`, `commit`, `rollback`).

• ReferenceError: exports is not defined in ES module scope

  cause A migration file is using CommonJS `exports.up` syntax in a project or environment configured for Node.js ES Modules (e.g., `"type": "module"` in `package.json`).
  fix Generate new migration files using `npx ley new --esm` and update existing ones to use ESM `export async function up(...) {}` syntax. Alternatively, if your project should be CJS, remove `"type": "module"` from `package.json`.

Warnings

• breaking In `v0.6.0`, the `--client` CLI option and `opts.client` programmatic option were removed. They have been replaced by `--driver` and `opts.driver` respectively, to better reflect the driver-agnostic nature of the tool.
  Fix: Update any CLI usage or programmatic configurations from `--client` to `--driver`, and `opts.client` to `opts.driver`.
• gotcha Ley enforces an append-only, immutable task chain for migrations. Attempting to modify or insert migrations out of their original sequence can lead to errors and inconsistent database states, especially when collaborating or deploying.
  Fix: Always create new migrations for changes. Do not reorder, rename, or modify previously applied migration files. Use tools like `ley new` to ensure correct sequential or timestamped naming.
• gotcha Ley is driver-agnostic and does not bundle any database drivers. You must explicitly install and configure your desired database driver (e.g., `pg` for PostgreSQL, `mysql2` for MySQL) as a dependency in your project.
  Fix: Install the appropriate database driver for your project (e.g., `npm install pg`). Then, configure `ley.config.js` (or `ts`) to provide an instance of this driver or a custom driver object.
• gotcha For TypeScript migrations or configuration files (`ley.config.ts`), `tsm` is the recommended module loader. Using `ts-node` might lead to unexpected behavior or require additional configuration due to how `ley` resolves modules.
  Fix: Install `tsm` (`npm install --save-dev tsm`). Update your `package.json` scripts to run `ley` commands using `node --loader tsm ley <command>`, for example: `"migrate:up": "node --loader tsm ley up"`.
• gotcha When working with Node.js ES Modules, migration files and `ley.config.js` should use `import/export` syntax. If your project has `"type": "module"` in `package.json`, or you generate migrations with `ley new --esm`, ensure your files comply, otherwise, you may encounter CJS/ESM compatibility issues.
  Fix: Generate new migration files with `ley new --esm` to get ESM syntax. If you convert an existing project to ESM, update `ley.config.js` and migration files to use `export default` and `export function` syntax instead of `module.exports` and `exports.up`.

Install

• npm install ley npm
• yarn add ley yarn
• pnpm add ley pnpm

Imports

• run
  wrong:

  const { run } = require('ley')

  correct:

  import { run } from 'ley'

  Primarily for programmatic execution of migrations. ESM-only for direct import; use `require` for CommonJS.
• Ley CLI
  wrong:

  node ley <command>

  correct:

  npx ley <command>

  The primary interface for most users. `npx` ensures the locally installed `ley` executable is used.
• Migration File Exports (ESM)
  wrong:

  exports.up = async function (sql) { /* ... */ }

  correct:

  export async function up(sql: Client) { /* ... */ }

  For migration files generated with `ley new --esm` or when the project is configured for ESM. Requires a module loader like `tsm` for TypeScript.
• Migration File Exports (CJS)
  wrong:

  export async function up(sql: Client) { /* ... */ }

  correct:

  exports.up = async function (sql) { /* ... */ }

  Default for migration files generated without `--esm` or in CommonJS projects. Type definitions (`Client`) are for TypeScript files.

Quickstart

This quickstart demonstrates setting up Ley with a PostgreSQL driver (`pg`) and TypeScript. It includes `package.json` scripts, a `ley.config.ts` file for driver configuration, and an example migration file (`0000_initial.ts`) with `up` and `down` functions using ESM syntax.

{
  "name": "my-ley-project",
  "version": "1.0.0",
  "description": "Ley quickstart example",
  "type": "module", // Optional, but useful for ESM migrations
  "scripts": {
    "migrate:new": "npx ley new",
    "migrate:up": "node --loader tsm ley up",
    "migrate:down": "node --loader tsm ley down"
  },
  "devDependencies": {
    "ley": "^0.8.1",
    "pg": "^8.11.3",
    "tsm": "^2.3.0"
  }
}

// ley.config.ts
import { Pool } from 'pg';
import type { LeyDriver } from 'ley';

const driver: LeyDriver = {
  connect: async () => {
    const pool = new Pool({
      connectionString: process.env.DATABASE_URL ?? 'postgresql://user:password@localhost:5432/mydb',
    });
    const client = await pool.connect();
    return {
      query: client.query.bind(client),
      release: client.release.bind(client),
      start: () => client.query('BEGIN'),
      commit: () => client.query('COMMIT'),
      rollback: () => client.query('ROLLBACK'),
    };
  },
};

export default {
  driver: driver,
  migrations: './migrations',
};

// migrations/0000_initial.ts (generated by 'npx ley new initial --esm' then edited)
import type { PoolClient } from 'pg';

export async function up(sql: PoolClient) {
  await sql.query(`
    CREATE TABLE IF NOT EXISTS users (
      id SERIAL PRIMARY KEY,
      name VARCHAR(255) NOT NULL,
      email VARCHAR(255) UNIQUE NOT NULL
    );
  `);
  await sql.query(`
    INSERT INTO users (name, email) VALUES ('Alice', 'alice@example.com');
  `);
}

export async function down(sql: PoolClient) {
  await sql.query(`DROP TABLE IF EXISTS users;`);
}