flint-orm 0.3.0 → 0.4.0

package/API.md

@@ -1,32 +1,57 @@
 # 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',
+});
 ```
 
 ---
@@ -38,14 +63,14 @@ const user = db.select().from(users).where(eq(users.id, 'u1')).single().execute(
 Define a table. Columns live as direct properties. SQL metadata is under `._`.
 
 ```ts
-import { table, text, integer, boolean, index } 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(),
 });
 ```
 
@@ -54,7 +79,7 @@ const users = table('users', {
 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,8 +143,10 @@ 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 }
 ```
 
 ---
@@ -132,26 +161,26 @@ Define indexes via the table callback. Chainable API.
 const users = table(
   'users',
   {
-    id: text('id').primaryKey(),
-    email: text('email'),
-    name: text('name'),
+    id: text().primaryKey(),
+    email: text(),
+    name: text(),
   },
-  (t) => [index('idx_users_email').on(t.email).unique(), index('idx_users_name').on(t.name), index('idx_users_email_name').on(t.email, t.name)],
+  (t) => [index('idx_users_email').on(t.email).unique(), index('idx_users_name').on(t.name)],
 );
 ```
 
-The callback receives the table definition and returns an array of `IndexBuilder` objects. Indexes are attached to the table automatically and serialized for migrations.
-
 ---
 
 ## 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
 ```
 
@@ -160,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 }[]
 ```
@@ -170,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
 ```
 
@@ -179,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
 ```
@@ -189,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
 ```
 
@@ -198,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
 ```
 
@@ -207,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
 ```
 
@@ -216,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)`
@@ -235,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()`
@@ -259,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 }[]
 ```
 
@@ -273,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()`
@@ -282,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
 ```
 
 ---
@@ -299,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 }[]
 ```
 
 ---
@@ -331,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 }[]
 ```
 
 ---
@@ -355,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 nested under `__children`.
+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?)`
@@ -376,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
@@ -384,12 +383,11 @@ 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',
     name: 'Alice',
-    __children: [
+    orders: [
       { id: 'o1', userId: 'u1', total: 100 },
       { id: 'o2', userId: 'u1', total: 200 },
     ],
@@ -402,15 +400,15 @@ 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();
-// Returns: { id: string; name: string; __children: OrderRow[] }[]
+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();
-// Returns: { id: string; name: string; __children: OrderRow[] } | null
+await db.leftJoin(users).on(orders).single().execute();
+// Returns: { id: string; name: string; orders: OrderRow[] } | null
 ```
 
 ### Multi-Join
@@ -418,19 +416,20 @@ db.leftJoin(orders).on(users, eq(orders.userId, users.id)).single().execute();
 Chain multiple joins:
 
 ```ts
-db.leftJoin(orders).on(users).leftJoin(orderItems).on(orders).execute();
-// Returns nested: { ...userFields, __children: [{ ...orderFields, __children: [...items] }] }
+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
@@ -443,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
 ```
@@ -456,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 (?, ?, ...)
 ```
@@ -463,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)
 ```
@@ -470,102 +477,25 @@ 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
-```
-
-### `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?)`
-
-Sum of values. Returns `null` if no rows match.
-
-```ts
-db.sum(orders, orders.total); // 45000
-db.sum(orders, orders.total, eq(orders.userId, 'u1')); // 1500
-```
-
-### `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
-```
-
-### `db.min(table, column, condition?)`
-
-Minimum value. Returns `null` if no rows match.
-
-```ts
-db.min(orders, orders.total); // 10
-db.min(orders, orders.total, eq(orders.userId, 'u1')); // 50
-```
-
-### `db.max(table, column, condition?)`
-
-Maximum value. Returns `null` if no rows match.
-
-```ts
-db.max(orders, orders.total); // 1000
-db.max(orders, orders.total, eq(orders.userId, 'u1')); // 800
-```
-
-### Multiple Aggregates
-
-Use `Promise.all` when you need multiple aggregates:
-
-```ts
-const [total, revenue, avgOrder] = await Promise.all([db.count(orders), db.sum(orders, orders.total), db.avg(orders, orders.total)]);
+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);
 ```
 
 ---
@@ -575,15 +505,12 @@ const [total, revenue, avgOrder] = await Promise.all([db.count(orders), db.sum(o
 Run multiple queries atomically in a single transaction.
 
 ```ts
-import { flint, table, text, eq } from 'flint-orm';
-
-const db = flint({ url: 'app.db' });
-
-db.batch([db.insert(orders).values({ id: 'o1', userId: 'u1', total: 100 }), db.update(users).set({ totalOrders: 1 }).where(eq(users.id, 'u1'))]);
+await db.batch([
+  db.insert(orders).values({ id: 'o1', userId: 'u1', total: 100 }),
+  db.update(users).set({ totalOrders: 1 }).where(eq(users.id, 'u1')),
+]);
 ```
 
-All queries succeed or all roll back.
-
 ---
 
 ## Raw SQL
@@ -593,76 +520,35 @@ All queries succeed or all roll back.
 Execute raw SQL directly against the database.
 
 ```ts
-db.$run('CREATE TABLE test (id INTEGER PRIMARY KEY, name TEXT)');
-db.$run('INSERT INTO test VALUES (?, ?)', 1, 'Alice');
+await db.$run('CREATE TABLE test (id INTEGER PRIMARY KEY, name TEXT)');
+await db.$run('INSERT INTO test VALUES (?, ?)', 1, 'Alice');
 ```
 
-### `db.$client`
-
-Direct access to the underlying `bun:sqlite` client.
-
-```ts
-const rows = db.$client.prepare('SELECT * FROM users WHERE id = ?').all('u1');
-```
-
----
-
-## Tagged Template SQL
+### Tagged Template SQL
 
 Build parameterized SQL expressions with automatic placeholder handling.
 
 ```ts
 import { sql } from 'flint-orm';
 
-const expr = sql`SELECT * FROM users WHERE name = ${'Alice'} AND age > ${18}`;
-// { sql: "SELECT * FROM users WHERE name = ? AND age > ?", params: ["Alice", 18] }
+const expr = sql`name = ${'Alice'} AND age > ${18}`;
+// { sql: "name = ? AND age > ?", params: ["Alice", 18] }
 
-// Use with db.$client
-const rows = db.$client.prepare(expr.sql).all(...expr.params);
+const result = await db.select().from(users).where(expr).execute();
 ```
 
 ---
 
 ## Migration System
 
-### `flint generate` (CLI)
-
-Generate a migration from schema changes.
-
-```bash
-# Generate migration
-flint generate --name init_schema
-
-# Preview SQL without writing files
-flint generate --name init_schema --preview
-```
-
-### `flint migrate` (CLI)
-
-Apply pending migrations to the database.
+### CLI
 
 ```bash
-# Apply all pending migrations
-flint migrate
-
-# Show which migrations are pending/applied
-flint migrate --status
-```
-
-### Config
-
-Create `flint.config.ts` in your project root:
-
-```ts
-import { defineConfig } from 'flint-orm/config';
-
-export default defineConfig({
-  schema: './src/schema', // folder or file with table() definitions
-  migrations: './flint', // where migration folders are stored
-  database: {
-    url: './app.db', // SQLite database path
-  },
-});
+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
 ```
 
 ### Programmatic API
@@ -680,19 +566,17 @@ const operations = diffSchemas(previousState, currentState);
 const sql = generateSQL(operations);
 
 // Generate a migration folder
-const result = generate([users, orders], './flint', 'init_schema');
+const result = await generate([users, orders], './flint', { name: 'init_schema', interactive: true });
 
 // Apply pending migrations
-const result = migrate({ url: './app.db' }, './flint');
+const result = await migrate(executor, { migrationsDir: './flint' });
 
 // Check migration status
-const status = getMigrationStatus(client, './flint');
+const status = await getMigrationStatus(executor, './flint');
 ```
 
 ### Migration Operations
 
-Named, pre-vetted operations:
-
 ```ts
 import { addTable, dropTable, renameTable, addColumn, dropColumn, renameColumn, createIndex, dropIndex } from 'flint-orm/migration';
 ```
@@ -708,74 +592,25 @@ import { addTable, dropTable, renameTable, addColumn, dropColumn, renameColumn,
 | `createIndex`  | `CREATE [UNIQUE] INDEX ...`            |
 | `dropIndex`    | `DROP INDEX ...`                       |
 
-### Migration File Shape
-
-```ts
-import { defineMigration } from 'flint-orm/migration';
-import { addTable, addColumn } from 'flint-orm/migration';
-
-export default defineMigration({
-  name: 'init_schema',
-  operations: [
-    addTable({ name: 'users', columns: [...], indexes: [...] }),
-    addColumn('users', { name: 'email', sqlType: 'text', ... }),
-  ],
-});
-```
-
-### Tracking
-
-Applied migrations are recorded in `__flint_migrations` (per-database). The table is created on first `migrate()` call — never with `IF NOT EXISTS`.
-
-### FK Ordering
-
-Tables are topologically sorted (Kahn's algorithm) before generating `CREATE TABLE` statements. Referenced tables are created first.
-
----
-
-## SQLite Introspection
-
-### `introspectSchema(client)`
-
-Read the live database schema and return a `SchemaState` that can be diffed against code-defined tables.
-
-```ts
-import { introspectSchema } from 'flint-orm/sqlite';
-import { diffSchemas } from 'flint-orm/migration';
-
-const client = new Database('./app.db');
-const liveState = introspectSchema(client);
-
-// Compare live DB against code schema
-const codeState = serializeSchema([users, orders]);
-const operations = diffSchemas(liveState, codeState);
-```
-
-Normalizes SQLite type aliases (VARCHAR → TEXT, BIGINT → INTEGER, etc.) and parses default values.
-
 ---
 
 ## 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)                   |
-| `IndexDef`          | Index definition: `{ name, columns, unique }`                 |
-| `IndexBuilder`      | Chainable index builder: `.on(cols).unique()`                 |
-| `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()`) |