Registry / database / knex-migrate-sql-file

knex-migrate-sql-file

library2.0.0jsnpmunverified

A utility library for Knex.js that allows writing SQL migrations using .up.sql and .down.sql files instead of (or in addition to) programmatic schema methods. Version 2.0.0 is the latest stable release, with infrequent updates. It provides functions to load and execute SQL files as Knex raw queries, supporting both CommonJS and ESM modules. Key differentiators include zero-dependency generated migration files, simple integration with existing Knex setups, and type safety with TypeScript definitions.

database

npm install knex-migrate-sql-file

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · KNEX-MIGRATE-SQL-F

knex-migrate-sql-file

databasejavascriptv2.0.0

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.

default

✓ import getMigrators from 'knex-migrate-sql-file'

✗ const getMigrators = require('knex-migrate-sql-file')

Default export is ESM-only; CommonJS require is not supported in v2.0.0

upSQL

✓ import { upSQL } from 'knex-migrate-sql-file'

✗ import upSQL from 'knex-migrate-sql-file'

Named exports must be destructured; default export is getMigrators, not upSQL

downSQL

✓ import { downSQL } from 'knex-migrate-sql-file'

✗ const { downSQL } = require('knex-migrate-sql-file')

Named exports are ESM-only; CommonJS require is not supported in v2.0.0

Shows how to use upSQL and downSQL functions in a Knex migration file to execute SQL files.

// Install: npm install knex-migrate-sql-file import knex from 'knex'; import { upSQL, downSQL } from 'knex-migrate-sql-file'; export async function up(knex: Knex): Promise<void> { await upSQL(knex); } export async function down(knex: Knex): Promise<void> { await downSQL(knex); } // Then create SQL files: // ./migrations/20230101000000_test.up.sql // ./migrations/20230101000000_test.down.sql

Debug

Known issues

breakingVersion 2.0.0 dropped CommonJS support. Using require() will fail.

fix

Use ESM imports (import ... from ...) or migrate to a CommonJS-compatible version (<2.0.0).

affects: >=2.0.0

gotchagetMigrators() expects the SQL files to be in the same directory as the migration file with matching base name.

fix

Ensure .up.sql and .down.sql files are adjacent to the migration file and have the exact same base name (e.g., migration.js -> migration.up.sql).

affects: >=1.0.0

deprecatedThe function name 'getMigrators' is deprecated and may be removed in future versions.

fix

Use 'getMigrators' or switch to upSQL/downSQL functions. Check documentation for alternative.

affects: >=2.0.0

gotchaSQL files are executed using knex.raw(), which may not handle all SQL dialects consistently.

fix

Test SQL syntax against your specific database (PostgreSQL, MySQL, SQLite) before production deployment.

affects: >=1.0.0

gotchaupSQL/downSQL functions do not automatically fetch a knex instance; the 'knex' parameter must be the knex object from the migration function.

fix

Always call upSQL/downSQL with the knex instance passed to migration's up/down functions.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'knex-migrate-sql-file'

Package not installed or not in node_modules.

fix

Run 'npm install knex-migrate-sql-file' in your project directory.

TypeError: (0 , getMigrators) is not a function

Using CommonJS require() instead of ESM import.

fix

Replace 'const getMigrators = require(...)' with 'import getMigrators from ...' and ensure your project uses ESM.

Error: ENOENT: no such file or directory, open '.../migrations/xxx.up.sql'

The corresponding SQL file is missing or in a different location.

fix

Create a .up.sql (and .down.sql) file in the same directory as the migration file with the matching base name.

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/ozum/knex-migrate-sql-file ↗

packageknex-migrate-sql-file ↗

homepagehttps://github.com/ozum/knex-migrate-sql-file#readme ↗