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

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Database Operations

Name: tessl/npm-db-migrate
Author: tessl

Database-level operations for creating and dropping databases, useful for environment setup and teardown. These operations work across different database systems including MySQL, PostgreSQL, SQLite3, and MongoDB.

Capabilities

Create Database

Create a new database with the specified name.

/**
 * Create a database with the specified name
 * @param dbname - Name of database to create
 * @param callback - Completion callback (function)
 * @returns Promise
 */
createDatabase(dbname, callback): Promise;

Usage Examples:

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

// Create database
await instance.createDatabase('myapp_development');

// With callback
instance.createDatabase('myapp_test', (err) => {
  if (err) console.error('Failed to create database:', err);
  else console.log('Database created successfully');
});

// Create database for different environments
await instance.createDatabase('myapp_production');

Drop Database

Drop (delete) a database with the specified name.

/**
 * Drop a database with the specified name
 * @param dbname - Name of database to drop
 * @param callback - Completion callback (function)
 * @returns Promise
 */
dropDatabase(dbname, callback): Promise;

Usage Examples:

// Drop database
await instance.dropDatabase('myapp_test');

// With callback
instance.dropDatabase('old_database', (err) => {
  if (err) console.error('Failed to drop database:', err);
  else console.log('Database dropped successfully');
});

// Drop database with error handling
try {
  await instance.dropDatabase('myapp_staging');
  console.log('Staging database removed');
} catch (error) {
  if (error.message.includes('does not exist')) {
    console.log('Database was already removed');
  } else {
    throw error;
  }
}

Database-Specific Behavior

MySQL

Creates database with default character set (usually utf8mb4)
Requires appropriate user privileges (CREATE privilege)
Database names are case-sensitive on Linux, case-insensitive on Windows

Example Configuration:

{
  "dev": {
    "driver": "mysql",
    "host": "localhost",
    "user": "root",
    "password": "password",
    "multipleStatements": true
  }
}

PostgreSQL

Creates database with default encoding (usually UTF8)
Requires CREATEDB privilege or superuser access
Database names are converted to lowercase unless quoted

Example Configuration:

{
  "dev": {
    "driver": "pg",
    "host": "localhost", 
    "user": "postgres",
    "password": "password",
    "port": 5432
  }
}

SQLite3

Creates a new SQLite database file
Path can be relative or absolute
Directory must exist before creating database

Example Configuration:

{
  "dev": {
    "driver": "sqlite3",
    "filename": "./database/myapp.db"
  }
}

MongoDB

Creates a new MongoDB database
Database is created implicitly when first collection is created
Requires appropriate MongoDB user privileges

Example Configuration:

{
  "dev": {
    "driver": "mongodb",
    "host": "localhost",
    "database": "myapp_development",
    "port": 27017
  }
}

CLI Usage

Database operations are also available through the command-line interface:

# Create database
db-migrate db:create myapp_development

# Drop database  
db-migrate db:drop myapp_test

# With specific environment
db-migrate db:create myapp_production --env production

# With config file
db-migrate db:create myapp_staging --config ./config/database.json

Error Handling

Database operations can fail for various reasons:

try {
  await instance.createDatabase('myapp_production');
} catch (error) {
  if (error.message.includes('already exists')) {
    console.log('Database already exists, continuing...');
  } else if (error.message.includes('permission denied')) {
    console.error('Insufficient database privileges');
    throw error;
  } else if (error.message.includes('connection')) {
    console.error('Cannot connect to database server');
    throw error;
  } else {
    throw error;
  }
}

Environment-Based Operations

Database operations respect the current environment configuration:

// Using different configurations for different environments
const devInstance = dbMigrate.getInstance(true, { env: 'development' });
await devInstance.createDatabase('myapp_development');

const testInstance = dbMigrate.getInstance(true, { env: 'test' });  
await testInstance.createDatabase('myapp_test');

const prodInstance = dbMigrate.getInstance(true, { env: 'production' });
await prodInstance.createDatabase('myapp_production');

Best Practices

Development Workflow

// Setup development environment
async function setupDevelopment() {
  const instance = dbMigrate.getInstance(true, { env: 'development' });
  
  try {
    // Create database if it doesn't exist
    await instance.createDatabase('myapp_development');
    console.log('Development database ready');
    
    // Run migrations
    await instance.up();
    console.log('Migrations applied');
    
  } catch (error) {
    if (!error.message.includes('already exists')) {
      throw error;
    }
    console.log('Database already exists, running migrations...');
    await instance.up();
  }
}

Testing Workflow

// Setup and teardown test database
async function setupTestDatabase() {
  const instance = dbMigrate.getInstance(true, { env: 'test' });
  
  // Clean slate for tests
  try {
    await instance.dropDatabase('myapp_test');
  } catch (error) {
    // Ignore if database doesn't exist
  }
  
  await instance.createDatabase('myapp_test');
  await instance.up();
}

async function teardownTestDatabase() {
  const instance = dbMigrate.getInstance(true, { env: 'test' });
  await instance.dropDatabase('myapp_test');
}

Types

/**
 * Database operation callback function signature
 */
type DatabaseCallback = (error?: Error) => void;

/**
 * Database operation options
 */
interface DatabaseOptions {
  /** Target environment */
  env?: string;
  /** Configuration object or file path */
  config?: string | object;
}