knex-db-manager

0.7.0 verified Sat Apr 25 auth: no javascript

Collection of administrative database operations for knex, supporting PostgreSQL, MySQL, and SQLite3. Version 0.7.0 (latest) provides APIs for creating, dropping, copying, truncating databases, and managing database owners via a privileged superuser connection. Helps with test setup, initializing fresh databases, and truncating between tests. Requires knex 0.x and the appropriate database driver. Differentiates from raw knex by offering high-level admin functions like copyDb and truncateDb.

Common errors

error Error: knex: Required configuration option 'client' is missing. ↓

cause knex config object not passed correctly; missing client property.

fix

Ensure config.knex includes client: 'postgres' (or mysql/sqlite3).

error Error: Cannot find module 'pg-escape' ↓

cause The package requires pg-escape for PostgreSQL, but it is not installed.

fix

Run: npm install pg-escape

error DBManager: superUser and superPassword must be specified ↓

cause dbManager config missing superUser or superPassword fields.

fix

Add superUser and superPassword to dbManager configuration object.

error dbManager.createDb is not a function ↓

cause The module was imported incorrectly; databaseManagerFactory returns an object with methods.

fix

Use: const dbManager = databaseManagerFactory(config); then call dbManager.createDb().

error error: role "dbowneruser" does not exist ↓

cause The db owner user has not been created yet; use createDbOwnerIfNotExist() first.

fix

Call await dbManager.createDbOwnerIfNotExist() before createDb().

Warnings

gotcha DatabaseManager may not close all connections; superuser connection can remain open. Call dbManager.close() to close the knex instance and superuser connection. ↓

fix Add dbManager.close() after all operations to ensure clean exit.

gotcha When using copyDb with large databases, the operation copies on the server side and can cause high disk usage; consider using pg_dump/pg_restore instead. ↓

fix Avoid copyDb for very large databases; use native tools.

breaking The superUser and superPassword fields are required; omitting them results in an error. This was not always enforced in early versions. ↓

fix Always provide dbManager.superUser and dbManager.superPassword.

deprecated The populatePathPattern option is deprecated; use knex seed functionality instead. ↓

fix Remove populatePathPattern and run seeds via knex commands.

gotcha The copyDb method does not work with MySQL; it throws an error if used. ↓

fix Do not use copyDb with MySQL; implement your own copy logic.

gotcha truncateDb may fail if there are foreign key constraints; it disables triggers temporarily but some databases may require CASCADE. ↓

fix Ensure all tables are listed; use ignoreTables for tables with dependencies.

gotcha The collate option is database-specific; using wrong collation can cause errors on createDb. ↓

fix Set collate to an array of collations that the database supports; can be empty array if unsure.

Install

npm install knex-db-manager

yarn add knex-db-manager

pnpm add knex-db-manager

Imports

databaseManagerFactory

wrong

const knexDbManager = require('knex-db-manager')

correct

import { databaseManagerFactory } from 'knex-db-manager'

CJS require is fine; ESM named import also works.

default
wrong
```
const { default: knexDbManager } = require('knex-db-manager')
```
correct
```
import knexDbManager from 'knex-db-manager'
```
Module has a default export that is the factory function itself. CJS users can use require directly.

DatabaseManager

wrong

import { DatabaseManager } from 'knex-db-manager'

correct

import type { DatabaseManager } from 'knex-db-manager'

DatabaseManager is only exported as a type, not a value.

Quickstart

Shows initialization and basic usage: create db owner, create database, truncate tables except migrations.

const { databaseManagerFactory } = require('knex-db-manager');

const config = {
  knex: {
    client: 'postgres',
    connection: {
      host: 'localhost',
      user: 'dbowneruser',
      password: process.env.DB_PASSWORD || '',
      database: 'myapp_dev',
    },
    pool: { min: 0, max: 10 },
    migrations: { directory: './migrations' },
  },
  dbManager: {
    superUser: 'postgres',
    superPassword: process.env.SUPER_PASSWORD || '',
    collate: ['en_US.UTF-8'],
    populatePathPattern: 'data/**/*.js',
  },
};

const dbManager = databaseManagerFactory(config);

dbManager.createDbOwnerIfNotExist()
  .then(() => dbManager.createDb())
  .then(() => dbManager.truncateDb(['migrations']))
  .catch(err => console.error(err));