@hirehq/migration-utility

HireHQ Migration Utility - A reusable NPM package for database migrations across backend services.

Overview

This package provides a standardized way to handle database migrations and seeds across all HireHQ backend services. It extracts the proven migration logic from the enterprise service into a reusable package.

Features

• ✅ Sequelize Support: Full support for Sequelize ORM
• ✅ Fastify Integration: Seamless integration with Fastify applications
• ✅ Migration Management: Run, rollback, and status checking
• ✅ Seed Management: Database seeding with rollback support
• ✅ CLI Interface: Command-line interface for migration operations
• ✅ TypeScript Support: Full TypeScript definitions
• ✅ Error Handling: Comprehensive error handling and logging
• ✅ Single Operations: Run individual migrations and seeds
• ✅ Batch Operations: Run all pending migrations and seeds
• ✅ Service Examples: Comprehensive examples for all HireHQ services

Installation

npm install @hirehq/migration-utility

Quick Start

Basic Usage

import { MigrationManager, SequelizeAdapter } from '@hirehq/migration-utility';

const adapter = new SequelizeAdapter(sequelize, {
  migrationsPath: './src/database/migrations',
  seedsPath: './src/database/seeds',
});
const migrationManager = new MigrationManager(adapter, {
  logger: console,
});

// Run migrations
await migrationManager.runMigrations();

// Check status
const status = await migrationManager.getMigrationStatus();

Fastify Integration

import { MigrationManager, FastifyAdapter } from '@hirehq/migration-utility';

export default fp(async fastify => {
  const adapter = new FastifyAdapter(fastify, {
    migrationsPath: './src/database/migrations',
    seedsPath: './src/database/seeds',
  });
  const migrationManager = new MigrationManager(adapter, {
    logger: fastify.log,
  });

  // Delegate to package
  fastify.decorate('runMigrations', () => migrationManager.runMigrations());
  fastify.decorate('undoMigrations', () => migrationManager.undoMigrations());
  fastify.decorate('getMigrationStatus', () => migrationManager.getMigrationStatus());
});

CLI Usage

# Run migrations
npx hirehq-migrate up

# Rollback migrations
npx hirehq-migrate down

# Check status
npx hirehq-migrate status

# Run seeds
npx hirehq-migrate seed up

# Rollback seeds
npx hirehq-migrate seed down

Migration File Structure

src/database/migrations/
├── 20250101000001-create-audit-log.ts
├── 20250728000001-create-forms.ts
└── ...

src/database/seeds/
├── 20250730000001-seed-status-metadata-form-statuses.ts
└── ...

Examples

This package includes a comprehensive example for the enterprise service that can be used as a template for all HireHQ services:

📁 Available Examples

• Enterprise Service (examples/enterprise-service-example.ts) - Complete integration example for the enterprise service

🚀 Quick Integration

1. Use the enterprise service example as a template for your service
2. Copy the integration code from the example file into your service
3. Install the package: npm install @hirehq/migration-utility
4. Configure environment variables for your database
5. Create migration and seed files following the naming conventions

📋 Usage Examples

Batch Operations

# Run all migrations
npx hirehq-migrate up

# Rollback all migrations
npx hirehq-migrate down

# Check migration status
npx hirehq-migrate status

# Run all seeds
npx hirehq-migrate seed:up

# Rollback all seeds
npx hirehq-migrate seed:down

# Check seed status
npx hirehq-migrate seed:status

Single Operations

# Run single migration
npx hirehq-migrate up 20250101000001-create-users-table.ts

# Rollback single migration
npx hirehq-migrate down 20250101000001-create-users-table.ts

# Run single seed
npx hirehq-migrate seed:up 20250101000001-seed-admin-user.ts

# Rollback single seed
npx hirehq-migrate seed:down 20250101000001-seed-admin-user.ts

Programmatic Usage

// In your application
await app.runMigration('20250101000001-create-users-table.ts');
await app.undoMigration('20250101000001-create-users-table.ts');
await app.runSeed('20250101000001-seed-admin-user.ts');
await app.undoSeed('20250101000001-seed-admin-user.ts');

For detailed examples and service-specific patterns, see the Examples Documentation.

Migration File Format

import { Sequelize } from 'sequelize';

export async function up(sequelize: Sequelize) {
  await sequelize.getQueryInterface().createTable('users', {
    id: {
      type: DataTypes.UUID,
      defaultValue: DataTypes.UUIDV4,
      primaryKey: true,
    },
    // ... other fields
  });
}

export async function down(sequelize: Sequelize) {
  await sequelize.getQueryInterface().dropTable('users');
}

Configuration

MigrationManager Config

interface MigrationConfig {
  logger?: Logger; // Optional logger for migration operations
}

Adapter Config

interface AdapterConfig {
  migrationsPath: string; // Path to migration files
  seedsPath: string; // Path to seed files
  MigrationModel?: SequelizeModel; // Optional Sequelize model for tracking
}

CLI Config

interface CliConfig {
  migrationsPath: string;
  seedsPath: string;
  tableName?: string; // Optional custom table name
  verbose?: boolean; // Enable verbose logging
  dryRun?: boolean; // Preview changes without executing
  force?: boolean; // Force operations
}

Development

# Install dependencies
npm install

# Build the package
npm run build

# Run tests
npm test

# Lint code
npm run lint

# Format code
npm run format

License

UNLICENSED - Private package for HireHQ internal use only.

Support

For issues and questions, please contact the HireHQ development team.