ley

library0.1.0jsnpmunverified

Ley is a lightweight, driver-agnostic database migration tool for Node.js, currently at version 0.8.1. It provides both a command-line interface (CLI) and a programmatic API for managing database schema changes. Ley's core differentiators include its agnosticism towards specific database drivers (supporting `pg`, `postgres`, `mysql`, `mysql2`, `better-sqlite3`, and custom drivers without bundling them), its lightweight nature, and its transactional approach to migrations, ensuring atomicity for each change. It emphasizes working directly with your chosen driver's API, avoiding new abstractions, and enforces an append-only, immutable task chain for migrations to maintain database integrity across environments. Releases are consistent, with recent updates focusing on ESM support and improved TypeScript integration.

database devops

npm install ley

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · LEY

ley

databasejavascriptv0.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

run

✓ import { run } from 'ley'

✗ const { run } = require('ley')

Primarily for programmatic execution of migrations. ESM-only for direct import; use `require` for CommonJS.

Ley CLI

✓ npx ley <command>

✗ node ley <command>

The primary interface for most users. `npx` ensures the locally installed `ley` executable is used.

Migration File Exports (ESM)

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

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

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)

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

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

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

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;`); }

ley --version

Debug

Known issues

breakingIn `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`.

affects: >=0.6.0

gotchaLey 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.

affects: >=0.0.0

gotchaLey 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.

affects: >=0.0.0

gotchaFor 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"`.

affects: >=0.8.0

gotchaWhen 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`.

affects: >=0.7.0

Errors

Common errors & fixes

Ley: No migrations found in './migrations'

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

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

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

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`.

Upgrade

Version history

0.1.0latest on npm

Audit

Dependencies

pgoptionalA database driver is required for Ley to connect and interact with a database; pg is a common PostgreSQL client example. Other drivers like `mysql2` or `better-sqlite3` are also common.

tsmoptionalRecommended module loader for executing TypeScript migration files and `ley.config.ts` without needing to compile them first.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/lukeed/ley ↗

packagehttps://www.npmjs.com/package/ley ↗

homepagehttps://ley.xyz ↗