flint-orm 0.2.0 → 0.4.0

package/API.md

@@ -1,60 +1,85 @@
 # Flint ORM — API Reference
 
-A minimal, SQLite/libSQL-only query builder. Type-safe, immutable, parameterized.
+A type-safe, driver-agnostic SQLite ORM for JavaScript. One schema, any driver.
 
 ## Installation
 
 ```bash
 bun add flint-orm
+# or
+npm install flint-orm
 ```
 
 ## Quick Start
 
 ```ts
-import { flint, table, text, integer, eq } from 'flint-orm';
+import { flint } from 'flint-orm/bun-sqlite';
+import { table, text, integer, date } from 'flint-orm/table';
+import { eq } from 'flint-orm/expressions';
 
 // Define schema
 const users = table('users', {
-  id: text('id').primaryKey(),
-  name: text('name').notNull(),
-  email: text('email').unique(),
-  age: integer('age'),
+  id: text().primaryKey(),
+  name: text().notNull(),
+  email: text().unique(),
+  age: integer(),
+  createdAt: date().defaultNow(),
 });
 
 // Connect
-const db = flint({ url: 'app.db' });
+const db = flint({ url: './app.db' });
 
 // Query
-const user = db.select().from(users).where(eq(users.id, 'u1')).single().execute();
-// { id: "u1", name: "Alice", email: "alice@example.com", age: 30 }
+const user = await db.select().from(users).where(eq(users.id, 'u1')).single().execute();
+// { id: "u1", name: "Alice", email: "alice@example.com", age: 30, createdAt: Date }
+```
+
+---
+
+## Config
+
+Create `flint.config.ts` in your project root:
+
+```ts
+import { defineConfig } from 'flint-orm/config';
+
+export default defineConfig({
+  driver: 'bun-sqlite', // 'bun-sqlite' | 'better-sqlite3' | 'libsql' | 'libsql-web' | 'turso' | 'turso-sync'
+  database: {
+    url: './app.db',
+    authToken: '...', // for libsql/libsql-web/turso-sync only
+  },
+  schema: './src/schema',
+  migrations: './flint',
+});
 ```
 
 ---
 
 ## Schema
 
-### `table(name, columns)`
+### `table(name, columns, indexFn?)`
 
 Define a table. Columns live as direct properties. SQL metadata is under `._`.
 
 ```ts
-import { table, text, integer, boolean } from 'flint-orm';
+import { table, text, integer, boolean, index } from 'flint-orm/table';
 
 const users = table('users', {
-  id: text('id').primaryKey(),
-  name: text('name').notNull(),
-  email: text('email').unique(),
-  active: boolean('active').default(true),
-  age: integer('age'),
+  id: text().primaryKey(),
+  name: text().notNull(),
+  email: text().unique(),
+  active: boolean().default(true),
+  age: integer(),
 });
 ```
 
-### `snakeCase.table(name, columns)`
+### `snakeCase.table(name, columns, indexFn?)`
 
 Auto-converts camelCase keys to snake_case SQL names.
 
 ```ts
-import { snakeCase, text } from 'flint-orm';
+import { snakeCase, text } from 'flint-orm/table';
 
 const users = snakeCase.table('users', {
   id: text().primaryKey(), // SQL: id
@@ -65,21 +90,21 @@ const users = snakeCase.table('users', {
 
 ### Column Types
 
-| Function    | TS Type   | SQLite Storage     | Notes                                   |
-| ----------- | --------- | ------------------ | --------------------------------------- |
-| `text()`    | `string`  | TEXT               |                                         |
-| `integer()` | `number`  | INTEGER            | Supports `.autoIncrement()`             |
-| `boolean()` | `boolean` | INTEGER (0/1)      | Encodes/decodes automatically           |
-| `json<T>()` | `T`       | TEXT (JSON)        | Generic, encodes/decodes automatically  |
-| `real()`    | `number`  | REAL               |                                         |
-| `date()`    | `Date`    | INTEGER (epoch ms) | Supports `.defaultNow()`, `.onUpdate()` |
+| Function    | TS Type   | SQLite Storage     | Notes                                            |
+| ----------- | --------- | ------------------ | ------------------------------------------------ |
+| `text()`    | `string`  | TEXT               |                                                  |
+| `integer()` | `number`  | INTEGER            | Supports `.autoIncrement()`                      |
+| `boolean()` | `boolean` | INTEGER (0/1)      | Encodes/decodes automatically                    |
+| `json<T>()` | `T`       | TEXT (JSON)        | Generic, encodes/decodes automatically           |
+| `real()`    | `number`  | REAL               |                                                  |
+| `date()`    | `Date`    | INTEGER (epoch ms) | Supports `.defaultNow()`, `.onUpdateTimestamp()` |
 
 ### Column Modifiers
 
 Every column supports chaining:
 
 ```ts
-text('name')
+text()
   .primaryKey() // PRIMARY KEY
   .notNull() // NOT NULL
   .unique() // UNIQUE
@@ -91,15 +116,15 @@ text('name')
 **Integer-only:**
 
 ```ts
-integer('id').autoIncrement(); // AUTOINCREMENT
+integer().autoIncrement(); // AUTOINCREMENT
 ```
 
 **Date-only:**
 
 ```ts
-date('created_at')
+date()
   .defaultNow() // DEFAULT (current epoch ms)
-  .onUpdate(); // Always set to now on UPDATE
+  .onUpdateTimestamp(); // Always set to now on UPDATE
 ```
 
 ### `InferRow<T>`
@@ -107,8 +132,10 @@ date('created_at')
 Derives the row type from a table definition.
 
 ```ts
+import type { InferRow } from 'flint-orm/table';
+
 type UserRow = InferRow<typeof users>;
-// { id: string; name: string; email: string | null; active: boolean; age: number | null }
+// { id: string; name: string; email: string | null; active: boolean; age: number | null; createdAt: Date }
 ```
 
 ### `InsertRow<T>`
@@ -116,20 +143,44 @@ type UserRow = InferRow<typeof users>;
 Row type for INSERT. Columns with defaults or autoIncrement are optional.
 
 ```ts
+import type { InsertRow } from 'flint-orm/table';
+
 type UserInsert = InsertRow<typeof users>;
-// { id: string; name: string; email?: string; active?: boolean; age?: number }
+// { id: string; name: string; email?: string; active?: boolean; age?: number; createdAt?: Date }
+```
+
+---
+
+## Indexes
+
+### `index(name).on(columns).unique()`
+
+Define indexes via the table callback. Chainable API.
+
+```ts
+const users = table(
+  'users',
+  {
+    id: text().primaryKey(),
+    email: text(),
+    name: text(),
+  },
+  (t) => [index('idx_users_email').on(t.email).unique(), index('idx_users_name').on(t.name)],
+);
 ```
 
 ---
 
 ## Query Builder
 
+All `execute()` methods return `Promise<T>` — always `await` regardless of driver.
+
 ### `db.select().from(table)`
 
 Start a SELECT query. Two-phase: `.from()` is required before anything else.
 
 ```ts
-db.select().from(users).execute();
+await db.select().from(users).execute();
 // SELECT * FROM users
 ```
 
@@ -138,7 +189,7 @@ db.select().from(users).execute();
 Narrow which columns appear in the result.
 
 ```ts
-db.select().from(users).columns(['id', 'name']).execute();
+await db.select().from(users).columns(['id', 'name']).execute();
 // SELECT id, name FROM users
 // Returns: { id: string; name: string }[]
 ```
@@ -148,7 +199,7 @@ db.select().from(users).columns(['id', 'name']).execute();
 Filter rows.
 
 ```ts
-db.select().from(users).where(eq(users.active, true)).execute();
+await db.select().from(users).where(eq(users.active, true)).execute();
 // SELECT * FROM users WHERE active = 1
 ```
 
@@ -157,7 +208,7 @@ db.select().from(users).where(eq(users.active, true)).execute();
 Return one row or null instead of an array. Adds `LIMIT 1`.
 
 ```ts
-db.select().from(users).where(eq(users.id, 'u1')).single().execute();
+await db.select().from(users).where(eq(users.id, 'u1')).single().execute();
 // SELECT * FROM users WHERE id = ? LIMIT 1
 // Returns: UserRow | null
 ```
@@ -167,7 +218,7 @@ db.select().from(users).where(eq(users.id, 'u1')).single().execute();
 Sort results. Default direction is `"asc"`.
 
 ```ts
-db.select().from(users).orderBy('name', 'desc').execute();
+await db.select().from(users).orderBy('name', 'desc').execute();
 // SELECT * FROM users ORDER BY name DESC
 ```
 
@@ -176,7 +227,7 @@ db.select().from(users).orderBy('name', 'desc').execute();
 Limit the number of results.
 
 ```ts
-db.select().from(users).limit(10).execute();
+await db.select().from(users).limit(10).execute();
 // SELECT * FROM users LIMIT 10
 ```
 
@@ -185,7 +236,7 @@ db.select().from(users).limit(10).execute();
 Skip N rows.
 
 ```ts
-db.select().from(users).limit(10).offset(20).execute();
+await db.select().from(users).limit(10).offset(20).execute();
 // SELECT * FROM users LIMIT 10 OFFSET 20
 ```
 
@@ -194,17 +245,10 @@ db.select().from(users).limit(10).offset(20).execute();
 Return unique rows.
 
 ```ts
-db.select().from(users).columns(['name']).distinct().execute();
+await db.select().from(users).columns(['name']).distinct().execute();
 // SELECT DISTINCT name FROM users
 ```
 
-### Full Example
-
-```ts
-const results = db.select().from(users).columns(['id', 'name']).where(eq(users.active, true)).orderBy('name', 'asc').limit(10).offset(0).execute();
-// Returns: { id: string; name: string }[]
-```
-
 ---
 
 ### `db.insert(table).values(row)`
@@ -213,23 +257,16 @@ Insert one or more rows. Two-phase: `.values()` is required before `.execute()`.
 
 ```ts
 // Single row
-db.insert(users).values({ id: 'u1', name: 'Alice', email: 'alice@example.com' }).execute();
-// INSERT INTO users (id, name, email) VALUES (?, ?, ?)
+await db.insert(users).values({ id: 'u1', name: 'Alice', email: 'alice@example.com' }).execute();
 
-// Multiple rows (bulk insert)
-db.insert(users)
+// Multiple rows
+await db
+  .insert(users)
   .values([
     { id: 'u1', name: 'Alice' },
     { id: 'u2', name: 'Bob' },
   ])
   .execute();
-// INSERT INTO users (id, name) VALUES (?, ?), (?, ?)
-```
-
-Columns with defaults can be omitted:
-
-```ts
-db.insert(users).values({ id: 'u1', name: 'Alice' }).execute();
 ```
 
 ### `.returning()`
@@ -237,12 +274,10 @@ db.insert(users).values({ id: 'u1', name: 'Alice' }).execute();
 Return the inserted row(s) instead of void. Pass an array to narrow which columns are returned.
 
 ```ts
-// Return all columns
-const user = db.insert(users).values({ id: 'u1', name: 'Alice' }).returning().execute();
+const user = await db.insert(users).values({ id: 'u1', name: 'Alice' }).returning().execute();
 // Returns: { id: string; name: string; ... }[]
 
-// Return specific columns
-const user = db.insert(users).values({ id: 'u1', name: 'Alice' }).returning(['id', 'name']).execute();
+const user = await db.insert(users).values({ id: 'u1', name: 'Alice' }).returning(['id', 'name']).execute();
 // Returns: { id: string; name: string }[]
 ```
 
@@ -251,8 +286,7 @@ const user = db.insert(users).values({ id: 'u1', name: 'Alice' }).returning(['id
 Skip the insert if a row with the same primary key already exists.
 
 ```ts
-db.insert(users).values({ id: 'u1', name: 'Alice' }).onConflictDoNothing().execute();
-// INSERT OR IGNORE INTO users ...
+await db.insert(users).values({ id: 'u1', name: 'Alice' }).onConflictDoNothing().execute();
 ```
 
 ### `.onConflictDoUpdate()`
@@ -260,14 +294,14 @@ db.insert(users).values({ id: 'u1', name: 'Alice' }).onConflictDoNothing().execu
 Update specific columns when a row with the same primary key already exists (upsert).
 
 ```ts
-db.insert(users)
+await db
+  .insert(users)
   .values({ id: 'u1', name: 'Alice' })
   .onConflictDoUpdate({
     target: users.id,
     set: { name: 'Alice Updated' },
   })
   .execute();
-// INSERT INTO users ... ON CONFLICT (id) DO UPDATE SET name = excluded.name
 ```
 
 ---
@@ -277,29 +311,22 @@ db.insert(users)
 Update rows. Two-phase: `.set()` is required before `.execute()`.
 
 ```ts
-db.update(users).set({ name: 'Bob' }).where(eq(users.id, 'u1')).execute();
-// UPDATE users SET name = ? WHERE id = ?
+await db.update(users).set({ name: 'Bob' }).where(eq(users.id, 'u1')).execute();
 ```
 
 Multiple `.set()` calls merge:
 
 ```ts
-db.update(users).set({ name: 'Bob' }).set({ email: 'bob@example.com' }).where(eq(users.id, 'u1')).execute();
-// UPDATE users SET name = ?, email = ? WHERE id = ?
+await db.update(users).set({ name: 'Bob' }).set({ email: 'bob@example.com' }).where(eq(users.id, 'u1')).execute();
 ```
 
 ### `.returning()`
 
-Return the updated row(s) instead of void. Pass an array to narrow which columns are returned.
+Return the updated row(s) instead of void.
 
 ```ts
-// Return all columns
-const updated = db.update(users).set({ name: 'Bob' }).where(eq(users.id, 'u1')).returning().execute();
+const updated = await db.update(users).set({ name: 'Bob' }).where(eq(users.id, 'u1')).returning().execute();
 // Returns: { id: string; name: string; ... }[]
-
-// Return specific columns
-const updated = db.update(users).set({ name: 'Bob' }).where(eq(users.id, 'u1')).returning(['id', 'name']).execute();
-// Returns: { id: string; name: string }[]
 ```
 
 ---
@@ -309,22 +336,16 @@ const updated = db.update(users).set({ name: 'Bob' }).where(eq(users.id, 'u1')).
 Delete rows.
 
 ```ts
-db.delete(users).where(eq(users.id, 'u1')).execute();
-// DELETE FROM users WHERE id = ?
+await db.delete(users).where(eq(users.id, 'u1')).execute();
 ```
 
 ### `.returning()`
 
-Return the deleted row(s) instead of void. Pass an array to narrow which columns are returned.
+Return the deleted row(s) instead of void.
 
 ```ts
-// Return all columns
-const deleted = db.delete(users).where(eq(users.id, 'u1')).returning().execute();
+const deleted = await db.delete(users).where(eq(users.id, 'u1')).returning().execute();
 // Returns: { id: string; name: string; ... }[]
-
-// Return specific columns
-const deleted = db.delete(users).where(eq(users.id, 'u1')).returning(['id', 'name']).execute();
-// Returns: { id: string; name: string }[]
 ```
 
 ---
@@ -333,20 +354,20 @@ const deleted = db.delete(users).where(eq(users.id, 'u1')).returning(['id', 'nam
 
 ### `db.leftJoin(parent).on(child, condition?)`
 
-LEFT JOIN. Returns all parent rows, with matching child data or null.
+LEFT JOIN. Returns all parent rows, with matching child data nested under the child table name.
 
 ```ts
 const orders = table('orders', {
-  id: text('id').primaryKey(),
-  userId: text('userId').notNull().references(users.id),
-  total: integer('total').notNull(),
+  id: text().primaryKey(),
+  userId: text().notNull().references(users.id),
+  total: integer().notNull(),
 });
 
 // With explicit condition
-db.leftJoin(orders).on(users, eq(orders.userId, users.id)).execute();
+await db.leftJoin(users).on(orders, eq(orders.userId, users.id)).execute();
 
 // Auto-join from foreign key (if .references() is defined)
-db.leftJoin(orders).on(users).execute();
+await db.leftJoin(users).on(orders).execute();
 ```
 
 ### `db.innerJoin(parent).on(child, condition?)`
@@ -354,7 +375,7 @@ db.leftJoin(orders).on(users).execute();
 INNER JOIN. Returns only rows where both tables match.
 
 ```ts
-db.innerJoin(orders).on(users, eq(orders.userId, users.id)).execute();
+await db.innerJoin(users).on(orders, eq(orders.userId, users.id)).execute();
 ```
 
 ### Join Result Shape
@@ -362,7 +383,6 @@ db.innerJoin(orders).on(users, eq(orders.userId, users.id)).execute();
 Joins return **nested** results, not flat-merged:
 
 ```ts
-// One-to-many: one user with multiple orders
 [
   {
     id: 'u1',
@@ -380,26 +400,36 @@ Joins return **nested** results, not flat-merged:
 Narrow parent columns with `.columns()`:
 
 ```ts
-db.leftJoin(orders).on(users, eq(orders.userId, users.id)).columns(['id', 'name']).execute();
+await db.leftJoin(users).on(orders).columns(['id', 'name']).execute();
 // Returns: { id: string; name: string; orders: OrderRow[] }[]
 ```
 
 ### `.single()` on Joins
 
 ```ts
-db.leftJoin(orders).on(users, eq(orders.userId, users.id)).single().execute();
+await db.leftJoin(users).on(orders).single().execute();
 // Returns: { id: string; name: string; orders: OrderRow[] } | null
 ```
 
+### Multi-Join
+
+Chain multiple joins:
+
+```ts
+await db.leftJoin(users).on(orders).leftJoin(orders).on(orderItems).execute();
+```
+
 ---
 
 ## Conditions
 
-All conditions are imported from `flint-orm`.
+All conditions are imported from `flint-orm/expressions`.
 
 ### Comparison
 
 ```ts
+import { eq, neq, gt, gte, lt, lte } from 'flint-orm/expressions';
+
 eq(column, value); // column = value
 eq(left, right); // left = right (column-to-column)
 neq(column, value); // column != value
@@ -412,12 +442,16 @@ lte(column, value); // column <= value
 ### Range
 
 ```ts
+import { between } from 'flint-orm/expressions';
+
 between(column, low, high); // column BETWEEN low AND high
 ```
 
 ### Null Checks
 
 ```ts
+import { isNull, isNotNull } from 'flint-orm/expressions';
+
 isNull(column); // column IS NULL
 isNotNull(column); // column IS NOT NULL
 ```
@@ -425,6 +459,8 @@ isNotNull(column); // column IS NOT NULL
 ### Array
 
 ```ts
+import { isIn, isNotIn } from 'flint-orm/expressions';
+
 isIn(column, values); // column IN (?, ?, ...)
 isNotIn(column, values); // column NOT IN (?, ?, ...)
 ```
@@ -432,6 +468,8 @@ isNotIn(column, values); // column NOT IN (?, ?, ...)
 ### Pattern Matching
 
 ```ts
+import { like, glob } from 'flint-orm/expressions';
+
 like(column, pattern); // column LIKE ?  (% and _ wildcards, case-insensitive)
 glob(column, pattern); // column GLOB ?  (* and ? wildcards, case-sensitive)
 ```
@@ -439,181 +477,140 @@ glob(column, pattern); // column GLOB ?  (* and ? wildcards, case-sensitive)
 ### Logical
 
 ```ts
+import { and, or } from 'flint-orm/expressions';
+
 and(...conditions); // cond1 AND cond2 AND ...
 or(...conditions); // (cond1 OR cond2 OR ...)
 ```
 
-### Examples
-
-```ts
-import { eq, and, or, gt, isIn, like, between } from "flint-orm";
-
-// Simple equality
-.where(eq(users.name, "Alice"))
-
-// Column-to-column
-.where(eq(orders.userId, users.id))
-
-// Multiple conditions
-.where(and(eq(users.active, true), gt(users.age, 18)))
-
-// OR
-.where(or(eq(users.name, "Alice"), eq(users.name, "Bob")))
-
-// IN
-.where(isIn(users.status, ["active", "pending"]))
-
-// LIKE
-.where(like(users.email, "%@example.com"))
-
-// BETWEEN
-.where(between(users.age, 18, 65))
-```
-
 ---
 
 ## Aggregates
 
-Aggregate functions are methods on the `db` object. They execute immediately and return a value.
-
-### `db.count(table, condition?)`
-
-Count all rows.
+Aggregate functions are methods on the `db` object. They return `Promise<T>`.
 
 ```ts
-db.count(users); // 150
-db.count(users, eq(users.active, true)); // 120
+const total = await db.count(users);
+const active = await db.count(users, eq(users.active, true));
+const totalViews = await db.sum(posts, posts.views);
+const avgAge = await db.avg(users, users.age);
+const minAge = await db.min(users, users.age);
+const maxAge = await db.max(users, users.age);
 ```
 
-### `db.countColumn(table, column, condition?)`
-
-Count non-null values in a column.
-
-```ts
-db.countColumn(users, users.email); // 145 (5 users have no email)
-```
+---
 
-### `db.sum(table, column, condition?)`
+## Batch
 
-Sum of values. Returns `null` if no rows match.
+Run multiple queries atomically in a single transaction.
 
 ```ts
-db.sum(orders, orders.total); // 45000
-db.sum(orders, orders.total, eq(orders.userId, 'u1')); // 1500
+await db.batch([
+  db.insert(orders).values({ id: 'o1', userId: 'u1', total: 100 }),
+  db.update(users).set({ totalOrders: 1 }).where(eq(users.id, 'u1')),
+]);
 ```
 
-### `db.avg(table, column, condition?)`
-
-Average of values. Returns `null` if no rows match.
+---
 
-```ts
-db.avg(orders, orders.total); // 300
-db.avg(orders, orders.total, eq(orders.userId, 'u1')); // 500
-```
+## Raw SQL
 
-### `db.min(table, column, condition?)`
+### `db.$run(sql, ...params)`
 
-Minimum value. Returns `null` if no rows match.
+Execute raw SQL directly against the database.
 
 ```ts
-db.min(orders, orders.total); // 10
-db.min(orders, orders.total, eq(orders.userId, 'u1')); // 50
+await db.$run('CREATE TABLE test (id INTEGER PRIMARY KEY, name TEXT)');
+await db.$run('INSERT INTO test VALUES (?, ?)', 1, 'Alice');
 ```
 
-### `db.max(table, column, condition?)`
+### Tagged Template SQL
 
-Maximum value. Returns `null` if no rows match.
+Build parameterized SQL expressions with automatic placeholder handling.
 
 ```ts
-db.max(orders, orders.total); // 1000
-db.max(orders, orders.total, eq(orders.userId, 'u1')); // 800
-```
-
-### Multiple Aggregates
+import { sql } from 'flint-orm';
 
-Use `Promise.all` when you need multiple aggregates:
+const expr = sql`name = ${'Alice'} AND age > ${18}`;
+// { sql: "name = ? AND age > ?", params: ["Alice", 18] }
 
-```ts
-const [total, revenue, avgOrder] = await Promise.all([db.count(orders), db.sum(orders, orders.total), db.avg(orders, orders.total)]);
+const result = await db.select().from(users).where(expr).execute();
 ```
 
 ---
 
-## Batch
-
-Run multiple queries atomically in a single transaction.
-
-```ts
-import { flint, table, text, eq } from 'flint-orm';
+## Migration System
 
-const db = flint({ url: 'app.db' });
+### CLI
 
-db.batch([db.insert(orders).values({ id: 'o1', userId: 'u1', total: 100 }), db.update(users).set({ totalOrders: 1 }).where(eq(users.id, 'u1'))]);
+```bash
+flint generate --name init_schema   # Generate migration
+flint generate --preview            # Preview SQL without writing
+flint migrate                       # Apply pending migrations
+flint migrate --status              # Show applied vs pending
+flint migrate --dry-run             # Preview without executing
 ```
 
-All queries succeed or all roll back.
-
----
-
-## Raw SQL
-
-Access the underlying `bun:sqlite` client directly for raw queries.
+### Programmatic API
 
 ```ts
-// Simple query
-const users = db.$client.prepare('SELECT * FROM users WHERE id = ?').all('u1');
-
-// With type annotation
-const rows = db.$client.prepare('SELECT count(*) as cnt FROM users').all() as { cnt: number }[];
-```
+import { generate, migrate, getMigrationStatus, serializeSchema, diffSchemas, generateSQL } from 'flint-orm/migration';
 
----
+// Serialize table definitions to JSON
+const state = serializeSchema([users, orders]);
 
-## Tagged Template SQL
+// Diff two schema states
+const operations = diffSchemas(previousState, currentState);
 
-Build parameterized SQL expressions with automatic placeholder handling.
+// Generate SQL from operations
+const sql = generateSQL(operations);
 
-```ts
-import { sql } from 'flint-orm';
+// Generate a migration folder
+const result = await generate([users, orders], './flint', { name: 'init_schema', interactive: true });
 
-const expr = sql`SELECT * FROM users WHERE name = ${'Alice'} AND age > ${18}`;
-// { sql: "SELECT * FROM users WHERE name = ? AND age > ?", params: ["Alice", 18] }
+// Apply pending migrations
+const result = await migrate(executor, { migrationsDir: './flint' });
 
-// Execute with db.$client
-const rows = db.$client.prepare(expr.sql).all(...expr.params);
+// Check migration status
+const status = await getMigrationStatus(executor, './flint');
 ```
 
----
-
-## Escape Hatch
-
-Access the underlying `bun:sqlite` client directly.
+### Migration Operations
 
 ```ts
-db.$client; // Database instance
+import { addTable, dropTable, renameTable, addColumn, dropColumn, renameColumn, createIndex, dropIndex } from 'flint-orm/migration';
 ```
 
+| Operation      | SQL Generated                          |
+| -------------- | -------------------------------------- |
+| `addTable`     | `CREATE TABLE ...`                     |
+| `dropTable`    | `DROP TABLE ...`                       |
+| `renameTable`  | `ALTER TABLE ... RENAME TO ...`        |
+| `addColumn`    | `ALTER TABLE ... ADD COLUMN ...`       |
+| `dropColumn`   | `ALTER TABLE ... DROP COLUMN ...`      |
+| `renameColumn` | `ALTER TABLE ... RENAME COLUMN ... TO` |
+| `createIndex`  | `CREATE [UNIQUE] INDEX ...`            |
+| `dropIndex`    | `DROP INDEX ...`                       |
+
 ---
 
 ## Types
 
-| Type                | Description                                                   |
-| ------------------- | ------------------------------------------------------------- |
-| `TableDef<T>`       | Table definition with hidden `._` metadata                    |
-| `ColumnDef<T, S>`   | Column definition with phantom type `T` and storage class `S` |
-| `InferRow<T>`       | Derives row type from table definition                        |
-| `InsertRow<T>`      | Derives insert type (defaults are optional)                   |
-| `Condition`         | Condition node for WHERE clauses                              |
-| `Executable`        | Anything with a `.toSQL()` method (for `batch()`)             |
-| `ConnectionDetails` | `{ url: string }`                                             |
-| `SQLExpression`     | `{ sql: string; params: unknown[] }`                          |
+| Type              | Description                                                                               |
+| ----------------- | ----------------------------------------------------------------------------------------- |
+| `TableDef<T>`     | Table definition with hidden `._` metadata                                                |
+| `ColumnDef<T, S>` | Column definition with phantom types                                                      |
+| `InferRow<T>`     | Derives row type from table definition                                                    |
+| `InsertRow<T>`    | Derives insert type (defaults are optional)                                               |
+| `Executor`        | Database executor interface (all, get, run, transaction)                                  |
+| `SQLExpression`   | `{ sql: string; params: unknown[] }`                                                      |
+| `Executable`      | Anything with a `.toSQL()` method (for `batch()`)                                         |
+| `Driver`          | `'bun-sqlite' \| 'better-sqlite3' \| 'libsql' \| 'libsql-web' \| 'turso' \| 'turso-sync'` |
 
 ---
 
 ## Error Classes
 
-Prefixed with `Flint` to avoid collisions in consumer codebases.
-
 | Class                  | When                                                              |
 | ---------------------- | ----------------------------------------------------------------- |
 | `FlintValidationError` | Invalid query construction (e.g., no primary key for `.single()`) |