sumak 0.0.6 → 0.0.8

package/README.md

@@ -14,12 +14,50 @@
   <a href="https://github.com/productdevbook/sumak/blob/main/LICENSE"><img src="https://img.shields.io/github/license/productdevbook/sumak?style=flat&colorA=18181B&colorB=e11d48" alt="license"></a>
 </p>
 
-## Quick Start
+---
+
+## Table of Contents
+
+- [Install](#install)
+- [Quick Start](#quick-start)
+- [SELECT](#select)
+- [INSERT](#insert)
+- [UPDATE](#update)
+- [DELETE](#delete)
+- [WHERE Conditions](#where-conditions)
+- [Joins](#joins)
+- [Expressions](#expressions)
+- [Aggregates](#aggregates)
+- [Window Functions](#window-functions)
+- [SQL Functions](#sql-functions)
+- [Subqueries](#subqueries)
+- [Set Operations](#set-operations)
+- [CTEs (WITH)](#ctes-with)
+- [Conditional / Dynamic Queries](#conditional--dynamic-queries)
+- [Raw SQL](#raw-sql)
+- [ON CONFLICT / Upsert](#on-conflict--upsert)
+- [MERGE](#merge-sql2003)
+- [Row Locking](#row-locking)
+- [Schema Builder (DDL)](#schema-builder-ddl)
+- [Full-Text Search](#full-text-search)
+- [Temporal Tables](#temporal-tables-sql2011)
+- [Plugins](#plugins)
+- [Hooks](#hooks)
+- [Dialects](#dialects)
+- [Architecture](#architecture)
+
+---
+
+## Install
 
 ```sh
 npm install sumak
 ```
 
+## Quick Start
+
+Define your tables and create a typed instance:
+
 ```ts
 import { sumak, pgDialect, serial, text, boolean, integer, jsonb } from "sumak"
 
@@ -43,252 +81,302 @@ const db = sumak({
 })
 ```
 
-## Query Building
+That's it. `db` now knows every table, column, and type. All queries are fully type-checked.
 
-### SELECT
+---
+
+## SELECT
 
 ```ts
+// Basic select
+db.selectFrom("users").select("id", "name").toSQL()
+// SELECT "id", "name" FROM "users"
+
+// Select all columns
+db.selectFrom("users").selectAll().toSQL()
+
+// With WHERE, ORDER BY, LIMIT, OFFSET
 db.selectFrom("users")
   .select("id", "name")
-  .where(({ age, active }) => and(age.gte(18), active.eq(true)))
+  .where(({ age }) => age.gte(18))
   .orderBy("name")
   .limit(10)
-  .compile(db.printer())
+  .offset(20)
+  .toSQL()
+
+// DISTINCT
+db.selectFrom("users").select("name").distinct().toSQL()
+
+// DISTINCT ON (PostgreSQL)
+db.selectFrom("users")
+  .selectAll()
+  .distinctOn("dept")
+  .orderBy("dept")
+  .orderBy("salary", "DESC")
+  .toSQL()
 ```
 
-### INSERT
+---
+
+## INSERT
 
 ```ts
+// Single row
+db.insertInto("users").values({ name: "Alice", email: "alice@example.com" }).toSQL()
+
+// Multiple rows
 db.insertInto("users")
-  .values({
-    name: "Alice",
-    email: "alice@example.com",
-  })
-  .returningAll()
-  .compile(db.printer())
+  .valuesMany([
+    { name: "Alice", email: "a@b.com" },
+    { name: "Bob", email: "b@b.com" },
+  ])
+  .toSQL()
+
+// RETURNING
+db.insertInto("users").values({ name: "Alice", email: "a@b.com" }).returningAll().toSQL()
+
+// INSERT ... SELECT
+const source = db.selectFrom("users").select("name", "email").build()
+db.insertInto("archive").fromSelect(source).toSQL()
+
+// DEFAULT VALUES
+db.insertInto("users").defaultValues().toSQL()
+
+// SQLite: INSERT OR IGNORE / INSERT OR REPLACE
+db.insertInto("users").values({ name: "Alice" }).orIgnore().toSQL()
 ```
 
-### UPDATE
+---
+
+## UPDATE
 
 ```ts
+// Basic update
 db.update("users")
   .set({ active: false })
   .where(({ id }) => id.eq(1))
-  .compile(db.printer())
-```
+  .toSQL()
 
-### DELETE
+// SET with expression
+db.update("users")
+  .setExpr("name", val("Anonymous"))
+  .where(({ active }) => active.eq(false))
+  .toSQL()
 
-```ts
-db.deleteFrom("users")
+// UPDATE ... FROM (PostgreSQL)
+db.update("users")
+  .set({ name: "Bob" })
+  .from("posts")
   .where(({ id }) => id.eq(1))
-  .returning("id")
-  .compile(db.printer())
-```
-
-## Joins
+  .toSQL()
 
-```ts
-// INNER JOIN
-db.selectFrom("users")
-  .innerJoin("posts", ({ users, posts }) => users.id.eqCol(posts.userId))
-  .select("id", "title")
-  .compile(db.printer())
+// UPDATE with JOIN (MySQL)
+db.update("orders").set({ total: 0 }).innerJoin("users", onExpr).toSQL()
 
-// LEFT JOIN — joined columns become nullable
-db.selectFrom("users")
-  .leftJoin("posts", ({ users, posts }) => users.id.eqCol(posts.userId))
-  .compile(db.printer())
-
-// RIGHT JOIN
-db.selectFrom("users")
-  .rightJoin("posts", ({ users, posts }) => users.id.eqCol(posts.userId))
-  .compile(db.printer())
-
-// FULL JOIN — both sides become nullable
-db.selectFrom("users")
-  .fullJoin("posts", ({ users, posts }) => users.id.eqCol(posts.userId))
-  .compile(db.printer())
+// RETURNING
+db.update("users")
+  .set({ active: false })
+  .where(({ id }) => id.eq(1))
+  .returningAll()
+  .toSQL()
 
-// CROSS JOIN — cartesian product
-db.selectFrom("users").crossJoin("posts").compile(db.printer())
+// ORDER BY + LIMIT (MySQL)
+db.update("users").set({ active: false }).orderBy("id").limit(lit(10)).toSQL()
 ```
 
-## Expression API
+---
 
-### Comparisons
+## DELETE
 
 ```ts
-.where(({ id }) =>
-  id.eq(42),
-)
+db.deleteFrom("users")
+  .where(({ id }) => id.eq(1))
+  .toSQL()
 
-.where(({ age }) =>
-  age.gt(18),
-)
+// RETURNING
+db.deleteFrom("users")
+  .where(({ id }) => id.eq(1))
+  .returning("id")
+  .toSQL()
 
-.where(({ age }) =>
-  age.gte(18),
-)
+// DELETE ... USING (PostgreSQL)
+db.deleteFrom("orders").using("users").where(onExpr).toSQL()
 
-.where(({ age }) =>
-  age.lt(65),
-)
+// DELETE with JOIN (MySQL)
+db.deleteFrom("orders")
+  .innerJoin("users", onExpr)
+  .where(({ id }) => id.eq(1))
+  .toSQL()
+```
 
-.where(({ age }) =>
-  age.lte(65),
-)
+---
 
-.where(({ active }) =>
-  active.neq(false),
-)
-```
+## WHERE Conditions
 
-### String Matching
+Every `.where()` takes a callback with typed column proxies.
 
-```ts
-.where(({ name }) =>
-  name.like("%ali%"),
-)
+### Comparisons
 
-.where(({ name }) =>
-  name.notLike("%bob%"),
-)
+```ts
+.where(({ age }) => age.eq(25))        // = 25
+.where(({ age }) => age.neq(0))        // != 0
+.where(({ age }) => age.gt(18))        // > 18
+.where(({ age }) => age.gte(18))       // >= 18
+.where(({ age }) => age.lt(65))        // < 65
+.where(({ age }) => age.lte(65))       // <= 65
+```
 
-// Case-insensitive (PG)
-.where(({ name }) =>
-  name.ilike("%alice%"),
-)
+### Pattern Matching
 
-.where(({ email }) =>
-  email.notIlike("%spam%"),
-)
+```ts
+.where(({ name }) => name.like("%ali%"))         // LIKE
+.where(({ name }) => name.notLike("%bob%"))      // NOT LIKE
+.where(({ name }) => name.ilike("%alice%"))      // ILIKE (PG)
+.where(({ email }) => email.notIlike("%spam%"))  // NOT ILIKE
 ```
 
-### Range & List
+### Range & Lists
 
 ```ts
-.where(({ age }) =>
-  age.between(18, 65),
-)
+.where(({ age }) => age.between(18, 65))           // BETWEEN
+.where(({ age }) => age.notBetween(0, 17))         // NOT BETWEEN
+.where(({ age }) => age.betweenSymmetric(65, 18))  // BETWEEN SYMMETRIC (PG)
+.where(({ id }) => id.in([1, 2, 3]))               // IN
+.where(({ id }) => id.notIn([99, 100]))             // NOT IN
+```
 
-.where(({ age }) =>
-  age.notBetween(18, 65),
-)
+### Null Checks
 
-// Order-independent (PG)
-.where(({ age }) =>
-  age.betweenSymmetric(65, 18),
-)
+```ts
+.where(({ bio }) => bio.isNull())       // IS NULL
+.where(({ email }) => email.isNotNull()) // IS NOT NULL
+```
 
-.where(({ id }) =>
-  id.in([1, 2, 3]),
-)
+### Null-Safe Comparisons
 
-.where(({ id }) =>
-  id.notIn([99, 100]),
-)
+```ts
+.where(({ age }) => age.isDistinctFrom(null))      // IS DISTINCT FROM
+.where(({ age }) => age.isNotDistinctFrom(25))     // IS NOT DISTINCT FROM
 ```
 
-### Null Checks
+### IN Subquery
 
 ```ts
-.where(({ bio }) =>
-  bio.isNull(),
-)
+const deptIds = db
+  .selectFrom("departments")
+  .select("id")
+  .build()
 
-.where(({ email }) =>
-  email.isNotNull(),
-)
+  .where(({ dept_id }) => dept_id.inSubquery(deptIds)) // IN (SELECT ...)
+  .where(({ dept_id }) => dept_id.notInSubquery(deptIds)) // NOT IN (SELECT ...)
 ```
 
 ### Logical Combinators
 
 ```ts
-// AND
+// AND (variadic — 2 or more args)
 .where(({ age, active }) =>
-  and(
-    age.gt(0),
-    active.eq(true),
-  ),
+  and(age.gt(18), active.eq(true)),
+)
+
+// AND with 3+ conditions
+.where(({ id, age, active }) =>
+  and(id.gt(0), age.gt(18), active.eq(true)),
 )
 
-// OR
+// OR (variadic)
 .where(({ name, email }) =>
-  or(
-    name.like("%alice%"),
-    email.like("%alice%"),
-  ),
+  or(name.like("%alice%"), email.like("%alice%")),
 )
 
 // NOT
-.where(({ active }) =>
-  not(active.eq(true)),
-)
+.where(({ active }) => not(active.eq(true)))
 ```
 
-### Null-Safe Comparisons
+### Multiple WHERE (implicit AND)
 
 ```ts
-// IS DISTINCT FROM — null-safe inequality
-.where(({ age }) =>
-  age.isDistinctFrom(null),
-)
+// Calling .where() multiple times ANDs conditions together
+db.selectFrom("users")
+  .select("id")
+  .where(({ age }) => age.gt(18))
+  .where(({ active }) => active.eq(true))
+  .toSQL()
+// WHERE ("age" > $1) AND ("active" = $2)
+```
 
-// IS NOT DISTINCT FROM — null-safe equality
-.where(({ age }) =>
-  age.isNotDistinctFrom(25),
-)
+### Column-to-Column Comparisons
+
+```ts
+.where(({ price, cost }) => price.gtCol(cost))    // "price" > "cost"
+.where(({ a, b }) => a.eqCol(b))                  // "a" = "b"
+.where(({ a, b }) => a.neqCol(b))                 // "a" != "b"
+.where(({ a, b }) => a.gteCol(b))                 // "a" >= "b"
+.where(({ a, b }) => a.ltCol(b))                  // "a" < "b"
+.where(({ a, b }) => a.lteCol(b))                 // "a" <= "b"
 ```
 
-### Aggregates
+---
+
+## Joins
 
 ```ts
-import { count, countDistinct, sumDistinct, avgDistinct, sum, avg, min, max, coalesce } from "sumak"
+// INNER JOIN
+db.selectFrom("users")
+  .innerJoin("posts", ({ users, posts }) => users.id.eqCol(posts.userId))
+  .select("id", "title")
+  .toSQL()
 
-db.selectFrom("users").selectExpr(count(), "total").compile(db.printer())
+// LEFT JOIN — joined columns become nullable
+db.selectFrom("users")
+  .leftJoin("posts", ({ users, posts }) => users.id.eqCol(posts.userId))
+  .toSQL()
 
-db.selectFrom("users").selectExpr(countDistinct(col.dept), "uniqueDepts").compile(db.printer())
-// SELECT COUNT(DISTINCT "dept") AS "uniqueDepts" FROM "users"
+// RIGHT JOIN
+db.selectFrom("users")
+  .rightJoin("posts", ({ users, posts }) => users.id.eqCol(posts.userId))
+  .toSQL()
 
-db.selectFrom("orders").selectExpr(sum(col.amount), "totalAmount").compile(db.printer())
+// FULL JOIN — both sides nullable
+db.selectFrom("users")
+  .fullJoin("posts", ({ users, posts }) => users.id.eqCol(posts.userId))
+  .toSQL()
 
-db.selectFrom("orders").selectExpr(avg(col.amount), "avgAmount").compile(db.printer())
+// CROSS JOIN
+db.selectFrom("users").crossJoin("posts").toSQL()
 
-db.selectFrom("orders")
-  .selectExpr(coalesce(col.discount, val(0)), "safeDiscount")
-  .compile(db.printer())
+// LATERAL JOINs (correlated subqueries)
+db.selectFrom("users").innerJoinLateral(subquery, "recent_posts", onExpr).toSQL()
 
-// SUM(DISTINCT), AVG(DISTINCT)
-db.selectFrom("orders").selectExpr(sumDistinct(col.amount), "uniqueSum").compile(db.printer())
-db.selectFrom("orders").selectExpr(avgDistinct(col.amount), "uniqueAvg").compile(db.printer())
+db.selectFrom("users").leftJoinLateral(subquery, "recent_posts", onExpr).toSQL()
 
-// COALESCE with multiple fallbacks
-db.selectFrom("users")
-  .selectExpr(coalesce(col.nick, col.name, val("Anonymous")), "displayName")
-  .compile(db.printer())
+db.selectFrom("users").crossJoinLateral(subquery, "latest").toSQL()
 ```
 
-### String & JSON Aggregates
+---
 
-```ts
-import { stringAgg, arrayAgg, jsonAgg, jsonBuildObject } from "sumak"
+## Expressions
 
-// STRING_AGG with ORDER BY
-db.selectFrom("users")
-  .selectExpr(stringAgg(col.name, ", ", [{ expr: col.name, direction: "ASC" }]), "names")
-  .compile(db.printer())
-// STRING_AGG("name", ', ' ORDER BY "name" ASC)
+### Computed Columns
 
-// ARRAY_AGG
-db.selectFrom("users").selectExpr(arrayAgg(col.id), "ids").compile(db.printer())
+```ts
+import { val, cast, rawExpr } from "sumak"
 
-// JSON_AGG / JSON_BUILD_OBJECT
-db.selectFrom("users").selectExpr(jsonAgg(col.name), "namesJson").compile(db.printer())
+// Add a computed column with alias
+db.selectFrom("users").selectExpr(val("hello"), "greeting").toSQL()
 
+// Multiple expressions at once
 db.selectFrom("users")
-  .selectExpr(jsonBuildObject(["name", col.name], ["age", col.age]), "obj")
-  .compile(db.printer())
+  .selectExprs({
+    total: count(),
+    greeting: val("hello"),
+  })
+  .toSQL()
+
+// CAST
+db.selectFrom("users")
+  .selectExpr(cast(val(42), "text"), "idAsText")
+  .toSQL()
 ```
 
 ### Arithmetic
@@ -296,43 +384,15 @@ db.selectFrom("users")
 ```ts
 import { add, sub, mul, div, mod, neg } from "sumak"
 
-db.selectFrom("orders").selectExpr(mul(col.price, col.qty), "total").compile(db.printer())
+db.selectFrom("orders").selectExpr(mul(col.price, col.qty), "total").toSQL()
 // ("price" * "qty") AS "total"
 
 db.selectFrom("orders")
   .selectExpr(add(col.price, val(10)), "adjusted")
-  .compile(db.printer())
-```
-
-### EXISTS / NOT EXISTS
-
-```ts
-import { exists, notExists } from "sumak"
-
-db.selectFrom("users")
-  .where(() =>
-    exists(
-      db
-        .selectFrom("posts")
-        .where(({ userId }) => userId.eq(1))
-        .build(),
-    ),
-  )
-  .compile(db.printer())
-
-db.selectFrom("users")
-  .where(() =>
-    notExists(
-      db
-        .selectFrom("posts")
-        .where(({ userId }) => userId.eq(1))
-        .build(),
-    ),
-  )
-  .compile(db.printer())
+  .toSQL()
 ```
 
-### CASE Expression
+### CASE / WHEN
 
 ```ts
 import { case_, val } from "sumak"
@@ -346,151 +406,211 @@ db.selectFrom("users")
       .end(),
     "status",
   )
-  .compile(db.printer())
+  .toSQL()
 ```
 
-### CAST
+### JSON Operations
 
 ```ts
-import { cast, val } from "sumak"
+import { jsonRef, jsonAgg, toJson, jsonBuildObject } from "sumak"
 
+// Access: ->  (JSON object), ->> (text value)
 db.selectFrom("users")
-  .selectExpr(cast(val(42), "text"), "idAsText")
-  .compile(db.printer())
+  .selectExpr(jsonRef(col.meta, "name", "->>"), "metaName")
+  .toSQL()
+
+// JSON_AGG / TO_JSON
+db.selectFrom("users").selectExpr(jsonAgg(col.name), "namesJson").toSQL()
+
+// JSON_BUILD_OBJECT
+db.selectFrom("users")
+  .selectExpr(jsonBuildObject(["name", col.name], ["age", col.age]), "obj")
+  .toSQL()
 ```
 
-### JSON Operations
+### PostgreSQL Array Operators
+
+```ts
+import { arrayContains, arrayContainedBy, arrayOverlaps, rawExpr } from "sumak"
+
+.where(() => arrayContains(rawExpr("tags"), rawExpr("ARRAY['sql']")))    // @>
+.where(() => arrayContainedBy(rawExpr("tags"), rawExpr("ARRAY[...]")))   // <@
+.where(() => arrayOverlaps(rawExpr("tags"), rawExpr("ARRAY['sql']")))    // &&
+```
+
+---
+
+## Aggregates
 
 ```ts
-import { jsonRef } from "sumak"
+import { count, countDistinct, sum, sumDistinct, avg, avgDistinct, min, max, coalesce } from "sumak"
+
+db.selectFrom("users").selectExpr(count(), "total").toSQL()
+db.selectFrom("users").selectExpr(countDistinct(col.dept), "uniqueDepts").toSQL()
+db.selectFrom("orders").selectExpr(sumDistinct(col.amount), "uniqueSum").toSQL()
+db.selectFrom("orders").selectExpr(avg(col.amount), "avgAmount").toSQL()
 
-// ->  (JSON object)
+// COALESCE (variadic)
 db.selectFrom("users")
-  .selectExpr(jsonRef(col.meta, "address", "->"), "address")
-  .compile(db.printer())
+  .selectExpr(coalesce(col.nick, col.name, val("Anonymous")), "displayName")
+  .toSQL()
+```
+
+### Aggregate with FILTER (PostgreSQL)
+
+```ts
+import { filter, count } from "sumak"
 
-// ->> (text value)
+db.selectFrom("users").selectExpr(filter(count(), activeExpr), "activeCount").toSQL()
+// COUNT(*) FILTER (WHERE ...)
+```
+
+### Aggregate with ORDER BY
+
+```ts
+import { stringAgg, arrayAgg } from "sumak"
+
+// STRING_AGG with ORDER BY
 db.selectFrom("users")
-  .selectExpr(jsonRef(col.meta, "name", "->>"), "metaName")
-  .compile(db.printer())
+  .selectExpr(stringAgg(col.name, ", ", [{ expr: col.name, direction: "ASC" }]), "names")
+  .toSQL()
+// STRING_AGG("name", ', ' ORDER BY "name" ASC)
+
+// ARRAY_AGG
+db.selectFrom("users").selectExpr(arrayAgg(col.id), "ids").toSQL()
 ```
 
+---
+
 ## Window Functions
 
 ```ts
 import { over, rowNumber, rank, denseRank, lag, lead, ntile, count, sum } from "sumak"
 
-// ROW_NUMBER() OVER (PARTITION BY dept ORDER BY salary DESC)
+// ROW_NUMBER
 db.selectFrom("employees")
   .selectExpr(
     over(rowNumber(), (w) => w.partitionBy("dept").orderBy("salary", "DESC")),
     "rn",
   )
-  .compile(db.printer())
+  .toSQL()
 
-// RANK() OVER (ORDER BY score DESC)
-db.selectFrom("students")
-  .selectExpr(
-    over(rank(), (w) => w.orderBy("score", "DESC")),
-    "rnk",
-  )
-  .compile(db.printer())
+// RANK / DENSE_RANK
+over(rank(), (w) => w.orderBy("score", "DESC"))
+over(denseRank(), (w) => w.orderBy("score", "DESC"))
 
 // Running total with frame
-db.selectFrom("orders")
-  .selectExpr(
-    over(sum(col.amount), (w) =>
-      w
-        .partitionBy("userId")
-        .orderBy("createdAt")
-        .rows({ type: "unbounded_preceding" }, { type: "current_row" }),
-    ),
-    "runningTotal",
-  )
-  .compile(db.printer())
+over(sum(col.amount), (w) =>
+  w
+    .partitionBy("userId")
+    .orderBy("createdAt")
+    .rows({ type: "unbounded_preceding" }, { type: "current_row" }),
+)
 
-// LAG / LEAD
-db.selectFrom("prices")
-  .selectExpr(
-    over(lag(col.price, 1), (w) => w.orderBy("date")),
-    "prevPrice",
-  )
-  .compile(db.printer())
+// RANGE / GROUPS frames
+over(count(), (w) =>
+  w.orderBy("salary").range({ type: "preceding", value: 100 }, { type: "following", value: 100 }),
+)
 
-// NTILE(4)
-db.selectFrom("employees")
-  .selectExpr(
-    over(ntile(4), (w) => w.orderBy("salary", "DESC")),
-    "quartile",
-  )
-  .compile(db.printer())
+// LAG / LEAD / NTILE
+over(lag(col.price, 1), (w) => w.orderBy("date"))
+over(lead(col.price, 1), (w) => w.orderBy("date"))
+over(ntile(4), (w) => w.orderBy("salary", "DESC"))
 ```
 
+---
+
 ## SQL Functions
 
-### String Functions
+### String
 
 ```ts
 import { upper, lower, concat, substring, trim, length } from "sumak"
 
-db.selectFrom("users").selectExpr(upper(col.name), "upperName").compile(db.printer())
-// SELECT UPPER("name") AS "upperName" FROM "users"
+upper(col.name) // UPPER("name")
+lower(col.email) // LOWER("email")
+concat(col.first, val(" "), col.last) // CONCAT(...)
+substring(col.name, 1, 3) // SUBSTRING("name", 1, 3)
+trim(col.name) // TRIM("name")
+length(col.name) // LENGTH("name")
+```
 
-db.selectFrom("users").selectExpr(lower(col.email), "lowerEmail").compile(db.printer())
+### Numeric
 
-db.selectFrom("users")
-  .selectExpr(concat(col.firstName, val(" "), col.lastName), "fullName")
-  .compile(db.printer())
+```ts
+import { abs, round, ceil, floor, greatest, least } from "sumak"
+
+abs(col.balance) // ABS("balance")
+round(col.price, 2) // ROUND("price", 2)
+ceil(col.amount) // CEIL("amount")
+floor(col.amount) // FLOOR("amount")
+greatest(col.a, col.b) // GREATEST("a", "b")
+least(col.a, col.b) // LEAST("a", "b")
+```
 
-db.selectFrom("users")
-  .selectExpr(substring(col.name, 1, 3), "prefix")
-  .compile(db.printer())
+### Conditional
 
-db.selectFrom("users").selectExpr(trim(col.name), "trimmed").compile(db.printer())
+```ts
+import { nullif, coalesce } from "sumak"
 
-db.selectFrom("users").selectExpr(length(col.name), "nameLen").compile(db.printer())
+nullif(col.age, val(0)) // NULLIF("age", 0)
+coalesce(col.nick, col.name, val("Anonymous")) // COALESCE(...)
 ```
 
-### Numeric Functions
+### Date/Time
 
 ```ts
-import { abs, round, ceil, floor } from "sumak"
-
-db.selectFrom("orders").selectExpr(abs(col.balance), "absBalance").compile(db.printer())
+import { now, currentTimestamp } from "sumak"
 
-db.selectFrom("orders").selectExpr(round(col.price, 2), "rounded").compile(db.printer())
+now() // NOW()
+currentTimestamp() // CURRENT_TIMESTAMP()
+```
 
-db.selectFrom("orders").selectExpr(ceil(col.amount), "ceiling").compile(db.printer())
+---
 
-db.selectFrom("orders").selectExpr(floor(col.amount), "floored").compile(db.printer())
-```
+## Subqueries
 
-### Conditional Functions
+### EXISTS / NOT EXISTS
 
 ```ts
-import { nullif, greatest, least } from "sumak"
+import { exists, notExists } from "sumak"
 
 db.selectFrom("users")
-  .selectExpr(nullif(col.age, val(0)), "ageOrNull")
-  .compile(db.printer())
+  .where(() =>
+    exists(
+      db
+        .selectFrom("posts")
+        .where(({ userId }) => userId.eq(1))
+        .build(),
+    ),
+  )
+  .toSQL()
+```
+
+### Derived Tables (Subquery in FROM)
 
-db.selectFrom("products")
-  .selectExpr(greatest(col.price, col.minPrice), "effectivePrice")
-  .compile(db.printer())
+```ts
+const sub = db
+  .selectFrom("users")
+  .select("id", "name")
+  .where(({ age }) => age.gt(18))
 
-db.selectFrom("products")
-  .selectExpr(least(col.price, col.maxPrice), "cappedPrice")
-  .compile(db.printer())
+db.selectFromSubquery(sub, "adults").selectAll().toSQL()
+// SELECT * FROM (SELECT ...) AS "adults"
 ```
 
-### Date/Time Functions
+### IN Subquery
 
 ```ts
-import { now, currentTimestamp } from "sumak"
+const deptIds = db.selectFrom("departments").select("id").build()
 
-db.selectFrom("users").selectExpr(now(), "currentTime").compile(db.printer())
+db.selectFrom("users")
+  .where(({ dept_id }) => dept_id.inSubquery(deptIds))
+  .toSQL()
 ```
 
+---
+
 ## Set Operations
 
 ```ts
@@ -498,72 +618,40 @@ const active = db
   .selectFrom("users")
   .select("id")
   .where(({ active }) => active.eq(true))
-
 const premium = db
   .selectFrom("users")
   .select("id")
-  .where(({ active }) => active.eq(true))
-
-// UNION
-active.union(premium).compile(db.printer())
-
-// UNION ALL
-active.unionAll(premium).compile(db.printer())
-
-// INTERSECT / INTERSECT ALL
-active.intersect(premium).compile(db.printer())
-active.intersectAll(premium).compile(db.printer())
-
-// EXCEPT / EXCEPT ALL
-active.except(premium).compile(db.printer())
-active.exceptAll(premium).compile(db.printer())
+  .where(({ tier }) => tier.eq("premium"))
+
+active.union(premium).toSQL() // UNION
+active.unionAll(premium).toSQL() // UNION ALL
+active.intersect(premium).toSQL() // INTERSECT
+active.intersectAll(premium).toSQL() // INTERSECT ALL
+active.except(premium).toSQL() // EXCEPT
+active.exceptAll(premium).toSQL() // EXCEPT ALL
 ```
 
+---
+
 ## CTEs (WITH)
 
 ```ts
-// SELECT with CTE
-db.selectFrom("users")
-  .with(
-    "active_users",
-    db
-      .selectFrom("users")
-      .where(({ active }) => active.eq(true))
-      .build(),
-  )
-  .compile(db.printer())
-
-// INSERT with CTE
-db.insertInto("users")
-  .with("source", sourceCte)
-  .values({ name: "Alice", email: "a@b.com" })
-  .compile(db.printer())
-
-// UPDATE with CTE
-db.update("users").with("target", targetCte).set({ active: false }).compile(db.printer())
+const activeCte = db
+  .selectFrom("users")
+  .where(({ active }) => active.eq(true))
+  .build()
 
-// DELETE with CTE
-db.deleteFrom("users")
-  .with("to_delete", deleteCte)
-  .where(({ id }) => id.eq(1))
-  .compile(db.printer())
+db.selectFrom("users").with("active_users", activeCte).toSQL()
 
 // Recursive CTE
-db.selectFrom("users").with("tree", recursiveQuery, true).compile(db.printer())
+db.selectFrom("categories").with("tree", recursiveQuery, true).toSQL()
 ```
 
-## UPDATE FROM
+---
 
-```ts
-db.update("users")
-  .set({ name: "Bob" })
-  .from("posts")
-  .where(({ id }) => id.eq(1))
-  .compile(db.printer())
-// UPDATE "users" SET "name" = $1 FROM "posts" WHERE ("id" = $2)
-```
+## Conditional / Dynamic Queries
 
-## Conditional Query Building
+### `$if()` — conditional clause
 
 ```ts
 const withFilter = true
@@ -573,350 +661,342 @@ db.selectFrom("users")
   .select("id", "name")
   .$if(withFilter, (qb) => qb.where(({ age }) => age.gt(18)))
   .$if(withOrder, (qb) => qb.orderBy("name"))
-  .compile(db.printer())
+  .toSQL()
 // WHERE applied, ORDER BY skipped
+```
+
+### `$call()` — reusable query fragments
+
+```ts
+const withPagination = (qb) => qb.limit(10).offset(20)
+const onlyActive = (qb) => qb.where(({ active }) => active.eq(true))
 
-// Multiple .where() calls are AND'd together
+db.selectFrom("users").select("id", "name").$call(onlyActive).$call(withPagination).toSQL()
+```
+
+### `clear*()` — reset clauses
+
+```ts
 db.selectFrom("users")
   .select("id")
-  .where(({ age }) => age.gt(18))
-  .where(({ active }) => active.eq(true))
-  .compile(db.printer())
-// WHERE ("age" > $1) AND ("active" = $2)
+  .orderBy("name")
+  .clearOrderBy() // removes ORDER BY
+  .orderBy("id", "DESC") // re-add different order
+  .toSQL()
 ```
 
-## Reusable Query Fragments
+Available: `clearWhere()`, `clearOrderBy()`, `clearLimit()`, `clearOffset()`, `clearGroupBy()`, `clearHaving()`, `clearSelect()`.
+
+---
+
+## Raw SQL
+
+### `sql` tagged template
 
 ```ts
-// $call — pipe builder through a function
-const withPagination = (qb) => qb.limit(10).offset(20)
-const withActiveFilter = (qb) => qb.where(({ active }) => active.eq(true))
+import { sql } from "sumak"
 
-db.selectFrom("users")
-  .select("id", "name")
-  .$call(withActiveFilter)
-  .$call(withPagination)
-  .compile(db.printer())
+// Primitives are parameterized
+sql`SELECT * FROM users WHERE name = ${"Alice"}`
+// params: ["Alice"]
+
+// Expressions are inlined
+sql`SELECT * FROM users WHERE active = ${val(true)}`
+// → ... WHERE active = TRUE
+
+// Helpers
+sql`SELECT ${sql.ref("id")} FROM ${sql.table("users", "public")}`
+// → SELECT "id" FROM "public"."users"
 
-// selectExprs — multiple aliased expressions at once
+// In queries
 db.selectFrom("users")
-  .selectExprs({
-    total: count(),
-    greeting: val("hello"),
-  })
-  .compile(db.printer())
+  .selectExpr(sql`CURRENT_DATE`, "today")
+  .toSQL()
 ```
 
-## INSERT Advanced
+### `rawExpr()` escape hatch
 
 ```ts
-// INSERT ... SELECT
-const selectQuery = db.selectFrom("users").select("name", "age").build()
-db.insertInto("archive").fromSelect(selectQuery).compile(db.printer())
-
-// INSERT ... DEFAULT VALUES
-db.insertInto("users").defaultValues().compile(db.printer())
+import { rawExpr } from "sumak"
 
-// SQLite: INSERT OR IGNORE / INSERT OR REPLACE
-db.insertInto("users").values({ name: "Alice" }).orIgnore().compile(db.printer())
-// INSERT OR IGNORE INTO "users" ...
+// In WHERE
+db.selectFrom("users")
+  .where(() => rawExpr<boolean>("age > 18"))
+  .toSQL()
 
-db.insertInto("users").values({ name: "Alice" }).orReplace().compile(db.printer())
-// INSERT OR REPLACE INTO "users" ...
+// In SELECT
+db.selectFrom("users").selectExpr(rawExpr<number>("EXTRACT(YEAR FROM created_at)"), "year").toSQL()
 ```
 
-## ON CONFLICT
+---
+
+## ON CONFLICT / Upsert
 
 ```ts
-// DO NOTHING (by columns)
+// PostgreSQL: ON CONFLICT DO NOTHING
 db.insertInto("users")
   .values({ name: "Alice", email: "a@b.com" })
   .onConflictDoNothing("email")
-  .compile(db.printer())
+  .toSQL()
 
-// DO UPDATE (by columns)
+// ON CONFLICT DO UPDATE (with Expression)
 db.insertInto("users")
   .values({ name: "Alice", email: "a@b.com" })
-  .onConflictDoUpdate(["email"], [{ column: "name", value: val("Alice") }])
-  .compile(db.printer())
+  .onConflictDoUpdate(["email"], [{ column: "name", value: val("Updated") }])
+  .toSQL()
 
-// DO NOTHING (by constraint name)
+// ON CONFLICT DO UPDATE (with plain object — auto-parameterized)
+db.insertInto("users")
+  .values({ name: "Alice", email: "a@b.com" })
+  .onConflictDoUpdateSet(["email"], { name: "Alice Updated" })
+  .toSQL()
+
+// ON CONFLICT ON CONSTRAINT
 db.insertInto("users")
   .values({ name: "Alice", email: "a@b.com" })
   .onConflictConstraintDoNothing("users_email_key")
-  .compile(db.printer())
-// ON CONFLICT ON CONSTRAINT "users_email_key" DO NOTHING
+  .toSQL()
 
 // MySQL: ON DUPLICATE KEY UPDATE
 db.insertInto("users")
   .values({ name: "Alice" })
   .onDuplicateKeyUpdate([{ column: "name", value: val("Alice") }])
-  .compile(db.printer())
+  .toSQL()
 ```
 
+---
+
 ## MERGE (SQL:2003)
 
 ```ts
 db.mergeInto("users", "staging", "s", ({ target, source }) => target.id.eqCol(source.id))
   .whenMatchedThenUpdate({ name: "updated" })
-  .whenNotMatchedThenInsert({
-    name: "Alice",
-    email: "alice@example.com",
-  })
-  .compile(db.printer())
+  .whenNotMatchedThenInsert({ name: "Alice", email: "a@b.com" })
+  .toSQL()
 
-// MERGE with conditional delete
+// Conditional delete
 db.mergeInto("users", "staging", "s", ({ target, source }) => target.id.eqCol(source.id))
   .whenMatchedThenDelete()
-  .compile(db.printer())
+  .toSQL()
 ```
 
+---
+
 ## Row Locking
 
 ```ts
-// FOR UPDATE
-db.selectFrom("users").select("id").forUpdate().compile(db.printer())
-
-// FOR SHARE
-db.selectFrom("users").select("id").forShare().compile(db.printer())
-
-// FOR NO KEY UPDATE / FOR KEY SHARE (PG)
-db.selectFrom("users").select("id").forNoKeyUpdate().compile(db.printer())
-db.selectFrom("users").select("id").forKeyShare().compile(db.printer())
-
-// SKIP LOCKED / NOWAIT
-db.selectFrom("users").select("id").forUpdate().skipLocked().compile(db.printer())
-db.selectFrom("users").select("id").forUpdate().noWait().compile(db.printer())
+db.selectFrom("users").select("id").forUpdate().toSQL() // FOR UPDATE
+db.selectFrom("users").select("id").forShare().toSQL() // FOR SHARE
+db.selectFrom("users").select("id").forNoKeyUpdate().toSQL() // FOR NO KEY UPDATE (PG)
+db.selectFrom("users").select("id").forKeyShare().toSQL() // FOR KEY SHARE (PG)
+
+// Modifiers
+db.selectFrom("users").select("id").forUpdate().skipLocked().toSQL() // SKIP LOCKED
+db.selectFrom("users").select("id").forUpdate().noWait().toSQL() // NOWAIT
 ```
 
-## DISTINCT ON (PG)
+---
 
-```ts
-db.selectFrom("users")
-  .selectAll()
-  .distinctOn("dept")
-  .orderBy("dept")
-  .orderBy("salary", "DESC")
-  .compile(db.printer())
-// SELECT DISTINCT ON ("dept") * FROM "users" ORDER BY "dept" ASC, "salary" DESC
-```
-
-## DELETE USING / JOIN in UPDATE & DELETE
+## EXPLAIN
 
 ```ts
-// PG: DELETE ... USING
-db.deleteFrom("orders")
-  .using("users")
-  .where(eq(col("orders.user_id"), col("users.id")))
-  .compile(db.printer())
+db.selectFrom("users").select("id").explain().toSQL()
+// EXPLAIN SELECT "id" FROM "users"
 
-// MySQL: DELETE with JOIN
-db.deleteFrom("orders")
-  .innerJoin("users", eq(col("user_id", "orders"), col("id", "users")))
-  .where(eq(col("name", "users"), lit("Alice")))
-  .compile(db.printer())
+db.selectFrom("users").select("id").explain({ analyze: true }).toSQL()
+// EXPLAIN ANALYZE SELECT ...
 
-// MySQL: UPDATE with JOIN
-db.update("orders")
-  .set({ total: 0 })
-  .innerJoin("users", eq(col("user_id", "orders"), col("id", "users")))
-  .compile(db.printer())
+db.selectFrom("users").select("id").explain({ format: "JSON" }).toSQL()
+// EXPLAIN (FORMAT JSON) SELECT ...
 ```
 
-## Lateral JOIN
+---
 
-```ts
-// INNER JOIN LATERAL — correlated subquery join
-const recentPosts = db
-  .selectFrom("posts")
-  .select("id", "title")
-  .where(({ userId }) => userId.eq(1))
-  .limit(3)
+## Schema Builder (DDL)
 
-db.selectFrom("users").innerJoinLateral(recentPosts, "rp", onExpr).compile(db.printer())
-// SELECT * FROM "users" INNER JOIN LATERAL (SELECT ...) AS "rp" ON ...
+The schema builder generates DDL SQL (CREATE, ALTER, DROP). It is separate from the query builder — you use `db.compileDDL(node)` to compile DDL nodes.
 
-// LEFT JOIN LATERAL
-db.selectFrom("users").leftJoinLateral(recentPosts, "rp", onExpr).compile(db.printer())
-```
-
-## Tuple Comparisons
+### CREATE TABLE
 
 ```ts
-import { tuple, val } from "sumak"
-
-// Row-value comparison: (id, age) = (1, 25)
-db.selectFrom("users")
-  .selectExpr(tuple(val(1), val(2), val(3)), "triple")
-  .compile(db.printer())
-// (1, 2, 3)
+db.schema
+  .createTable("users")
+  .ifNotExists()
+  .addColumn("id", "serial", (c) => c.primaryKey())
+  .addColumn("name", "varchar(255)", (c) => c.notNull())
+  .addColumn("email", "varchar", (c) => c.unique().notNull())
+  .addColumn("active", "boolean", (c) => c.defaultTo(lit(true)))
+  .build()
+
+// Foreign key with ON DELETE CASCADE
+db.schema
+  .createTable("posts")
+  .addColumn("id", "serial", (c) => c.primaryKey())
+  .addColumn("user_id", "integer", (c) => c.notNull().references("users", "id").onDelete("CASCADE"))
+  .build()
+
+// Composite primary key
+db.schema
+  .createTable("order_items")
+  .addColumn("order_id", "integer")
+  .addColumn("product_id", "integer")
+  .addPrimaryKeyConstraint("pk_order_items", ["order_id", "product_id"])
+  .build()
 ```
 
-## SQL Template Literal
+### ALTER TABLE
 
 ```ts
-import { sql, val } from "sumak"
+db.schema
+  .alterTable("users")
+  .addColumn("age", "integer", (c) => c.notNull())
+  .build()
+
+db.schema.alterTable("users").dropColumn("age").build()
+db.schema.alterTable("users").renameColumn("name", "full_name").build()
+db.schema.alterTable("users").renameTo("people").build()
+
+db.schema
+  .alterTable("users")
+  .alterColumn("age", { type: "set_data_type", dataType: "bigint" })
+  .build()
+db.schema.alterTable("users").alterColumn("name", { type: "set_not_null" }).build()
+```
 
-// Tagged template with auto-parameterization
-sql`SELECT * FROM users WHERE name = ${"Alice"}`
-// params: ["Alice"]
+### CREATE INDEX
 
-// Inline Expression values
-sql`SELECT * FROM users WHERE active = ${val(true)}`
-// → SELECT * FROM users WHERE active = TRUE
+```ts
+db.schema.createIndex("idx_users_name").on("users").column("name").build()
+db.schema.createIndex("uq_email").unique().on("users").column("email").build()
+
+// Multi-column with direction
+db.schema
+  .createIndex("idx_multi")
+  .on("users")
+  .column("last_name", "ASC")
+  .column("age", "DESC")
+  .build()
+
+// GIN index (PG)
+db.schema.createIndex("idx_tags").on("posts").column("tags").using("gin").build()
+
+// Partial index
+db.schema
+  .createIndex("idx_active")
+  .on("users")
+  .column("email")
+  .where(rawExpr("active = true"))
+  .build()
+```
 
-// Helpers
-sql`SELECT ${sql.ref("id")} FROM ${sql.table("users", "public")}`
-// → SELECT "id" FROM "public"."users"
+### CREATE VIEW
 
-// Use in selectExpr
-db.selectFrom("users")
-  .selectExpr(sql`CURRENT_DATE`, "today")
-  .compile(db.printer())
+```ts
+db.schema.createView("active_users").asSelect(selectQuery).build()
+db.schema.createView("stats").materialized().asSelect(selectQuery).build()
+db.schema.createView("my_view").orReplace().columns("id", "name").asSelect(selectQuery).build()
 ```
 
-## Aggregate FILTER (WHERE)
+### DROP
 
 ```ts
-import { filter, count, sum } from "sumak"
-
-// COUNT(*) FILTER (WHERE active = true)
-db.selectFrom("users").selectExpr(filter(count(), activeExpr), "activeCount").compile(db.printer())
+db.schema.dropTable("users").ifExists().cascade().build()
+db.schema.dropIndex("idx_name").ifExists().build()
+db.schema.dropView("my_view").materialized().ifExists().build()
 ```
 
-## EXPLAIN
+### Auto-Generate from Schema
+
+The schema you pass to `sumak({ tables })` can auto-generate CREATE TABLE SQL:
 
 ```ts
-// EXPLAIN
-db.selectFrom("users").select("id").explain().compile(db.printer())
-// EXPLAIN SELECT "id" FROM "users"
+const db = sumak({
+  dialect: pgDialect(),
+  tables: {
+    users: {
+      id: serial().primaryKey(),
+      name: text().notNull(),
+      email: text().notNull(),
+    },
+    posts: {
+      id: serial().primaryKey(),
+      title: text().notNull(),
+      userId: integer().references("users", "id"),
+    },
+  },
+})
 
-// EXPLAIN ANALYZE
-db.selectFrom("users").select("id").explain({ analyze: true }).compile(db.printer())
+const ddl = db.generateDDL()
+// [
+//   { sql: 'CREATE TABLE "users" ("id" serial PRIMARY KEY NOT NULL, "name" text NOT NULL, "email" text NOT NULL)', params: [] },
+//   { sql: 'CREATE TABLE "posts" ("id" serial PRIMARY KEY NOT NULL, "title" text NOT NULL, "userId" integer REFERENCES "users"("id"))', params: [] },
+// ]
 
-// EXPLAIN with format
-db.selectFrom("users").select("id").explain({ format: "JSON" }).compile(db.printer())
-// EXPLAIN (FORMAT JSON) SELECT "id" FROM "users"
+// With IF NOT EXISTS
+const safeDDL = db.generateDDL({ ifNotExists: true })
 ```
 
+> Compile any DDL node: `db.compileDDL(node)` returns `{ sql, params }`.
+
+---
+
 ## Full-Text Search
 
-Dialect-aware FTS — same API, different SQL per dialect:
+Dialect-aware — same API, different SQL per dialect:
 
 ```ts
-import { textSearch } from "sumak"
+import { textSearch, val } from "sumak"
 
 // PostgreSQL: to_tsvector("name") @@ to_tsquery('alice')
 db.selectFrom("users")
   .where(({ name }) => textSearch([name.toExpr()], val("alice")))
-  .compile(db.printer())
-
-// With language config
-db.selectFrom("users")
-  .where(({ name }) => textSearch([name.toExpr()], val("alice"), { language: "english" }))
-  .compile(db.printer())
+  .toSQL()
 
 // MySQL: MATCH(`name`) AGAINST(? IN BOOLEAN MODE)
 // SQLite: ("name" MATCH ?)
 // MSSQL: CONTAINS(([name]), @p0)
 ```
 
-## Temporal Tables (SQL:2011)
+---
 
-Query historical data with `FOR SYSTEM_TIME`:
+## Temporal Tables (SQL:2011)
 
 ```ts
-// AS OF — point-in-time query
+// Point-in-time query
 db.selectFrom("users")
-  .forSystemTime({
-    kind: "as_of",
-    timestamp: lit("2024-01-01"),
-  })
-  .compile(db.printer())
+  .forSystemTime({ kind: "as_of", timestamp: lit("2024-01-01") })
+  .toSQL()
 
-// BETWEEN — time range
+// Time range
 db.selectFrom("users")
-  .forSystemTime({
-    kind: "between",
-    start: lit("2024-01-01"),
-    end: lit("2024-12-31"),
-  })
-  .compile(db.printer())
-
-// ALL — full history
-db.selectFrom("users").forSystemTime({ kind: "all" }).compile(db.printer())
-```
-
-Supported modes: `as_of`, `from_to`, `between`, `contained_in`, `all`.
-
-## Tree Shaking
-
-Import only the dialect you need:
+  .forSystemTime({ kind: "between", start: lit("2024-01-01"), end: lit("2024-12-31") })
+  .toSQL()
 
-```ts
-import { sumak } from "sumak"
-import { pgDialect } from "sumak/pg"
-import { mssqlDialect } from "sumak/mssql"
-import { mysqlDialect } from "sumak/mysql"
-import { sqliteDialect } from "sumak/sqlite"
-import { serial, text } from "sumak/schema"
-```
-
-## Dialects
-
-Same query, different SQL:
-
-```ts
-// PostgreSQL  → SELECT "id" FROM "users" WHERE ("id" = $1)
-// MySQL       → SELECT `id` FROM `users` WHERE (`id` = ?)
-// SQLite      → SELECT "id" FROM "users" WHERE ("id" = ?)
-// MSSQL       → SELECT [id] FROM [users] WHERE ([id] = @p0)
+// Full history
+db.selectFrom("users").forSystemTime({ kind: "all" }).toSQL()
 ```
 
-### MSSQL Specifics
-
-```ts
-import { mssqlDialect } from "sumak/mssql"
-
-const db = sumak({
-  dialect: mssqlDialect(),
-  tables: { ... },
-})
-
-// LIMIT → TOP N
-// SELECT TOP 10 * FROM [users]
-
-// LIMIT + OFFSET → OFFSET/FETCH
-// SELECT * FROM [users] ORDER BY [id] ASC OFFSET 20 ROWS FETCH NEXT 10 ROWS ONLY
-
-// RETURNING → OUTPUT INSERTED.*
-// INSERT INTO [users] ([name]) OUTPUT INSERTED.* VALUES (@p0)
+Modes: `as_of`, `from_to`, `between`, `contained_in`, `all`.
 
-// DELETE RETURNING → OUTPUT DELETED.*
-// DELETE FROM [users] OUTPUT DELETED.* WHERE ([id] = @p0)
-```
+---
 
 ## Plugins
 
 ```ts
-import {
-  WithSchemaPlugin,
-  SoftDeletePlugin,
-  CamelCasePlugin,
-} from "sumak"
+import { WithSchemaPlugin, SoftDeletePlugin, CamelCasePlugin } from "sumak"
 
 const db = sumak({
   dialect: pgDialect(),
   plugins: [
-    new WithSchemaPlugin("public"),
-    new SoftDeletePlugin({ tables: ["users"] }),
+    new WithSchemaPlugin("public"),      // auto "public"."users"
+    new SoftDeletePlugin({ tables: ["users"] }), // auto WHERE deleted_at IS NULL
   ],
   tables: { ... },
 })
-
-// SELECT * FROM "public"."users" WHERE ("deleted_at" IS NULL)
 ```
 
+---
+
 ## Hooks
 
 ```ts
@@ -925,14 +1005,6 @@ db.hook("query:after", (ctx) => {
   console.log(`[SQL] ${ctx.query.sql}`)
 })
 
-// Add request tracing
-db.hook("query:after", (ctx) => {
-  return {
-    ...ctx.query,
-    sql: `${ctx.query.sql} /* request_id=${requestId} */`,
-  }
-})
-
 // Modify AST before compilation
 db.hook("select:before", (ctx) => {
   // Add tenant isolation, audit filters, etc.
@@ -948,29 +1020,94 @@ const off = db.hook("query:before", handler)
 off()
 ```
 
-## Why sumak?
+---
+
+## Dialects
 
-|                    | sumak             | Drizzle         | Kysely         |
-| ------------------ | ----------------- | --------------- | -------------- |
-| **Architecture**   | AST-first         | Template        | AST (98 nodes) |
-| **Type inference** | Auto (no codegen) | Auto            | Manual DB type |
-| **Plugin system**  | Hooks + plugins   | None            | Plugins only   |
-| **SQL printer**    | Wadler algebra    | Template concat | String append  |
-| **Dependencies**   | 0                 | 0               | 0              |
-| **Node types**     | ~35 (focused)     | Config objects  | 98 (complex)   |
-| **API style**      | Callback proxy    | Method chain    | Method chain   |
+4 dialects supported. Same query, different SQL:
+
+```ts
+// PostgreSQL  → SELECT "id" FROM "users" WHERE ("id" = $1)
+// MySQL       → SELECT `id` FROM `users` WHERE (`id` = ?)
+// SQLite      → SELECT "id" FROM "users" WHERE ("id" = ?)
+// MSSQL       → SELECT [id] FROM [users] WHERE ([id] = @p0)
+```
+
+```ts
+import { pgDialect } from "sumak/pg"
+import { mysqlDialect } from "sumak/mysql"
+import { sqliteDialect } from "sumak/sqlite"
+import { mssqlDialect } from "sumak/mssql"
+```
+
+### Tree Shaking
+
+Import only the dialect you need — unused dialects are eliminated:
+
+```ts
+import { sumak } from "sumak"
+import { pgDialect } from "sumak/pg"
+import { serial, text } from "sumak/schema"
+```
+
+---
 
 ## Architecture
 
+sumak uses a 5-layer pipeline. Your code never touches SQL strings — everything flows through an AST.
+
 ```
-Schema → Builder → AST → Plugin/Hook → Printer → SQL
+┌─────────────────────────────────────────────────────────────────┐
+│  1. SCHEMA                                                      │
+│     sumak({ dialect, tables: { users: { id: serial(), ... } } })│
+│     → DB type auto-inferred, zero codegen                       │
+├─────────────────────────────────────────────────────────────────┤
+│  2. BUILDER                                                     │
+│     db.selectFrom("users").select("id").where(...)              │
+│     → Immutable, chainable, fully type-checked                  │
+├─────────────────────────────────────────────────────────────────┤
+│  3. AST                                                         │
+│     .build() → SelectNode (frozen, discriminated union)         │
+│     → ~40 node types, Object.freeze on all outputs              │
+├─────────────────────────────────────────────────────────────────┤
+│  4. PLUGIN / HOOK                                               │
+│     Plugin.transformNode() → Hook "query:before"                │
+│     → AST rewriting, tenant isolation, soft delete, logging     │
+├─────────────────────────────────────────────────────────────────┤
+│  5. PRINTER                                                     │
+│     .toSQL() → { sql: "SELECT ...", params: [...] }             │
+│     → Dialect-specific: PG ($1), MySQL (?), MSSQL (@p0)        │
+└─────────────────────────────────────────────────────────────────┘
 ```
 
-- **Schema Layer** — `defineTable()`, `ColumnType<S,I,U>`, auto type inference
-- **Builder Layer** — `Sumak<DB>`, `TypedSelectBuilder<DB,TB,O>`, proxy-based expressions
-- **AST Layer** — ~35 frozen node types, discriminated unions, visitor pattern
-- **Plugin Layer** — `SumakPlugin` interface, `Hookable` lifecycle hooks
-- **Printer Layer** — `BasePrinter` with 4 dialect subclasses (PG, MySQL, SQLite, MSSQL), Wadler document algebra
+### Why AST-first?
+
+The query is never a string until the very last step. This means:
+
+- **Plugins can rewrite queries** — add WHERE clauses, prefix schemas, transform joins
+- **Hooks can inspect/modify** — logging, tracing, tenant isolation
+- **Printers are swappable** — same AST, different SQL per dialect
+- **No SQL injection** — values are always parameterized
+
+### Key design decisions
+
+- **Params at print time** — no global state, no index tracking during build
+- **Immutable builders** — every method returns a new instance
+- **Proxy-based column access** — `({ age }) => age.gt(18)` with full type safety
+- **Phantom types** — `Expression<T>` carries type info with zero runtime cost
+
+---
+
+## Acknowledgments
+
+sumak wouldn't exist without the incredible work of these projects:
+
+- **[Kysely](https://github.com/kysely-org/kysely)** — Pioneered the AST-first approach for TypeScript query builders. The `DB/TB/O` generic threading pattern, immutable builder design, and visitor-based printer architecture are directly inspired by Kysely.
+- **[Drizzle ORM](https://github.com/drizzle-team/drizzle-orm)** — Proved that schema-as-code (no codegen) is the right developer experience. The `defineTable()` + column builder pattern in sumak follows Drizzle's lead.
+- **[JOOQ](https://github.com/jOOQ/jOOQ)** — The original AST-first SQL builder (Java). Showed that a clean AST layer makes multi-dialect support elegant.
+- **[SQLAlchemy](https://github.com/sqlalchemy/sqlalchemy)** — Demonstrated that separating the expression layer from the ORM layer gives maximum flexibility.
+
+---
 
 ## License