CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-db-migrate

Database migration framework for Node.js applications that enables developers to programmatically manage database schema changes and evolution over time.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

configuration-management.mddocs/

Configuration Management

Configuration system for setting up database connections, environments, and migration settings. db-migrate supports multiple configuration sources including files, objects, environment variables, and runtime parameter modification.

Capabilities

Add Configuration Options

Add custom configuration options with CLI argument support.

/**
 * Add a configuration option with CLI argument support
 * @param description - Description of the configuration option
 * @param args - Array of argument names, first is primary name
 * @param type - Argument type: 'string' or 'boolean'
 * @returns boolean - Success status
 */
addConfiguration(description, args, type): boolean;

Usage Examples:

const dbMigrate = require('db-migrate');
const instance = dbMigrate.getInstance();

// Add string configuration option
instance.addConfiguration(
  'Custom migration directory', 
  ['custom-dir', 'd'], 
  'string'
);

// Add boolean configuration option
instance.addConfiguration(
  'Enable verbose logging',
  ['verbose', 'v'],
  'boolean'
);

// Add configuration with multiple aliases
instance.addConfiguration(
  'Database connection timeout',
  ['timeout', 't', 'connection-timeout'],
  'string'
);

Set Configuration Parameters

Set configuration parameter values at runtime.

/**
 * Set a configuration parameter value
 * @param param - Parameter name
 * @param value - Parameter value
 * @returns value - The set value
 */
setConfigParam(param, value): any;

Usage Examples:

// Set migration directory
instance.setConfigParam('migrations-dir', './db/migrations');

// Set environment
instance.setConfigParam('env', 'production');

// Set database table name
instance.setConfigParam('table', 'schema_migrations');

// Set count for operations
instance.setConfigParam('count', 5);

// Set boolean flags
instance.setConfigParam('dry-run', true);
instance.setConfigParam('verbose', true);

Reset Configuration

Reset argv configuration to new values.

/**
 * Reset argv configuration to specified values
 * @param argv - New argv configuration object
 */
resetConfiguration(argv): void;

Usage Example:

// Reset configuration with new argv
const newArgv = {
  env: 'test',
  'migrations-dir': './test/migrations',
  verbose: true
};
instance.resetConfiguration(newArgv);

This method is also documented in the API reference and allows complete replacement of the current argument configuration.

Add Global Libraries

Add global library references for use in migrations.

/**
 * Add a global library reference accessible in migrations
 * @param library - Library name or path to require
 * @returns boolean - Success status (true if library loaded successfully)
 */
addGlobal(library): boolean;

Usage Examples:

// Add lodash globally
const success = instance.addGlobal('lodash');
if (success) {
  console.log('Lodash is now available globally in migrations');
}

// Add custom utility
instance.addGlobal('./lib/db-utils');

// Add multiple libraries
['moment', 'uuid', 'bcrypt'].forEach(lib => {
  instance.addGlobal(lib);
});

Plugin and Hook Management

Register and manage API hooks for extending db-migrate functionality.

/**
 * Register and initialize API hooks for plugins
 * @param callback - Completion callback (function)
 * @returns Promise
 */
registerAPIHook(callback): Promise;

Usage Examples:

const dbMigrate = require('db-migrate');
const instance = dbMigrate.getInstance(true, {
  plugins: {
    'custom-hook': {
      hooks: ['init:api:addfunction:hook'],
      name: 'CustomPlugin',
      loadPlugin: function() { /* plugin implementation */ }
    }
  }
});

// Register API hooks
await instance.registerAPIHook();

// Plugin can add functions to the API
instance.customFunction(); // Added by plugin

Plugin Structure:

// Example plugin
const customPlugin = {
  name: 'CustomMigrationPlugin',
  hooks: [
    'init:api:addfunction:hook',
    'init:api:accessapi:hook'
  ],
  loadPlugin: function() {
    // Plugin initialization logic
  },
  'init:api:addfunction:hook': function() {
    return ['customMigrationMethod', function() {
      console.log('Custom migration functionality');
    }];
  }
};

// Use plugin
const instance = dbMigrate.getInstance(true, {
  plugins: { 'custom-plugin': customPlugin }
});

Disabling Plugins:

// Disable all plugin loading
const instance = dbMigrate.getInstance(true, {
  noPlugins: true
});

Configuration Sources

File-Based Configuration

Most common approach using database.json or custom config files.

{
  "development": {
    "driver": "mysql",
    "host": "localhost",
    "user": "root",
    "password": "password",
    "database": "myapp_development",
    "multipleStatements": true,
    "migrations-dir": "migrations",
    "seeds-dir": "seeds"
  },
  "test": {
    "driver": "mysql", 
    "host": "localhost",
    "user": "test",
    "password": "test",
    "database": "myapp_test"
  },
  "production": {
    "driver": "mysql",
    "host": "prod-db.example.com",
    "user": "prod_user",
    "password": "secure_password",
    "database": "myapp_production",
    "ssl": true
  }
}

Loading File Configuration:

// Default database.json
const instance = dbMigrate.getInstance();

// Custom config file
const instance = dbMigrate.getInstance(true, {
  config: './config/database.json'
});

// Different environments
const prodInstance = dbMigrate.getInstance(true, {
  config: './config/database.json',
  env: 'production'
});

Object-Based Configuration

Programmatic configuration using JavaScript objects.

const config = {
  development: {
    driver: 'mysql',
    host: process.env.DB_HOST || 'localhost',
    user: process.env.DB_USER || 'root',
    password: process.env.DB_PASSWORD || 'password',
    database: 'myapp_development'
  }
};

const instance = dbMigrate.getInstance(true, { config });

Environment Variable Configuration

Using environment variables for configuration.

{
  "production": {
    "driver": "mysql",
    "host": {"ENV": "DB_HOST"},
    "user": {"ENV": "DB_USER"}, 
    "password": {"ENV": "DB_PASSWORD"},
    "database": {"ENV": "DB_NAME"},
    "port": {"ENV": "DB_PORT"}
  }
}

Environment Variables:

export DB_HOST=prod-db.example.com
export DB_USER=prod_user
export DB_PASSWORD=secure_password
export DB_NAME=myapp_production
export DB_PORT=3306

Database URL Configuration

Using DATABASE_URL for configuration (common in cloud deployments).

DATABASE_URL=mysql://user:password@host:port/database
// Automatically uses DATABASE_URL if available
const instance = dbMigrate.getInstance();

// Or explicitly
const instance = dbMigrate.getInstance(true, {
  config: process.env.DATABASE_URL
});

Configuration Options

Common Options

const options = {
  // Environment selection
  env: 'development',
  
  // Working directory
  cwd: process.cwd(),
  
  // Configuration source
  config: './database.json', // or config object
  
  // Directory paths
  'migrations-dir': 'migrations',
  'vcseeder-dir': 'seeds/vc',
  'staticseeder-dir': 'seeds/static',
  
  // Table names
  table: 'migrations',
  'seeds-table': 'seeds',
  
  // Operation settings
  count: 0, // Number of migrations to run
  'dry-run': false, // Print SQL without executing
  verbose: false, // Verbose output
  'force-exit': false, // Force exit after completion
  
  // Transaction settings
  'non-transactional': false, // Disable transactions
  
  // File generation
  'sql-file': false, // Generate SQL files
  'coffee-file': false, // Generate CoffeeScript files
  'ignore-on-init': false, // Generate conditional files
  
  // Plugin settings
  noPlugins: false, // Disable plugin loading
  plugins: {}, // Custom plugins
  
  // Advanced settings
  staticLoader: false, // Use static command loader
  throwUncatched: false // Prevent error event registration
};

const instance = dbMigrate.getInstance(true, options);

Database-Specific Options

MySQL:

{
  "driver": "mysql",
  "host": "localhost",
  "port": 3306,
  "user": "root",
  "password": "password", 
  "database": "myapp",
  "multipleStatements": true,
  "charset": "utf8mb4",
  "timezone": "UTC",
  "acquireTimeout": 60000,
  "timeout": 60000,
  "reconnect": true,
  "ssl": {
    "ca": "path/to/ca.pem",
    "cert": "path/to/cert.pem", 
    "key": "path/to/key.pem"
  }
}

PostgreSQL:

{
  "driver": "pg",
  "host": "localhost",
  "port": 5432,
  "user": "postgres",
  "password": "password",
  "database": "myapp",
  "schema": "public",
  "ssl": false,
  "max": 10,
  "idleTimeoutMillis": 30000
}

SQLite3:

{
  "driver": "sqlite3", 
  "filename": "./database.db",
  "mode": "OPEN_READWRITE | OPEN_CREATE"
}

MongoDB:

{
  "driver": "mongodb",
  "host": "localhost",
  "port": 27017,
  "database": "myapp",
  "username": "user",
  "password": "password",
  "ssl": false
}

Runtime Configuration

// Get instance with base configuration
const instance = dbMigrate.getInstance(true, {
  env: 'development',
  config: './database.json'
});

// Modify configuration at runtime
instance.setConfigParam('verbose', true);
instance.setConfigParam('migrations-dir', './custom/migrations');
instance.setConfigParam('table', 'custom_migrations');

// Add custom CLI options
instance.addConfiguration('Custom timeout', ['timeout'], 'string');
instance.setConfigParam('timeout', '30000');

// Execute with modified configuration
await instance.up();

Configuration Validation

function validateConfig(config) {
  const required = ['driver', 'database'];
  const missing = required.filter(key => !config[key]);
  
  if (missing.length > 0) {
    throw new Error(`Missing required config: ${missing.join(', ')}`);
  }
  
  // Driver-specific validation
  if (config.driver === 'mysql' || config.driver === 'pg') {
    if (!config.host || !config.user) {
      throw new Error('Host and user are required for MySQL/PostgreSQL');
    }
  }
  
  return true;
}

// Use validated configuration
try {
  validateConfig(config.development);
  const instance = dbMigrate.getInstance(true, { config });
} catch (error) {
  console.error('Configuration error:', error.message);
}

Environment-Specific Patterns

// Multi-environment setup
const environments = ['development', 'test', 'staging', 'production'];

async function runMigrationsAllEnvironments() {
  for (const env of environments) {
    console.log(`Running migrations for ${env}...`);
    const instance = dbMigrate.getInstance(true, { env });
    await instance.up();
  }
}

// Conditional configuration
const config = {
  development: {
    driver: 'sqlite3',
    filename: './dev_database.db'
  },
  production: {
    driver: 'mysql',
    host: process.env.DB_HOST,
    user: process.env.DB_USER,
    password: process.env.DB_PASSWORD,
    database: process.env.DB_NAME,
    ssl: process.env.NODE_ENV === 'production'
  }
};

Types

/**
 * Configuration argument type
 */
type ConfigArgType = 'string' | 'boolean';

/**
 * Configuration parameter value
 */
type ConfigValue = string | number | boolean | object;

/**
 * Database configuration object
 */
interface DatabaseConfig {
  /** Database driver name */
  driver: string;
  /** Database host */
  host?: string;
  /** Database port */
  port?: number;
  /** Database user */
  user?: string;
  /** Database password */
  password?: string;
  /** Database name */
  database: string;
  /** Additional driver-specific options */
  [key: string]: any;
}

/**
 * Migration configuration options
 */
interface MigrationConfig {
  /** Migrations directory path */
  'migrations-dir'?: string;
  /** Migration table name */
  table?: string;
  /** Seeds table name */
  'seeds-table'?: string;
  /** Version controlled seeds directory */
  'vcseeder-dir'?: string;
  /** Static seeds directory */
  'staticseeder-dir'?: string;
  /** Enable verbose output */
  verbose?: boolean;
  /** Dry run mode */
  'dry-run'?: boolean;
  /** Force exit after completion */
  'force-exit'?: boolean;
  /** Disable transactions */
  'non-transactional'?: boolean;
}

/**
 * Complete configuration object
 */
interface Config {
  [environment: string]: DatabaseConfig & MigrationConfig;
}

docs

cli-interface.md

configuration-management.md

data-seeding.md

database-interface.md

database-operations.md

index.md

migration-management.md

tile.json