Registry / database / knex-migration-with-schema

knex-migration-with-schema

library2.0.0jsnpmunverified

A utility library for Knex.js (v2.0.0) that simplifies running database migrations across multiple schemas. While Knex supports per-query schema references via `withSchema()`, its built-in `knex.migrate` API lacks native multi-schema support. This library fills that gap by providing `createSchema`, `executeSchemaMigration`, and `executeSchemaMigrationFromDir` functions. It accepts a Knex instance, schema name, and a dictionary of migration objects or a directory of migration files, executing only pending migrations per schema. Released under MIT, actively maintained on GitHub. Key differentiator: enables programmatic schema-scoped migrations without manual schema tracking or external orchestration.

database

npm install knex-migration-with-schema

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · KNEX-MIGRATION-WIT

knex-migration-with-schema

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.

createSchema

✓ import { createSchema } from 'knex-migration-with-schema'

✗ const createSchema = require('knex-migration-with-schema').createSchema

Default CJS require works as well but ESM import is preferred if using ES modules.

executeSchemaMigration

✓ import { executeSchemaMigration } from 'knex-migration-with-schema'

✗ import executeSchemaMigration from 'knex-migration-with-schema'

This is a named export, not a default export. Do not attempt default import.

executeSchemaMigrationFromDir

✓ import { executeSchemaMigrationFromDir } from 'knex-migration-with-schema'

Also a named export. Available since v1.x. TypeScript types are included.

Creates a new schema, defines a migration with up/down methods, and executes pending migrations against that schema using a Knex instance.

import { createSchema, executeSchemaMigration } from 'knex-migration-with-schema'; import knex from 'knex'; const db = knex({ client: 'pg', connection: process.env.DATABASE_URL ?? 'postgres://user:pass@localhost/db', }); const schemaName = 'tenant_1'; await createSchema({ knex: db, schemaName }); const migrations = { createUsersTable: (schemaName) => ({ async up(knex) { return knex.schema.withSchema(schemaName).createTable('users', (table) => { table.increments('id').primary(); table.text('email').notNullable().unique(); }); }, async down(knex) { return knex.schema.withSchema(schemaName).dropTableIfExists('users'); }, }), }; await executeSchemaMigration({ knex: db, schemaName, migrations }); await db.destroy();

Debug

Known issues

gotchaThe migration definition functions receive schemaName as parameter, but the up/down methods themselves do not receive schemaName implicitly. You must explicitly use the passed schemaName inside the migration object via closure.

fix

Wrap your migration object in a function that takes schemaName and returns { up, down } as shown in the documentation.

affects: >=1.0.0

gotchaThe library does not manage Knex migration table name or schema for the migration tracking table. The default knex_migrations table is created in the public schema unless you configure Knex otherwise.

fix

If you need the migration table in the same schema as the migrations, use Knex's migration config or manually set the schema before calling executeSchemaMigration.

affects: >=1.0.0

gotchaThe executeSchemaMigrationFromDir expects migration files to export a function that takes schemaName and returns a Knex.Migration object. If your files export the object directly, migration will fail or behave unpredictably.

fix

Ensure each migration file has a default export: `export default (schemaName: string): Knex.Migration => ({ up, down })`.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: (0 , knex_migration_with_schema_1.executeSchemaMigration) is not a function

Attempting to use default import or incorrect named import. The library only exposes named exports.

fix

Use `import { executeSchemaMigration } from 'knex-migration-with-schema'` instead of `import executeSchemaMigration from '...'`.

error: relation "knex_migrations" does not exist

The migration tracking table is created automatically by Knex when first migration runs, but it may be created in the default schema (public) instead of the target schema.

fix

Configure Knex migration table explicitly via `knex.migrate.config` or set the search path accordingly. Or ensure the target schema exists before running migrations.

Module not found: Can't resolve 'knex-migration-with-schema'

Package not installed or missing from node_modules.

fix

Run `npm install knex-migration-with-schema` and ensure your bundler resolves node_modules correctly.

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

knexrequiredPeer dependency; requires Knex instance for database operations. Must be installed separately.

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/wgrisa/knex-migration-with-schema ↗

packageknex-migration-with-schema ↗

homepagehttps://github.com/wgrisa/knex-migration-with-schema ↗