@kysera/migrations 0.4.1 → 0.6.0

package/README.md

@@ -1,41 +1,53 @@
 # @kysera/migrations
 
-> Lightweight, type-safe database migration management for Kysera ORM with dry-run support and flexible rollback capabilities.
+> Lightweight, type-safe database migration management for Kysera ORM with dry-run support, flexible rollback capabilities, and plugin system.
 
 [![npm version](https://img.shields.io/npm/v/@kysera/migrations.svg)](https://www.npmjs.com/package/@kysera/migrations)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue)](https://www.typescriptlang.org/)
 
-## 📦 Package Information
+## Package Information
 
 | Property | Value |
 |----------|-------|
 | **Package** | `@kysera/migrations` |
-| **Version** | `0.3.0` |
-| **Bundle Size** | 3.7 KB (minified) |
-| **Dependencies** | None (peer: kysely) |
-| **Test Coverage** | 24 tests, comprehensive |
+| **Version** | `0.5.1` |
+| **Bundle Size** | ~12 KB (minified) |
+| **Dependencies** | @kysera/core (workspace) |
+| **Peer Dependencies** | kysely >=0.28.8, zod ^4.1.13 |
+| **Test Coverage** | 64 tests, comprehensive |
 | **Supported Databases** | PostgreSQL, MySQL, SQLite |
-| **Type Safety** | ✅ Full TypeScript support |
+| **Type Safety** | Full TypeScript support |
 
-## 🎯 Features
+## Features
 
 ### Core Migration Management
-- ✅ **Simple API** - Intuitive migration creation and execution
-- ✅ **Type-safe** - Full TypeScript support with Kysely integration
-- ✅ **State tracking** - Automatic migration history in database
-- ✅ **Sequential execution** - Migrations run in order
-- ✅ **Dry run mode** - Preview changes before execution
+- **Simple API** - Intuitive migration creation and execution
+- **Type-safe** - Full TypeScript support with Kysely integration
+- **State tracking** - Automatic migration history in database
+- **Sequential execution** - Migrations run in order
+- **Dry run mode** - Preview changes before execution
 
 ### Advanced Features
-- ✅ **Rollback support** - Roll back one or multiple migrations
-- ✅ **Partial migration** - Run up to specific migration
-- ✅ **Status reporting** - View executed and pending migrations
-- ✅ **Error handling** - Graceful failure with detailed logging
-- ✅ **Idempotent setup** - Safe to run multiple times
-- ✅ **Zero dependencies** - Only Kysely as peer dependency
-
-## 📥 Installation
+- **Rollback support** - Roll back one or multiple migrations
+- **Partial migration** - Run up to specific migration
+- **Status reporting** - View executed and pending migrations
+- **Error handling** - Typed errors with `MigrationError` class
+- **Transaction support** - Optional transaction wrapping per migration
+- **Duplicate detection** - Validates unique migration names
+
+### Developer Experience (v0.5.0+)
+- **`defineMigrations()`** - Object-based migration definition
+- **`runMigrations()`** - One-liner to run pending migrations
+- **`rollbackMigrations()`** - One-liner for rollbacks
+- **Migration metadata** - Description, breaking flag, tags, timing
+
+### Plugin System (v0.5.0+)
+- **Plugin hooks** - Before/after migration events
+- **Built-in plugins** - Logging and metrics plugins
+- **Extensible** - Create custom plugins for your needs
+
+## Installation
 
 ```bash
 # pnpm (recommended)
@@ -51,7 +63,7 @@ yarn add @kysera/migrations kysely
 bun add @kysera/migrations kysely
 ```
 
-## 🚀 Quick Start
+## Quick Start
 
 ### Basic Usage
 
@@ -86,7 +98,6 @@ const migrations = [
           col.notNull().references('users.id').onDelete('cascade')
         )
         .addColumn('title', 'varchar(255)', col => col.notNull())
-        .addColumn('content', 'text')
         .execute()
     },
     async (db) => {
@@ -101,1221 +112,576 @@ const runner = createMigrationRunner(db, migrations)
 
 // Run all pending migrations
 await runner.up()
-// ✅ All migrations completed successfully
 
 // Check status
 await runner.status()
-// 📊 Migration Status:
-//   ✅ Executed: 2
-//   ⏳ Pending: 0
 
 // Rollback last migration
 await runner.down(1)
-// ✅ Rollback completed successfully
+```
+
+### Minimalist API (v0.5.0+)
+
+```typescript
+import { Kysely } from 'kysely'
+import { defineMigrations, runMigrations } from '@kysera/migrations'
+
+// Define migrations with object syntax
+const migrations = defineMigrations({
+  '001_create_users': {
+    description: 'Create users table with email and name',
+    up: async (db) => {
+      await db.schema
+        .createTable('users')
+        .addColumn('id', 'serial', col => col.primaryKey())
+        .addColumn('email', 'varchar(255)', col => col.notNull().unique())
+        .execute()
+    },
+    down: async (db) => {
+      await db.schema.dropTable('users').execute()
+    },
+  },
+
+  '002_create_posts': {
+    description: 'Create posts table',
+    breaking: false,
+    tags: ['schema'],
+    up: async (db) => {
+      await db.schema
+        .createTable('posts')
+        .addColumn('id', 'serial', col => col.primaryKey())
+        .addColumn('title', 'varchar(255)', col => col.notNull())
+        .execute()
+    },
+  },
+})
+
+// One-liner to run all migrations
+await runMigrations(db, migrations)
 ```
 
 ### Dry Run Mode
 
 ```typescript
+import { runMigrations } from '@kysera/migrations'
+
 // Preview what would happen without making changes
-const runner = createMigrationRunner(db, migrations, {
-  dryRun: true,
-  logger: console.log
-})
+const result = await runMigrations(db, migrations, { dryRun: true })
 
-await runner.up()
-// 🔍 DRY RUN - No changes will be made
-// ↑ Running 001_create_users...
-// ✓ 001_create_users completed
-// ↑ Running 002_create_posts...
-// ✓ 002_create_posts completed
+console.log('Would execute:', result.executed)
+console.log('Would skip:', result.skipped)
+// No actual changes made to database
 ```
 
-## 📖 Table of Contents
-
-- [Installation](#-installation)
-- [Quick Start](#-quick-start)
-- [Core Concepts](#-core-concepts)
-  - [Migrations](#migrations)
-  - [Migration Runner](#migration-runner)
-  - [State Tracking](#state-tracking)
-- [API Reference](#-api-reference)
-  - [createMigration()](#createmigration)
-  - [createMigrationRunner()](#createmigrationrunner)
-  - [MigrationRunner Methods](#migrationrunner-methods)
-  - [setupMigrations()](#setupmigrations)
-- [Migration Lifecycle](#-migration-lifecycle)
-- [Advanced Usage](#-advanced-usage)
-  - [Partial Migrations](#partial-migrations)
-  - [Custom Logger](#custom-logger)
-  - [Migration Metadata](#migration-metadata)
-  - [Complex Schema Changes](#complex-schema-changes)
-- [Best Practices](#-best-practices)
-- [Multi-Database Support](#-multi-database-support)
-- [Troubleshooting](#-troubleshooting)
-- [Examples](#-examples)
-
-## 💡 Core Concepts
-
-### Migrations
-
-A migration represents a set of database schema changes that can be applied and (optionally) reverted:
+## API Reference
+
+### Types
+
+#### `Migration`
 
 ```typescript
 interface Migration {
-  /** Unique migration name (e.g., '001_create_users') */
   name: string
-
-  /** Migration up function - creates/modifies schema */
   up: (db: Kysely<any>) => Promise<void>
-
-  /** Optional migration down function - reverts changes */
   down?: (db: Kysely<any>) => Promise<void>
 }
 ```
 
-**Key points:**
-- **name**: Must be unique, typically versioned (001_, 002_, etc.)
-- **up**: Required, contains schema changes
-- **down**: Optional, should revert the up changes
-- Migrations run sequentially in the order they appear in the array
+#### `MigrationWithMeta`
 
-### Migration Runner
+```typescript
+interface MigrationWithMeta extends Migration {
+  description?: string      // Shown in logs
+  breaking?: boolean        // Shows warning
+  estimatedDuration?: number // In milliseconds
+  tags?: string[]           // For categorization
+}
+```
 
-The `MigrationRunner` class manages migration execution and state:
+#### `MigrationStatus`
 
 ```typescript
-class MigrationRunner {
-  // Run all pending migrations
-  async up(): Promise<void>
-
-  // Rollback last N migrations
-  async down(steps?: number): Promise<void>
+interface MigrationStatus {
+  executed: string[]
+  pending: string[]
+  total: number
+}
+```
 
-  // Show migration status
-  async status(): Promise<MigrationStatus>
+#### `MigrationResult`
 
-  // Reset all migrations (rollback everything)
-  async reset(): Promise<void>
+```typescript
+interface MigrationResult {
+  executed: string[]   // Successfully executed
+  skipped: string[]    // Already executed or no down()
+  failed: string[]     // Failed migrations
+  duration: number     // Total time in ms
+  dryRun: boolean      // Whether dry run mode
+}
+```
 
-  // Migrate up to specific migration
-  async upTo(targetName: string): Promise<void>
+#### `MigrationRunnerOptions`
 
-  // Get list of executed migrations
-  async getExecutedMigrations(): Promise<string[]>
+```typescript
+interface MigrationRunnerOptions {
+  dryRun?: boolean          // Preview only (default: false)
+  logger?: KyseraLogger     // Logger instance from @kysera/core (default: silentLogger)
+  useTransactions?: boolean // Wrap in transactions (default: false)
+  stopOnError?: boolean     // Stop on first error (default: true)
+  verbose?: boolean         // Show metadata (default: true)
 }
 ```
 
-### State Tracking
-
-Migrations are tracked in a `migrations` table:
+#### `MigrationDefinition`
 
-```sql
-CREATE TABLE migrations (
-  name VARCHAR(255) PRIMARY KEY,
-  executed_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
-);
+```typescript
+interface MigrationDefinition {
+  up: (db: Kysely<any>) => Promise<void>
+  down?: (db: Kysely<any>) => Promise<void>
+  description?: string
+  breaking?: boolean
+  estimatedDuration?: number
+  tags?: string[]
+}
 ```
 
-This table is automatically created when you run migrations and stores which migrations have been executed.
+#### `MigrationDefinitions`
+
+```typescript
+type MigrationDefinitions = Record<string, MigrationDefinition>
+```
 
-## 📚 API Reference
+#### `MigrationRunnerWithPluginsOptions`
 
-### createMigration()
+```typescript
+interface MigrationRunnerWithPluginsOptions extends MigrationRunnerOptions {
+  plugins?: MigrationPlugin[]
+}
+```
 
-Create a migration object with up and optional down functions.
+#### `MigrationErrorCode`
 
 ```typescript
-function createMigration(
-  name: string,
-  up: (db: Kysely<any>) => Promise<void>,
-  down?: (db: Kysely<any>) => Promise<void>
-): Migration
+type MigrationErrorCode = 'MIGRATION_UP_FAILED' | 'MIGRATION_DOWN_FAILED' | 'MIGRATION_VALIDATION_FAILED'
 ```
 
-**Parameters:**
-- `name` - Unique migration identifier (e.g., '001_create_users')
-- `up` - Function that applies the migration
-- `down` - Optional function that reverts the migration
+### Factory Functions
 
-**Returns:** Migration object
+#### `createMigration(name, up, down?)`
+
+Create a simple migration:
 
-**Example:**
 ```typescript
 const migration = createMigration(
   '001_create_users',
-  async (db) => {
-    await db.schema
-      .createTable('users')
-      .addColumn('id', 'serial', col => col.primaryKey())
-      .addColumn('email', 'varchar(255)', col => col.notNull().unique())
-      .execute()
-  },
-  async (db) => {
-    await db.schema.dropTable('users').execute()
-  }
+  async (db) => { /* up */ },
+  async (db) => { /* down */ }
 )
 ```
 
-### createMigrationRunner()
+#### `createMigrationWithMeta(name, options)`
 
-Create a MigrationRunner instance.
+Create a migration with metadata:
 
 ```typescript
-function createMigrationRunner(
-  db: Kysely<any>,
-  migrations: Migration[],
-  options?: MigrationRunnerOptions
-): MigrationRunner
+const migration = createMigrationWithMeta('001_create_users', {
+  description: 'Create users table',
+  breaking: true,
+  tags: ['schema', 'users'],
+  estimatedDuration: 5000,
+  up: async (db) => { /* ... */ },
+  down: async (db) => { /* ... */ },
+})
 ```
 
-**Parameters:**
-- `db` - Kysely database instance
-- `migrations` - Array of migration objects
-- `options` - Optional configuration
-
-**Options:**
-```typescript
-interface MigrationRunnerOptions {
-  /** Enable dry run mode (preview only, no changes) */
-  dryRun?: boolean
-
-  /** Custom logger function (default: console.log) */
-  logger?: (message: string) => void
-}
-```
+#### `createMigrationRunner(db, migrations, options?)`
 
-**Returns:** MigrationRunner instance
+Create a MigrationRunner instance:
 
-**Example:**
 ```typescript
 const runner = createMigrationRunner(db, migrations, {
   dryRun: false,
-  logger: (msg) => console.log(`[MIGRATION] ${msg}`)
+  logger: console.log,
+  useTransactions: true,
 })
 ```
 
-### MigrationRunner Methods
-
-#### up()
+#### `createMigrationRunnerWithPlugins(db, migrations, options?)`
 
-Run all pending migrations sequentially.
+Create a MigrationRunner with plugin support (async factory):
 
 ```typescript
-async up(): Promise<void>
-```
-
-**Behavior:**
-- Creates migrations table if it doesn't exist
-- Gets list of already-executed migrations
-- Runs only migrations that haven't been executed
-- Marks each migration as executed after successful completion
-- Stops on first error (does not mark failed migration as executed)
+const runner = await createMigrationRunnerWithPlugins(db, migrations, {
+  plugins: [createLoggingPlugin(), createMetricsPlugin()],
+  useTransactions: true,
+})
 
-**Example:**
-```typescript
+// Runner is ready with plugins initialized via onInit
 await runner.up()
-// Output:
-// ✓ 001_create_users (already executed)
-// ↑ Running 002_create_posts...
-// ✓ 002_create_posts completed
-// ✅ All migrations completed successfully
 ```
 
-#### down()
+### One-Liner Functions (v0.5.0+)
 
-Rollback the last N migrations.
+#### `defineMigrations(definitions)`
+
+Define migrations using object syntax:
 
 ```typescript
-async down(steps?: number): Promise<void>
+const migrations = defineMigrations({
+  '001_users': {
+    description: 'Create users',
+    up: async (db) => { /* ... */ },
+    down: async (db) => { /* ... */ },
+  },
+})
 ```
 
-**Parameters:**
-- `steps` - Number of migrations to rollback (default: 1)
+#### `runMigrations(db, migrations, options?)`
 
-**Behavior:**
-- Gets list of executed migrations
-- Selects last N migrations to rollback (in reverse order)
-- Calls down() method for each migration
-- Removes migration from executed list after successful rollback
-- Skips migrations without down() method
-- Stops on first error
+Run all pending migrations:
 
-**Example:**
 ```typescript
-// Rollback last migration
-await runner.down(1)
-
-// Rollback last 3 migrations
-await runner.down(3)
+const result = await runMigrations(db, migrations)
+const result = await runMigrations(db, migrations, { dryRun: true })
 ```
 
-#### status()
+#### `rollbackMigrations(db, migrations, steps?, options?)`
 
-Display current migration status.
+Rollback migrations:
 
 ```typescript
-async status(): Promise<MigrationStatus>
+await rollbackMigrations(db, migrations)        // Last 1
+await rollbackMigrations(db, migrations, 3)     // Last 3
+await rollbackMigrations(db, migrations, 1, { dryRun: true })
 ```
 
-**Returns:**
-```typescript
-interface MigrationStatus {
-  /** List of executed migration names */
-  executed: string[]
+#### `getMigrationStatus(db, migrations, options?)`
 
-  /** List of pending migration names */
-  pending: string[]
-}
-```
+Get migration status:
 
-**Example:**
 ```typescript
-const status = await runner.status()
+const status = await getMigrationStatus(db, migrations)
 console.log(`Executed: ${status.executed.length}`)
 console.log(`Pending: ${status.pending.length}`)
-
-// Output:
-// 📊 Migration Status:
-//   ✅ Executed: 2
-//   ⏳ Pending: 1
-//
-// Executed migrations:
-//   ✓ 001_create_users
-//   ✓ 002_create_posts
-//
-// Pending migrations:
-//   - 003_add_indexes
 ```
 
-#### reset()
+### MigrationRunner Methods
+
+#### `up(): Promise<MigrationResult>`
 
-Rollback all migrations (dangerous!).
+Run all pending migrations:
 
 ```typescript
-async reset(): Promise<void>
+const result = await runner.up()
+console.log(`Executed: ${result.executed.length} migrations`)
 ```
 
-**Behavior:**
-- Gets count of executed migrations
-- Calls down() to rollback all migrations
-- Only rolls back migrations that have down() methods
+#### `down(steps?): Promise<MigrationResult>`
+
+Rollback last N migrations:
 
-**Example:**
 ```typescript
-await runner.reset()
-// ⚠️  Resetting 3 migrations...
-// ↓ Rolling back 003_add_indexes...
-// ✓ 003_add_indexes rolled back
-// ↓ Rolling back 002_create_posts...
-// ✓ 002_create_posts rolled back
-// ↓ Rolling back 001_create_users...
-// ✓ 001_create_users rolled back
-// ✅ All migrations reset
+await runner.down(1)   // Rollback last one
+await runner.down(3)   // Rollback last three
 ```
 
-#### upTo()
+#### `status(): Promise<MigrationStatus>`
 
-Run migrations up to (and including) a specific migration.
+Get migration status:
 
 ```typescript
-async upTo(targetName: string): Promise<void>
+const status = await runner.status()
+// Logs status to console and returns object
 ```
 
-**Parameters:**
-- `targetName` - Name of the target migration
+#### `reset(): Promise<MigrationResult>`
 
-**Behavior:**
-- Finds the target migration in the list
-- Runs all migrations up to and including the target
-- Skips already-executed migrations
-- Throws error if target migration not found
+Rollback all migrations:
 
-**Example:**
 ```typescript
-await runner.upTo('002_create_posts')
-// ↑ Running 001_create_users...
-// ✓ 001_create_users completed
-// ↑ Running 002_create_posts...
-// ✓ 002_create_posts completed
-// ✅ Migrated up to 002_create_posts
+await runner.reset()  // Dangerous! Rolls back everything
 ```
 
-### setupMigrations()
+#### `upTo(targetName): Promise<MigrationResult>`
 
-Manually create the migrations tracking table.
+Run migrations up to a specific one:
 
 ```typescript
-async function setupMigrations(db: Kysely<any>): Promise<void>
+await runner.upTo('002_create_posts')
+// Runs 001 and 002, stops before 003
 ```
 
-**Note:** This is called automatically by the runner, but you can call it manually if needed.
+#### `getExecutedMigrations(): Promise<string[]>`
 
-**Example:**
-```typescript
-import { setupMigrations } from '@kysera/migrations'
+Get list of executed migrations:
 
-await setupMigrations(db)
-// Creates migrations table if it doesn't exist
+```typescript
+const executed = await runner.getExecutedMigrations()
 ```
 
-## 🔄 Migration Lifecycle
+#### `markAsExecuted(name): Promise<void>`
 
-### Complete Migration Flow
+Manually mark a migration as executed:
 
-```
-┌─────────────────────────────────────────────────────────┐
-│ 1. Create Migrations                                    │
-│    Define up/down functions                             │
-└─────────────────────────────────────────────────────────┘
-                      ↓
-┌─────────────────────────────────────────────────────────┐
-│ 2. Initialize Runner                                    │
-│    createMigrationRunner(db, migrations, options)       │
-└─────────────────────────────────────────────────────────┘
-                      ↓
-┌─────────────────────────────────────────────────────────┐
-│ 3. Check Status (Optional)                              │
-│    await runner.status()                                │
-│    → Shows executed and pending migrations              │
-└─────────────────────────────────────────────────────────┘
-                      ↓
-┌─────────────────────────────────────────────────────────┐
-│ 4. Run Migrations                                       │
-│    await runner.up()                                    │
-│    → Executes pending migrations sequentially           │
-│    → Marks each as executed after success               │
-└─────────────────────────────────────────────────────────┘
-                      ↓
-┌─────────────────────────────────────────────────────────┐
-│ 5. Rollback (If Needed)                                 │
-│    await runner.down(N)                                 │
-│    → Reverts last N migrations                          │
-│    → Removes from executed list                         │
-└─────────────────────────────────────────────────────────┘
+```typescript
+await runner.markAsExecuted('001_create_users')
 ```
 
-### Migration Execution Order
+#### `markAsRolledBack(name): Promise<void>`
 
-Migrations are executed in **array order**:
+Manually mark a migration as rolled back:
 
 ```typescript
-const migrations = [
-  createMigration('001_first', ...),   // Runs first
-  createMigration('002_second', ...),  // Runs second
-  createMigration('003_third', ...)    // Runs third
-]
+await runner.markAsRolledBack('001_create_users')
 ```
 
-**Important:** Name your migrations with numeric prefixes to ensure proper ordering:
-- ✅ `001_create_users`, `002_create_posts`, `003_add_indexes`
-- ❌ `create_users`, `create_posts` (no guaranteed order)
+### Standalone Functions
 
-### Error Handling
+#### `setupMigrations(db)`
 
-When a migration fails:
-1. Execution stops immediately
-2. Failed migration is **not** marked as executed
-3. Previous successful migrations remain executed
-4. Error is thrown for handling
+Manually create the migrations tracking table:
 
 ```typescript
-try {
-  await runner.up()
-} catch (error) {
-  console.error('Migration failed:', error)
-  // Handle error: notify admins, rollback, etc.
-}
+import { setupMigrations } from '@kysera/migrations'
+
+await setupMigrations(db)
+// Creates migrations table if not exists
 ```
 
-## 🔧 Advanced Usage
+## Plugin System (v0.5.0+)
 
-### Partial Migrations
+### Plugin Interface
 
-Run migrations incrementally:
+Consistent with `@kysera/repository` Plugin interface:
 
 ```typescript
-const runner = createMigrationRunner(db, migrations)
-
-// Run only the first two migrations
-await runner.upTo('002_create_posts')
-
-// Later, run the rest
-await runner.up()
+interface MigrationPlugin {
+  name: string
+  version: string
+  // Called once when runner is initialized (consistent with repository Plugin.onInit)
+  onInit?(runner: MigrationRunner): Promise<void> | void
+  beforeMigration?(migration: Migration, operation: 'up' | 'down'): Promise<void> | void
+  afterMigration?(migration: Migration, operation: 'up' | 'down', duration: number): Promise<void> | void
+  // Unknown error type for consistency with repository Plugin.onError
+  onMigrationError?(migration: Migration, operation: 'up' | 'down', error: unknown): Promise<void> | void
+}
 ```
 
-### Custom Logger
+### Built-in Plugins
 
-Integrate with your logging system:
+#### Logging Plugin
 
 ```typescript
-import { createMigrationRunner } from '@kysera/migrations'
-import { logger } from './logger'
-
-const runner = createMigrationRunner(db, migrations, {
-  logger: (message) => {
-    logger.info('[MIGRATIONS]', message)
-  }
-})
+import { createLoggingPlugin } from '@kysera/migrations'
 
-await runner.up()
-// Logs will be sent to your logging system
+const loggingPlugin = createLoggingPlugin(console.log)
+// or with custom logger
+const loggingPlugin = createLoggingPlugin((msg) => logger.info(msg))
 ```
 
-### Disable Logging
+#### Metrics Plugin
 
 ```typescript
-const runner = createMigrationRunner(db, migrations, {
-  logger: () => {} // No-op logger
-})
+import { createMetricsPlugin } from '@kysera/migrations'
 
-await runner.up() // Silent execution
-```
+const metricsPlugin = createMetricsPlugin()
 
-### Migration Metadata
+// After running migrations
+const metrics = metricsPlugin.getMetrics()
+console.log(metrics.migrations)
+// [{ name: '001_users', operation: 'up', duration: 45, success: true }, ...]
+```
 
-Add metadata to migrations for documentation:
+### Creating Custom Plugins
 
 ```typescript
-interface MigrationWithMeta extends Migration {
-  /** Human-readable description */
-  description?: string
+const notificationPlugin: MigrationPlugin = {
+  name: 'notification-plugin',
+  version: '1.0.0',
 
-  /** Whether this is a breaking change */
-  breaking?: boolean
+  // Called when runner is created via createMigrationRunnerWithPlugins()
+  async onInit(runner) {
+    console.log('Notification plugin initialized')
+  },
 
-  /** Estimated duration in milliseconds */
-  estimatedDuration?: number
-}
+  async beforeMigration(migration, operation) {
+    await slack.send(`Starting ${operation} for ${migration.name}`)
+  },
 
-const migration: MigrationWithMeta = {
-  name: '001_create_users',
-  description: 'Create users table with email and name',
-  breaking: false,
-  estimatedDuration: 500,
-  up: async (db) => { /* ... */ },
-  down: async (db) => { /* ... */ }
+  async afterMigration(migration, operation, duration) {
+    await slack.send(`Completed ${migration.name} in ${duration}ms`)
+  },
+
+  async onMigrationError(migration, operation, error) {
+    // Error is unknown type - handle appropriately
+    const message = error instanceof Error ? error.message : String(error)
+    await pagerduty.alert(`Migration failed: ${message}`)
+  },
 }
 ```
 
-### Complex Schema Changes
+## Error Handling
 
-Handle complex migrations with transactions:
-
-```typescript
-createMigration(
-  '004_complex_refactor',
-  async (db) => {
-    // Use transaction for complex operations
-    await db.transaction().execute(async (trx) => {
-      // 1. Create new table
-      await trx.schema
-        .createTable('new_users')
-        .addColumn('id', 'serial', col => col.primaryKey())
-        .addColumn('email', 'varchar(255)', col => col.notNull())
-        .addColumn('full_name', 'varchar(255)', col => col.notNull())
-        .execute()
+### MigrationError
 
-      // 2. Copy data
-      await trx
-        .insertInto('new_users')
-        .columns(['email', 'full_name'])
-        .from(
-          trx.selectFrom('users')
-            .select(['email', 'name as full_name'])
-        )
-        .execute()
+Extends `DatabaseError` from `@kysera/core` for consistency:
 
-      // 3. Drop old table
-      await trx.schema.dropTable('users').execute()
+```typescript
+import { MigrationError } from '@kysera/migrations'
 
-      // 4. Rename new table
-      await trx.schema.alterTable('new_users').renameTo('users').execute()
-    })
-  },
-  async (db) => {
-    // Revert complex changes
-    await db.transaction().execute(async (trx) => {
-      await trx.schema
-        .alterTable('users')
-        .renameColumn('full_name', 'name')
-        .execute()
-    })
+try {
+  await runner.up()
+} catch (error) {
+  if (error instanceof MigrationError) {
+    console.log('Migration:', error.migrationName)
+    console.log('Operation:', error.operation) // 'up' or 'down'
+    console.log('Code:', error.code) // 'MIGRATION_UP_FAILED' or 'MIGRATION_DOWN_FAILED'
+    console.log('Cause:', error.cause?.message)
+
+    // Serialize for logging
+    console.log(error.toJSON())
+    // { name, message, code, detail, migrationName, operation, cause }
   }
-)
+}
 ```
 
-### Data Migrations
+### BadRequestError
 
-Migrate data along with schema:
+For validation errors (e.g., duplicate migration names):
 
 ```typescript
-createMigration(
-  '005_migrate_user_roles',
-  async (db) => {
-    // 1. Add new column
-    await db.schema
-      .alterTable('users')
-      .addColumn('role', 'varchar(50)', col => col.defaultTo('user'))
-      .execute()
-
-    // 2. Migrate data
-    await db
-      .updateTable('users')
-      .set({ role: 'admin' })
-      .where('email', 'like', '%@admin.com')
-      .execute()
+import { BadRequestError } from '@kysera/migrations'
 
-    // 3. Make column required
-    await db.schema
-      .alterTable('users')
-      .alterColumn('role', col => col.setNotNull())
-      .execute()
-  },
-  async (db) => {
-    await db.schema
-      .alterTable('users')
-      .dropColumn('role')
-      .execute()
+try {
+  createMigrationRunner(db, [
+    createMigration('001_users', ...),
+    createMigration('001_users', ...), // Duplicate!
+  ])
+} catch (error) {
+  if (error instanceof BadRequestError) {
+    console.log(error.message) // "Duplicate migration name: 001_users"
+    console.log(error.code)    // "BAD_REQUEST"
   }
-)
+}
 ```
 
-## ✅ Best Practices
+### NotFoundError
 
-### 1. Always Use Numeric Prefixes
+Uses `NotFoundError` from `@kysera/core`:
 
 ```typescript
-// ✅ Good: Clear ordering
-const migrations = [
-  createMigration('001_create_users', ...),
-  createMigration('002_create_posts', ...),
-  createMigration('003_add_indexes', ...)
-]
+import { NotFoundError } from '@kysera/migrations'
 
-// ❌ Bad: No guaranteed order
-const migrations = [
-  createMigration('create_users', ...),
-  createMigration('create_posts', ...),
-  createMigration('add_indexes', ...)
-]
+try {
+  await runner.upTo('nonexistent_migration')
+} catch (error) {
+  if (error instanceof NotFoundError) {
+    console.log(error.message) // "Migration not found"
+  }
+}
 ```
 
-### 2. Keep Migrations Small and Focused
+## Best Practices
 
-```typescript
-// ✅ Good: One table per migration
-createMigration('001_create_users', async (db) => {
-  await db.schema.createTable('users')...execute()
-})
+### 1. Use Numeric Prefixes
 
-createMigration('002_create_posts', async (db) => {
-  await db.schema.createTable('posts')...execute()
-})
+```typescript
+// Good - clear ordering
+'001_create_users'
+'002_create_posts'
+'003_add_indexes'
 
-// ❌ Bad: Multiple tables in one migration
-createMigration('001_initial_schema', async (db) => {
-  await db.schema.createTable('users')...execute()
-  await db.schema.createTable('posts')...execute()
-  await db.schema.createTable('comments')...execute()
-})
+// Bad - no guaranteed order
+'create_users'
+'create_posts'
 ```
 
-### 3. Always Provide down() Methods
+### 2. Always Provide down() Methods
 
 ```typescript
-// ✅ Good: Reversible migration
 createMigration(
   '001_create_users',
-  async (db) => {
-    await db.schema.createTable('users')...execute()
-  },
-  async (db) => {
-    await db.schema.dropTable('users').execute()
-  }
-)
-
-// ⚠️ Acceptable but not ideal: No rollback
-createMigration(
-  '002_add_column',
-  async (db) => {
-    await db.schema
-      .alterTable('users')
-      .addColumn('status', 'varchar(50)')
-      .execute()
-  }
-  // No down() method - can't be rolled back
+  async (db) => { /* up */ },
+  async (db) => { /* down - always provide this! */ }
 )
 ```
 
-### 4. Test Migrations Before Production
+### 3. Use Metadata for Complex Migrations
 
 ```typescript
-// Test in development
-const runner = createMigrationRunner(devDb, migrations, {
-  logger: console.log
+createMigrationWithMeta('005_big_refactor', {
+  description: 'Refactors user permissions system',
+  breaking: true,  // Will show warning
+  tags: ['breaking', 'permissions'],
+  up: async (db) => { /* ... */ },
 })
-
-// 1. Test up
-await runner.up()
-// Verify schema is correct
-
-// 2. Test down
-await runner.down(1)
-// Verify rollback works
-
-// 3. Test up again
-await runner.up()
-// Ensure idempotency
 ```
 
-### 5. Use Dry Run for Production
+### 4. Test with Dry Run First
 
 ```typescript
-// Preview changes in production
-const dryRunner = createMigrationRunner(db, migrations, {
-  dryRun: true,
-  logger: console.log
-})
-
-await dryRunner.up()
-// Review output, ensure it's safe
+// Preview in production
+await runMigrations(db, migrations, { dryRun: true })
 
 // Then run for real
-const runner = createMigrationRunner(db, migrations)
-await runner.up()
-```
-
-### 6. Organize Migrations in Separate Files
-
-```typescript
-// migrations/001_create_users.ts
-export const migration_001 = createMigration(
-  '001_create_users',
-  async (db) => { /* ... */ },
-  async (db) => { /* ... */ }
-)
-
-// migrations/002_create_posts.ts
-export const migration_002 = createMigration(
-  '002_create_posts',
-  async (db) => { /* ... */ },
-  async (db) => { /* ... */ }
-)
-
-// migrations/index.ts
-import { migration_001 } from './001_create_users'
-import { migration_002 } from './002_create_posts'
-
-export const migrations = [
-  migration_001,
-  migration_002
-]
+await runMigrations(db, migrations)
 ```
 
-### 7. Handle Breaking Changes Carefully
+### 5. Use Transactions for Safety
 
 ```typescript
-// Mark breaking changes
-const migration: MigrationWithMeta = {
-  name: '010_remove_deprecated_columns',
-  description: 'Remove deprecated user columns',
-  breaking: true,  // Alert!
-  up: async (db) => {
-    // Drop columns that apps might still use
-    await db.schema
-      .alterTable('users')
-      .dropColumn('old_column')
-      .execute()
-  },
-  down: async (db) => {
-    // Cannot fully revert - data loss!
-    await db.schema
-      .alterTable('users')
-      .addColumn('old_column', 'text')
-      .execute()
-  }
-}
+const runner = createMigrationRunner(db, migrations, {
+  useTransactions: true,  // Each migration wrapped in transaction
+})
 ```
 
-## 🗃️ Multi-Database Support
-
-### PostgreSQL
+## Migration Script Example
 
 ```typescript
+// scripts/migrate.ts
 import { Kysely, PostgresDialect } from 'kysely'
 import { Pool } from 'pg'
-import { createMigrationRunner, createMigration } from '@kysera/migrations'
+import { runMigrations, rollbackMigrations, getMigrationStatus, defineMigrations } from '@kysera/migrations'
+
+const migrations = defineMigrations({
+  // ... your migrations
+})
 
-const db = new Kysely({
-  dialect: new PostgresDialect({
-    pool: new Pool({
-      host: 'localhost',
-      database: 'mydb',
-      user: 'user',
-      password: 'password'
-    })
-  })
-})
-
-const migrations = [
-  createMigration(
-    '001_create_users',
-    async (db) => {
-      await db.schema
-        .createTable('users')
-        .addColumn('id', 'serial', col => col.primaryKey())
-        .addColumn('email', 'varchar(255)', col => col.notNull().unique())
-        .addColumn('created_at', 'timestamp', col =>
-          col.notNull().defaultTo(db.fn('now'))
-        )
-        .execute()
-
-      // PostgreSQL-specific: Create index
-      await db.schema
-        .createIndex('users_email_idx')
-        .on('users')
-        .column('email')
-        .execute()
-    },
-    async (db) => {
-      await db.schema.dropTable('users').cascade().execute()
-    }
-  )
-]
-
-const runner = createMigrationRunner(db, migrations)
-await runner.up()
-```
-
-### MySQL
-
-```typescript
-import { Kysely, MysqlDialect } from 'kysely'
-import { createPool } from 'mysql2'
-import { createMigrationRunner, createMigration } from '@kysera/migrations'
-
-const db = new Kysely({
-  dialect: new MysqlDialect({
-    pool: createPool({
-      host: 'localhost',
-      database: 'mydb',
-      user: 'user',
-      password: 'password'
-    })
-  })
-})
-
-const migrations = [
-  createMigration(
-    '001_create_users',
-    async (db) => {
-      await db.schema
-        .createTable('users')
-        .addColumn('id', 'integer', col =>
-          col.primaryKey().autoIncrement()
-        )
-        .addColumn('email', 'varchar(255)', col => col.notNull().unique())
-        .addColumn('created_at', 'datetime', col =>
-          col.notNull().defaultTo(db.fn('now'))
-        )
-        .execute()
-    },
-    async (db) => {
-      await db.schema.dropTable('users').execute()
-    }
-  )
-]
-
-const runner = createMigrationRunner(db, migrations)
-await runner.up()
-```
-
-### SQLite
-
-```typescript
-import { Kysely, SqliteDialect } from 'kysely'
-import Database from 'better-sqlite3'
-import { createMigrationRunner, createMigration } from '@kysera/migrations'
-
-const db = new Kysely({
-  dialect: new SqliteDialect({
-    database: new Database('mydb.sqlite')
-  })
-})
-
-const migrations = [
-  createMigration(
-    '001_create_users',
-    async (db) => {
-      await db.schema
-        .createTable('users')
-        .addColumn('id', 'integer', col =>
-          col.primaryKey().autoIncrement()
-        )
-        .addColumn('email', 'text', col => col.notNull().unique())
-        .addColumn('created_at', 'text', col =>
-          col.notNull().defaultTo(db.fn('datetime', ['now']))
-        )
-        .execute()
-    },
-    async (db) => {
-      await db.schema.dropTable('users').execute()
-    }
-  )
-]
-
-const runner = createMigrationRunner(db, migrations)
-await runner.up()
-```
-
-## 🐛 Troubleshooting
-
-### Migration Not Running
-
-**Problem**: Migration appears in pending list but doesn't execute
-
-**Solutions:**
-```typescript
-// 1. Check migration is in the array
-const migrations = [
-  migration_001,
-  migration_002,
-  migration_003  // Make sure it's included!
-]
-
-// 2. Verify migration name is unique
-const migrations = [
-  createMigration('001_users', ...),
-  createMigration('001_users', ...)  // ❌ Duplicate name!
-]
-
-// 3. Check for errors in up() function
-createMigration('001_test', async (db) => {
-  try {
-    await db.schema.createTable('test')...execute()
-  } catch (error) {
-    console.error('Migration failed:', error)
-    throw error
-  }
-})
-```
-
-### Rollback Fails
-
-**Problem**: down() throws error or doesn't work
-
-**Solutions:**
-```typescript
-// 1. Ensure down() method exists
-const migration = createMigration(
-  '001_test',
-  async (db) => { /* up */ },
-  async (db) => { /* down - required for rollback! */ }
-)
-
-// 2. Handle dependent objects (foreign keys, etc.)
-createMigration(
-  '001_create_posts',
-  async (db) => {
-    await db.schema.createTable('posts')
-      .addColumn('user_id', 'integer', col =>
-        col.references('users.id')
-      )
-      .execute()
-  },
-  async (db) => {
-    // Must drop in correct order
-    await db.schema.dropTable('posts').execute()  // ✅ Drop first
-    // DON'T drop users table here if posts references it
-  }
-)
-
-// 3. Use CASCADE for PostgreSQL
-async (db) => {
-  await db.schema.dropTable('users').cascade().execute()
-}
-```
-
-### Migrations Table Not Found
-
-**Problem**: `Error: Table 'migrations' does not exist`
-
-**Solution:**
-```typescript
-// The migrations table is created automatically,
-// but you can create it manually if needed:
-import { setupMigrations } from '@kysera/migrations'
-
-await setupMigrations(db)
-await runner.up()
-```
-
-### Duplicate Migration Names
-
-**Problem**: Same migration runs twice or state is inconsistent
-
-**Solution:**
-```typescript
-// Ensure unique names with consistent prefixes
-const migrations = [
-  createMigration('001_create_users', ...),
-  createMigration('002_create_posts', ...),
-  createMigration('003_add_indexes', ...)
-  // Not: '001_create_users', '001_another_table', ...
-]
-
-// Check for duplicates programmatically
-const names = migrations.map(m => m.name)
-const duplicates = names.filter((n, i) => names.indexOf(n) !== i)
-if (duplicates.length > 0) {
-  throw new Error(`Duplicate migrations: ${duplicates.join(', ')}`)
-}
-```
-
-### Migration Stuck in Pending
-
-**Problem**: Migration marked as executed but database changes not applied
-
-**Solution:**
-```typescript
-// Manually remove from migrations table and re-run
-await db
-  .deleteFrom('migrations')
-  .where('name', '=', 'problematic_migration_name')
-  .execute()
-
-await runner.up()
-```
-
-## 📝 Examples
-
-### Complete Blog Application Migration
-
-```typescript
-import { createMigration } from '@kysera/migrations'
-import { sql } from 'kysely'
-
-export const blogMigrations = [
-  // 001: Create users table
-  createMigration(
-    '001_create_users',
-    async (db) => {
-      await db.schema
-        .createTable('users')
-        .addColumn('id', 'serial', col => col.primaryKey())
-        .addColumn('email', 'varchar(255)', col => col.notNull().unique())
-        .addColumn('username', 'varchar(50)', col => col.notNull().unique())
-        .addColumn('password_hash', 'varchar(255)', col => col.notNull())
-        .addColumn('created_at', 'timestamp', col =>
-          col.notNull().defaultTo(sql`CURRENT_TIMESTAMP`)
-        )
-        .execute()
-
-      await db.schema
-        .createIndex('users_email_idx')
-        .on('users')
-        .column('email')
-        .execute()
-    },
-    async (db) => {
-      await db.schema.dropTable('users').cascade().execute()
-    }
-  ),
-
-  // 002: Create posts table
-  createMigration(
-    '002_create_posts',
-    async (db) => {
-      await db.schema
-        .createTable('posts')
-        .addColumn('id', 'serial', col => col.primaryKey())
-        .addColumn('user_id', 'integer', col =>
-          col.notNull().references('users.id').onDelete('cascade')
-        )
-        .addColumn('title', 'varchar(255)', col => col.notNull())
-        .addColumn('slug', 'varchar(255)', col => col.notNull().unique())
-        .addColumn('content', 'text', col => col.notNull())
-        .addColumn('published', 'boolean', col => col.notNull().defaultTo(false))
-        .addColumn('created_at', 'timestamp', col =>
-          col.notNull().defaultTo(sql`CURRENT_TIMESTAMP`)
-        )
-        .addColumn('updated_at', 'timestamp', col =>
-          col.notNull().defaultTo(sql`CURRENT_TIMESTAMP`)
-        )
-        .execute()
-
-      await db.schema
-        .createIndex('posts_user_id_idx')
-        .on('posts')
-        .column('user_id')
-        .execute()
-
-      await db.schema
-        .createIndex('posts_slug_idx')
-        .on('posts')
-        .column('slug')
-        .execute()
-    },
-    async (db) => {
-      await db.schema.dropTable('posts').execute()
-    }
-  ),
-
-  // 003: Create comments table
-  createMigration(
-    '003_create_comments',
-    async (db) => {
-      await db.schema
-        .createTable('comments')
-        .addColumn('id', 'serial', col => col.primaryKey())
-        .addColumn('post_id', 'integer', col =>
-          col.notNull().references('posts.id').onDelete('cascade')
-        )
-        .addColumn('user_id', 'integer', col =>
-          col.notNull().references('users.id').onDelete('cascade')
-        )
-        .addColumn('content', 'text', col => col.notNull())
-        .addColumn('created_at', 'timestamp', col =>
-          col.notNull().defaultTo(sql`CURRENT_TIMESTAMP`)
-        )
-        .execute()
-
-      await db.schema
-        .createIndex('comments_post_id_idx')
-        .on('comments')
-        .column('post_id')
-        .execute()
-    },
-    async (db) => {
-      await db.schema.dropTable('comments').execute()
-    }
-  ),
-
-  // 004: Add tags
-  createMigration(
-    '004_create_tags',
-    async (db) => {
-      await db.schema
-        .createTable('tags')
-        .addColumn('id', 'serial', col => col.primaryKey())
-        .addColumn('name', 'varchar(50)', col => col.notNull().unique())
-        .addColumn('slug', 'varchar(50)', col => col.notNull().unique())
-        .execute()
-
-      await db.schema
-        .createTable('post_tags')
-        .addColumn('post_id', 'integer', col =>
-          col.notNull().references('posts.id').onDelete('cascade')
-        )
-        .addColumn('tag_id', 'integer', col =>
-          col.notNull().references('tags.id').onDelete('cascade')
-        )
-        .addPrimaryKeyConstraint('post_tags_pk', ['post_id', 'tag_id'])
-        .execute()
-
-      await db.schema
-        .createIndex('post_tags_tag_id_idx')
-        .on('post_tags')
-        .column('tag_id')
-        .execute()
-    },
-    async (db) => {
-      await db.schema.dropTable('post_tags').execute()
-      await db.schema.dropTable('tags').execute()
-    }
-  ),
-
-  // 005: Add full-text search
-  createMigration(
-    '005_add_fulltext_search',
-    async (db) => {
-      // PostgreSQL specific
-      await db.schema
-        .alterTable('posts')
-        .addColumn('search_vector', 'tsvector')
-        .execute()
-
-      await sql`
-        CREATE INDEX posts_search_vector_idx
-        ON posts
-        USING gin(search_vector)
-      `.execute(db)
-
-      await sql`
-        CREATE TRIGGER posts_search_vector_update
-        BEFORE INSERT OR UPDATE ON posts
-        FOR EACH ROW EXECUTE FUNCTION
-        tsvector_update_trigger(
-          search_vector, 'pg_catalog.english', title, content
-        )
-      `.execute(db)
-    },
-    async (db) => {
-      await sql`DROP TRIGGER posts_search_vector_update ON posts`.execute(db)
-      await db.schema
-        .alterTable('posts')
-        .dropColumn('search_vector')
-        .execute()
-    }
-  )
-]
-
-// Usage
-const runner = createMigrationRunner(db, blogMigrations)
-await runner.up()
-```
-
-### Migration Script
-
-```typescript
-// scripts/migrate.ts
-import { Kysely, PostgresDialect } from 'kysely'
-import { Pool } from 'pg'
-import { createMigrationRunner } from '@kysera/migrations'
-import { migrations } from '../migrations'
-
-async function main() {
-  const db = new Kysely({
-    dialect: new PostgresDialect({
-      pool: new Pool({
-        connectionString: process.env.DATABASE_URL
-      })
+async function main() {
+  const db = new Kysely({
+    dialect: new PostgresDialect({
+      pool: new Pool({ connectionString: process.env.DATABASE_URL })
     })
   })
 
   const command = process.argv[2]
-  const runner = createMigrationRunner(db, migrations)
 
   try {
     switch (command) {
       case 'up':
         console.log('Running migrations...')
-        await runner.up()
+        const upResult = await runMigrations(db, migrations)
+        console.log(`Executed: ${upResult.executed.length} migrations`)
         break
 
       case 'down':
         const steps = parseInt(process.argv[3] || '1')
         console.log(`Rolling back ${steps} migration(s)...`)
-        await runner.down(steps)
+        await rollbackMigrations(db, migrations, steps)
         break
 
       case 'status':
-        await runner.status()
+        await getMigrationStatus(db, migrations)
         break
 
-      case 'reset':
-        console.log('⚠️  WARNING: This will rollback ALL migrations!')
-        await runner.reset()
+      case 'dry-run':
+        console.log('Dry run mode...')
+        await runMigrations(db, migrations, { dryRun: true })
         break
 
       default:
-        console.log('Usage: pnpm migrate [up|down|status|reset] [steps]')
-        process.exit(1)
+        console.log('Usage: pnpm migrate [up|down|status|dry-run] [steps]')
     }
-  } catch (error) {
-    console.error('Migration failed:', error)
-    process.exit(1)
   } finally {
     await db.destroy()
   }
@@ -1328,82 +694,113 @@ main()
 // package.json
 {
   "scripts": {
-    "migrate:up": "tsx scripts/migrate.ts up",
+    "migrate": "tsx scripts/migrate.ts up",
     "migrate:down": "tsx scripts/migrate.ts down",
     "migrate:status": "tsx scripts/migrate.ts status",
-    "migrate:reset": "tsx scripts/migrate.ts reset"
+    "migrate:dry-run": "tsx scripts/migrate.ts dry-run"
   }
 }
 ```
 
-## 🔒 Type Safety
+## Multi-Database Support
 
-### Fully Typed Migrations
+### PostgreSQL
 
 ```typescript
-import type { Kysely } from 'kysely'
-import type { Database } from './database'
-
-// Type-safe migration
-const migration = createMigration(
+createMigration(
   '001_create_users',
-  async (db: Kysely<Database>) => {
+  async (db) => {
     await db.schema
       .createTable('users')
       .addColumn('id', 'serial', col => col.primaryKey())
-      .addColumn('email', 'varchar(255)', col => col.notNull())
+      .addColumn('created_at', 'timestamp', col =>
+        col.notNull().defaultTo(db.fn('now'))
+      )
       .execute()
-  },
-  async (db: Kysely<Database>) => {
-    await db.schema.dropTable('users').execute()
   }
 )
+```
 
-// Type-safe data migration
+### MySQL
+
+```typescript
 createMigration(
-  '002_migrate_data',
-  async (db: Kysely<Database>) => {
-    // TypeScript knows about 'users' table
-    const users = await db
-      .selectFrom('users')
-      .selectAll()
+  '001_create_users',
+  async (db) => {
+    await db.schema
+      .createTable('users')
+      .addColumn('id', 'integer', col =>
+        col.primaryKey().autoIncrement()
+      )
+      .addColumn('created_at', 'datetime', col =>
+        col.notNull().defaultTo(db.fn('now'))
+      )
       .execute()
+  }
+)
+```
 
-    // Type-safe operations
-    for (const user of users) {
-      await db
-        .updateTable('users')
-        .set({ email: user.email.toLowerCase() })
-        .where('id', '=', user.id)
-        .execute()
-    }
+### SQLite
+
+```typescript
+createMigration(
+  '001_create_users',
+  async (db) => {
+    await db.schema
+      .createTable('users')
+      .addColumn('id', 'integer', col =>
+        col.primaryKey().autoIncrement()
+      )
+      .addColumn('created_at', 'text', col =>
+        col.notNull().defaultTo(sql`CURRENT_TIMESTAMP`)
+      )
+      .execute()
   }
 )
 ```
 
-## 📄 License
+## Changelog
+
+### v0.5.1
 
-MIT © [Kysera Team](https://github.com/omnitron-dev)
+- **Breaking** `MigrationError` now extends `DatabaseError` from `@kysera/core` with `code` property
+- **Breaking** `onMigrationError` hook now receives `error: unknown` (consistent with repository Plugin)
+- **Breaking** `createMigrationRunnerWithPlugins()` is now async (returns `Promise<MigrationRunnerWithPlugins>`)
+- **Added** `onInit` hook to `MigrationPlugin` interface (consistent with repository Plugin)
+- **Added** `MigrationErrorCode` type export
+- **Added** `MigrationDefinition` and `MigrationDefinitions` type exports
+- **Added** `MigrationRunnerWithPluginsOptions` interface export
+- **Added** `DatabaseError` and `BadRequestError` re-exports from `@kysera/core`
+- **Changed** Validation errors now throw `BadRequestError` instead of generic `Error`
 
-## 🤝 Contributing
+### v0.5.0
 
-Contributions are welcome! Please read our [Contributing Guide](../../CONTRIBUTING.md) for details.
+- **Added** `@kysera/core` integration with typed errors
+- **Added** `MigrationWithMeta` support with description, breaking flag, tags
+- **Added** `defineMigrations()` for object-based syntax
+- **Added** `runMigrations()`, `rollbackMigrations()`, `getMigrationStatus()` one-liners
+- **Added** `MigrationResult` return type for all operations
+- **Added** Plugin system with `MigrationPlugin` interface
+- **Added** Built-in `createLoggingPlugin()` and `createMetricsPlugin()`
+- **Added** `MigrationError` class for better error handling
+- **Added** Duplicate migration name validation
+- **Added** `useTransactions` option for transaction wrapping
+- **Added** `stopOnError` option for error handling control
+- **Fixed** Inconsistent dry run behavior in `reset()` and `upTo()`
+- **Fixed** `MigrationStatus` now includes `total` count
 
-## 📚 Related Packages
+### v0.4.1
 
-- [`@kysera/core`](../core) - Core utilities and error handling
-- [`@kysera/repository`](../repository) - Repository pattern implementation
-- [`@kysera/audit`](../audit) - Audit logging plugin
-- [`@kysera/soft-delete`](../soft-delete) - Soft delete plugin
-- [`@kysera/timestamps`](../timestamps) - Automatic timestamp management
+- Initial release
 
-## 🔗 Links
+## Related Packages
 
-- [Documentation](https://kysera.dev/docs/migrations)
-- [GitHub Repository](https://github.com/omnitron-dev/kysera)
-- [Issue Tracker](https://github.com/omnitron-dev/kysera/issues)
-- [Kysely Documentation](https://kysely.dev)
+- [`@kysera/core`](../kysera-core) - Core utilities and error handling
+- [`@kysera/repository`](../kysera-repository) - Repository pattern implementation
+- [`@kysera/audit`](../kysera-audit) - Audit logging plugin
+- [`@kysera/soft-delete`](../kysera-soft-delete) - Soft delete plugin
+- [`@kysera/timestamps`](../kysera-timestamps) - Automatic timestamp management
 
----
+## License
 
-**Built with ❤️ using TypeScript and Kysely**
+MIT