chore: wip

Author: glennmichael123

docs/.vitepress/components.d.ts

@@ -2,6 +2,7 @@
 // @ts-nocheck
 // Generated by unplugin-vue-components
 // Read more: https://github.com/vuejs/core/pull/3399
+// biome-ignore lint: disable
 export {}
 
 /* prettier-ignore */

docs/.vitepress/config.ts

@@ -65,6 +65,7 @@ const sidebar = [
       { text: 'Relations', link: '/features/relations' },
       { text: 'Transactions', link: '/features/transactions' },
       { text: 'Pagination', link: '/features/pagination' },
+      { text: 'Migrations', link: '/features/migrations' },
       { text: 'CLI', link: '/features/cli' },
     ],
   },

docs/features/migrations.md

@@ -0,0 +1,320 @@
+# Migrations
+
+Generate and execute database migrations directly from your TypeScript models with full type safety and dialect support.
+
+## Overview
+
+The migration system automatically generates SQL DDL statements from your model definitions, supporting incremental migrations and full schema generation. It handles table creation, column additions, foreign keys, indexes, and more across PostgreSQL, MySQL, and SQLite.
+
+## Features
+
+- **Model-driven**: Generate migrations from your TypeScript model definitions
+- **Multi-dialect**: Support for PostgreSQL, MySQL, and SQLite
+- **Incremental**: Smart diff-based migrations that only apply changes
+- **Full schema**: Option to generate complete schema SQL
+- **State tracking**: Maintains migration state for incremental updates
+- **Type safe**: Full TypeScript support with inferred types
+
+## Basic Usage
+
+### Generate and Apply Migration
+
+```ts
+import { generateMigration, executeMigration } from 'bun-query-builder'
+
+// Generate migration from models directory
+const migration = await generateMigration('./models', { 
+  dialect: 'postgres', 
+  apply: true, 
+  full: true 
+})
+
+// Execute the migration
+await executeMigration(migration)
+```
+
+### Migration Options
+
+```ts
+interface MigrateOptions {
+  dialect?: 'postgres' | 'mysql' | 'sqlite'  // Default: 'postgres'
+  state?: string                              // Path to state file
+  apply?: boolean                             // Execute SQL immediately
+  full?: boolean                              // Force full schema generation
+}
+```
+
+## CLI Commands
+
+### migrate
+
+Generate SQL migrations from models:
+
+```bash
+# Basic migration generation
+query-builder migrate ./app/Models
+
+# With specific dialect
+query-builder migrate ./app/Models --dialect mysql
+
+# Apply migration immediately
+query-builder migrate ./app/Models --apply
+
+# Force full schema generation
+query-builder migrate ./app/Models --full
+
+# Custom state file location
+query-builder migrate ./app/Models --state ./migrations/state.json
+```
+
+### Examples
+
+```bash
+# Generate PostgreSQL migration for User models
+query-builder migrate ./app/Models --dialect postgres
+
+# Apply MySQL migration immediately
+query-builder migrate ./app/Models --dialect mysql --apply
+
+# Generate full schema for SQLite
+query-builder migrate ./app/Models --dialect sqlite --full
+```
+
+## Migration Types
+
+### Incremental Migrations
+
+By default, the system generates incremental migrations that only apply changes:
+
+- Creates new tables
+- Adds new columns
+- Adds new foreign keys
+- Adds new indexes
+- Maintains existing data
+
+### Full Schema Migrations
+
+Use the `--full` flag to generate complete schema SQL:
+
+- Drops and recreates all tables
+- Useful for development/testing
+- **Warning**: Destructive operation
+
+## State Management
+
+The migration system maintains state in a JSON file (default: `.qb-migrations.<dialect>.json`) that tracks:
+
+- Current schema plan
+- Migration hash for change detection
+- Last update timestamp
+
+### State File Location
+
+```ts
+// Default location
+const defaultStatePath = join(dir, `.qb-migrations.${dialect}.json`)
+
+// Custom location
+const migration = await generateMigration('./models', {
+  state: './custom/path/state.json'
+})
+```
+
+## Model Inference
+
+Migrations are generated by analyzing your model definitions:
+
+```ts
+// Example model that generates migration
+const models = defineModels({
+  User: {
+    name: 'User',
+    table: 'users',
+    primaryKey: 'id',
+    attributes: {
+      id: { validation: { rule: {} } },
+      name: { validation: { rule: {} } },
+      email: { validation: { rule: {} } },
+      active: { validation: { rule: {} } }
+    }
+  }
+})
+```
+
+### Supported Types
+
+The system automatically infers SQL types from your validation rules:
+
+- `string` → `varchar(255)` / `text`
+- `boolean` → `boolean` / `tinyint(1)`
+- `integer` → `integer`
+- `bigint` → `bigint`
+- `float` → `real`
+- `date` → `date`
+- `datetime` → `timestamp` / `datetime`
+- `json` → `jsonb` / `json` / `text`
+
+## Advanced Features
+
+### Foreign Key Relationships
+
+```ts
+const models = defineModels({
+  Post: {
+    name: 'Post',
+    table: 'posts',
+    attributes: {
+      user_id: { 
+        validation: { rule: {} },
+        references: { table: 'users', column: 'id' }
+      }
+    }
+  }
+})
+```
+
+### Indexes and Constraints
+
+```ts
+const models = defineModels({
+  User: {
+    name: 'User',
+    table: 'users',
+    attributes: {
+      email: { 
+        validation: { rule: {} },
+        unique: true
+      },
+      created_at: { 
+        validation: { rule: {} },
+        index: { name: 'created_at_idx' }
+      }
+    }
+  }
+})
+```
+
+## Error Handling
+
+### Migration Failures
+
+```ts
+try {
+  const migration = await generateMigration('./models', { 
+    dialect: 'postgres', 
+    apply: true 
+  })
+  
+  await executeMigration(migration)
+} catch (err) {
+  console.error('Migration failed:', err)
+  // Handle rollback or retry logic
+}
+```
+
+### Common Issues
+
+- **Dialect mismatch**: Ensure state file dialect matches current dialect
+- **Permission errors**: Check database connection and privileges
+- **Syntax errors**: Verify model definitions and validation rules
+
+## Best Practices
+
+### Development Workflow
+
+1. **Start with full migration**: Use `--full` for initial schema setup
+2. **Use incremental for changes**: Let the system detect and apply only changes
+3. **Version control state files**: Commit migration state files to track schema evolution
+4. **Test migrations**: Always test migrations in development before production
+
+### Production Considerations
+
+- **Backup first**: Always backup before applying migrations
+- **Review SQL**: Check generated SQL before applying
+- **Rollback plan**: Have a strategy for migration failures
+- **State consistency**: Ensure state files are properly managed across environments
+
+## Integration Examples
+
+### With Build Scripts
+
+```json
+{
+  "scripts": {
+    "migrate": "query-builder migrate ./src/models --apply",
+    "migrate:dev": "query-builder migrate ./src/models --dialect postgres --full",
+    "migrate:test": "query-builder migrate ./test/models --dialect sqlite --full"
+  }
+}
+```
+
+### With CI/CD
+
+```yaml
+# GitHub Actions example
+- name: Run migrations
+  run: |
+    query-builder migrate ./src/models --dialect postgres --apply
+```
+
+### With Testing
+
+```ts
+// In test setup
+beforeAll(async () => {
+  const result = await generateMigration('./test/models', { 
+    dialect: 'postgres', 
+    full: true 
+  })
+  
+  if (result.sqlStatements.length > 0) {
+    await executeMigration(result)
+  }
+})
+```
+
+## API Reference
+
+### generateMigration
+
+```ts
+function generateMigration(
+  dir: string, 
+  opts?: MigrateOptions
+): Promise<GenerateMigrationResult>
+```
+
+**Parameters:**
+
+- `dir`: Path to models directory
+- `opts`: Migration options
+
+**Returns:**
+
+- `sql`: Complete SQL string
+- `sqlStatements`: Array of individual SQL statements
+- `hasChanges`: Whether any changes were detected
+- `plan`: Generated migration plan
+
+### executeMigration
+
+```ts
+function executeMigration(
+  migration: GenerateMigrationResult
+): Promise<boolean>
+```
+
+**Parameters:**
+
+- `migration`: Result from generateMigration
+
+**Returns:**
+
+- `boolean`: Success status
+
+## Related
+
+- [Query Builder](./builder.md) - Build type-safe queries
+- [Relations](./relations.md) - Handle model relationships
+- [CLI](./cli.md) - Command-line interface
+- [Configuration](../config.md) - Global settings and options