libsql-migrate

library1.3.5jsnpmunverified

Database migration and seed management tool for libSQL, SQLite, and Turso databases. Current stable version is 1.3.5 with regular updates. Provides a CLI for creating, running, and reverting migrations with lifecycle hooks, configurable migration and seed directories, and multiple environment support (development, production). Differentiates from other SQLite migration tools by being purpose-built for libSQL (the open-source fork of SQLite used by Turso) and supporting remote database connections with authentication tokens.

database

npm install libsql-migrate

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · LIBSQL-MIGRATE

libsql-migrate

databasejavascriptv1.3.5

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

migration file exports

✓ export async function up(client) { ... }

✗ module.exports = { async up(client) { ... } }

Migration files are ESM-only. Using CommonJS exports will cause runtime failures.

configuration file exports

✓ export default { development: { connection: { url: 'file:local.db' } } }

✗ module.exports = { ... }

Configuration file must use ESM default export. CommonJS not supported.

libsql-migrate CLI

✓ npx libsql-migrate up

✗ libsql-migrate up

For locally installed packages, use npx. Global install avoids this.

Global install, init project, create a migration, and apply it to a local SQLite database.

npm install -g libsql-migrate mkdir myproject && cd myproject libsql-migrate init # Edit libsqlrc.js if needed libsql-migrate make create_users # Edit migrations/<timestamp>_create_users.js cat > migrations/$(ls migrations/ | head -1) << 'EOF' export async function up(client) { await client.execute("CREATE TABLE users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT);"); } export async function down(client) { await client.execute("DROP TABLE users;"); } EOF libsql-migrate up

Debug

Known issues

breakingConfiguration file must be ESM (ECMAScript modules). CommonJS module.exports syntax is not supported.

fix

Use export default { ... } instead of module.exports = { ... }

affects: >=1.0.0

gotchaMigration and seed files must export named async functions 'up' and 'down'. Default exports or synchronous functions will fail silently.

fix

Ensure your migration files have export async function up(client) { ... } and export async function down(client) { ... }

affects: >=1.0.0

breakingNode.js version must be >=18.4.0. Older versions will crash with syntax errors.

fix

Update Node.js to version 18.4.0 or later.

affects: >=1.0.0

gotchaWhen using remote Turso databases, the 'authToken' must be provided in the production connection config. Missing token results in authentication errors.

fix

Add authToken: 'your-token' to the connection object in the production environment.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Failed to load config file libsqlrc.js: Unexpected token 'export'

Node.js is running in CommonJS mode or version <18

fix

Add 'type': 'module' to your package.json or use .mjs extension for the config file, and ensure Node >=18.4.0

Error: Cannot find module 'libsql'

@libsql/client is not installed

fix

Run: npm install @libsql/client

Error: libsql-migrate: command not found

CLI not in PATH after local install

fix

Use: npx libsql-migrate <command>

Upgrade

Version history

1.3.5latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/travishorn/libsql-migrate ↗

packagelibsql-migrate ↗

homepagehttps://github.com/travishorn/libsql-migrate#readme ↗