@ork-orm/migrate

TypeScript-native migration engine for Ork ORM with direct Kysely integration.

Overview

@ork-orm/migrate provides programmatic migration capabilities that work directly with Kysely dialect instances, eliminating custom driver abstractions and providing transparent, type-safe database operations.

Key Features

• Direct Kysely Integration: Works with Kysely dialect instances for PostgreSQL, MySQL, SQLite, and D1
• TypeScript-Native: No Rust binaries or external dependencies
• Programmatic API: await ork.migrate.diff() and await ork.migrate.apply()
• Transparent Operations: Uses Kysely's native introspection and DDL builders
• Type Safety: Full TypeScript support with proper type inference
• Comprehensive Schema Diffing:
  • Foreign Key Constraints: Full support for FK creation, modification, and deletion with cascade rules
  • Index Management: Unique indexes, multi-column indexes, and custom named indexes
  • Default Values: Column default value creation, modification, and removal
  • Enum Types: Database enum type creation, value addition, and type management
• Risk Assessment: Automatic detection of destructive changes with detailed warnings
• Golden Snapshot Testing: Deterministic SQL generation with comprehensive test coverage

Installation

npm install @ork-orm/migrate kysely
# or
pnpm add @ork-orm/migrate kysely

Usage

Basic Setup

import { createMigrate } from '@ork-orm/migrate'
import { Kysely, PostgresDialect } from 'kysely'
import { Pool } from 'pg'

// Create your Kysely instance
const db = new Kysely({
  dialect: new PostgresDialect({
    pool: new Pool({ connectionString: process.env.DATABASE_URL! }),
  }),
})

// Create migration engine
const migrate = createMigrate(db, {
  useTransaction: true,
  validateSchema: true,
})

Generate Migration Diff

// Generate diff without applying changes
const diff = await migrate.diff('./prisma/schema.prisma')

console.log('Migration Summary:')
console.log('- Tables to create:', diff.summary.tablesCreated)
console.log('- Tables to modify:', diff.summary.tablesModified)
console.log('- Columns to add:', diff.summary.columnsAdded)
console.log('- Risk level:', diff.impact.riskLevel)

if (diff.hasDestructiveChanges) {
  console.warn('⚠️  This migration contains potentially destructive changes')
}

Apply Migrations

// Apply migrations to database
const result = await migrate.apply('./prisma/schema.prisma')

if (result.success) {
  console.log(`✅ Migration completed successfully`)
  console.log(`   Statements executed: ${result.statementsExecuted}`)
  console.log(`   Execution time: ${result.executionTime}ms`)
} else {
  console.error('❌ Migration failed:')
  result.errors.forEach((error) => {
    console.error(`   ${error.message}`)
    if (error.statement) {
      console.error(`   SQL: ${error.statement}`)
    }
  })
}

Migration History

// Get migration history
const history = await migrate.getHistory()

history.forEach((entry) => {
  console.log(`${entry.id}: ${entry.name}`)
  console.log(`  Applied: ${entry.appliedAt}`)
  console.log(`  Duration: ${entry.executionTime}ms`)
  console.log(`  Success: ${entry.success}`)
})

Schema Validation

// Validate current database against schema
const isValid = await migrate.validate('./prisma/schema.prisma')

if (isValid) {
  console.log('✅ Database schema is up to date')
} else {
  console.log('⚠️  Database schema is out of sync')
}

Supported Kysely Dialects

Works with any Kysely dialect:

• PostgreSQL: kysely with PostgresDialect
• MySQL: kysely with MysqlDialect
• SQLite: kysely with SqliteDialect
• Cloudflare D1: kysely-d1
• Note: Ork targets these providers today; other Kysely dialects may work but are not officially supported yet.

Configuration Options

interface MigrationOptions {
  /** Whether to run migrations in a transaction (default: true) */
  useTransaction?: boolean
  /** Timeout for migration operations in milliseconds (default: 30000) */
  timeout?: number
  /** Whether to validate schema before applying migrations (default: true) */
  validateSchema?: boolean
  /** Custom migration table name (default: '_ork_migrations') */
  migrationTableName?: string
}

Architecture

Direct Kysely Integration

Unlike traditional ORMs that use custom driver abstractions, @ork-orm/migrate works directly with your Kysely instance:

1. Introspection: Uses kysely.introspection.getTables() to get current database state
2. DDL Generation: Uses kysely.schema.createTable(), kysely.schema.alterTable() for SQL generation
3. Execution: Executes through the same Kysely instance with proper transaction handling

No Translation Layers

• No DMMF compatibility layers
• No custom driver abstractions
• No format conversion between systems
• Direct use of Kysely's native types and APIs

Type Safety

Full TypeScript support with:

• Proper type inference for all operations
• Type-safe configuration options
• Strongly typed return values
• Integration with Kysely's type system

Development

# Install dependencies
pnpm install

# Build package
pnpm build

# Run tests
pnpm test

# Development mode
pnpm dev

License

Apache-2.0