sumak 0.0.5 → 0.0.7

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,216 +81,321 @@ 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").compile(db.printer())
+// SELECT "id", "name" FROM "users"
+
+// Select all columns
+db.selectFrom("users").selectAll().compile(db.printer())
+
+// 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)
+  .offset(20)
+  .compile(db.printer())
+
+// DISTINCT
+db.selectFrom("users").select("name").distinct().compile(db.printer())
+
+// DISTINCT ON (PostgreSQL)
+db.selectFrom("users")
+  .selectAll()
+  .distinctOn("dept")
+  .orderBy("dept")
+  .orderBy("salary", "DESC")
   .compile(db.printer())
 ```
 
-### INSERT
+---
+
+## INSERT
 
 ```ts
+// Single row
+db.insertInto("users").values({ name: "Alice", email: "alice@example.com" }).compile(db.printer())
+
+// Multiple rows
 db.insertInto("users")
-  .values({
-    name: "Alice",
-    email: "alice@example.com",
-  })
+  .valuesMany([
+    { name: "Alice", email: "a@b.com" },
+    { name: "Bob", email: "b@b.com" },
+  ])
+  .compile(db.printer())
+
+// RETURNING
+db.insertInto("users")
+  .values({ name: "Alice", email: "a@b.com" })
   .returningAll()
   .compile(db.printer())
+
+// INSERT ... SELECT
+const source = db.selectFrom("users").select("name", "email").build()
+db.insertInto("archive").fromSelect(source).compile(db.printer())
+
+// DEFAULT VALUES
+db.insertInto("users").defaultValues().compile(db.printer())
+
+// SQLite: INSERT OR IGNORE / INSERT OR REPLACE
+db.insertInto("users").values({ name: "Alice" }).orIgnore().compile(db.printer())
 ```
 
-### UPDATE
+---
+
+## UPDATE
 
 ```ts
+// Basic update
 db.update("users")
   .set({ active: false })
   .where(({ id }) => id.eq(1))
   .compile(db.printer())
-```
 
-### DELETE
+// SET with expression
+db.update("users")
+  .setExpr("name", val("Anonymous"))
+  .where(({ active }) => active.eq(false))
+  .compile(db.printer())
 
-```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())
+
+// UPDATE with JOIN (MySQL)
+db.update("orders").set({ total: 0 }).innerJoin("users", onExpr).compile(db.printer())
+
+// RETURNING
+db.update("users")
+  .set({ active: false })
+  .where(({ id }) => id.eq(1))
+  .returningAll()
+  .compile(db.printer())
+
+// ORDER BY + LIMIT (MySQL)
+db.update("users").set({ active: false }).orderBy("id").limit(lit(10)).compile(db.printer())
 ```
 
-## Joins
+---
+
+## DELETE
 
 ```ts
-// INNER JOIN
-db.selectFrom("users")
-  .innerJoin("posts", ({ users, posts }) => users.id.eqCol(posts.userId))
-  .select("id", "title")
+db.deleteFrom("users")
+  .where(({ id }) => id.eq(1))
   .compile(db.printer())
 
-// LEFT JOIN — joined columns become nullable
-db.selectFrom("users")
-  .leftJoin("posts", ({ users, posts }) => users.id.eqCol(posts.userId))
+// RETURNING
+db.deleteFrom("users")
+  .where(({ id }) => id.eq(1))
+  .returning("id")
   .compile(db.printer())
 
-// RIGHT JOIN
-db.selectFrom("users")
-  .rightJoin("posts", ({ users, posts }) => users.id.eqCol(posts.userId))
-  .compile(db.printer())
+// DELETE ... USING (PostgreSQL)
+db.deleteFrom("orders").using("users").where(onExpr).compile(db.printer())
 
-// FULL JOIN — both sides become nullable
-db.selectFrom("users")
-  .fullJoin("posts", ({ users, posts }) => users.id.eqCol(posts.userId))
+// DELETE with JOIN (MySQL)
+db.deleteFrom("orders")
+  .innerJoin("users", onExpr)
+  .where(({ id }) => id.eq(1))
   .compile(db.printer())
-
-// CROSS JOIN — cartesian product
-db.selectFrom("users").crossJoin("posts").compile(db.printer())
 ```
 
-## Expression API
+---
 
-### Comparisons
+## WHERE Conditions
 
-```ts
-.where(({ id }) =>
-  id.eq(42),
-)
+Every `.where()` takes a callback with typed column proxies.
 
-.where(({ age }) =>
-  age.gt(18),
-)
-
-.where(({ age }) =>
-  age.gte(18),
-)
+### Comparisons
 
-.where(({ age }) =>
-  age.lt(65),
-)
+```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
+```
 
-.where(({ age }) =>
-  age.lte(65),
-)
+### Pattern Matching
 
-.where(({ active }) =>
-  active.neq(false),
-)
+```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
 ```
 
-### String Matching
+### Range & Lists
 
 ```ts
-.where(({ name }) =>
-  name.like("%ali%"),
-)
+.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
 ```
 
-### Range & List
+### Null Checks
 
 ```ts
-.where(({ age }) =>
-  age.between(18, 65),
-)
+.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)),
 )
 
-// OR
+// AND with 3+ conditions
+.where(({ id, age, active }) =>
+  and(id.gt(0), age.gt(18), active.eq(true)),
+)
+
+// 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)))
 ```
 
-### Aggregates
+### Multiple WHERE (implicit AND)
 
 ```ts
-import { count, countDistinct, sum, avg, min, max, coalesce } from "sumak"
+// Calling .where() multiple times ANDs conditions together
+db.selectFrom("users")
+  .select("id")
+  .where(({ age }) => age.gt(18))
+  .where(({ active }) => active.eq(true))
+  .compile(db.printer())
+// WHERE ("age" > $1) AND ("active" = $2)
+```
 
-db.selectFrom("users").selectExpr(count(), "total").compile(db.printer())
+### Column-to-Column Comparisons
 
-db.selectFrom("users").selectExpr(countDistinct(col.dept), "uniqueDepts").compile(db.printer())
-// SELECT COUNT(DISTINCT "dept") AS "uniqueDepts" FROM "users"
+```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"
+```
 
-db.selectFrom("orders").selectExpr(sum(col.amount), "totalAmount").compile(db.printer())
+---
 
-db.selectFrom("orders").selectExpr(avg(col.amount), "avgAmount").compile(db.printer())
+## Joins
 
-db.selectFrom("orders")
-  .selectExpr(coalesce(col.discount, val(0)), "safeDiscount")
+```ts
+// INNER JOIN
+db.selectFrom("users")
+  .innerJoin("posts", ({ users, posts }) => users.id.eqCol(posts.userId))
+  .select("id", "title")
+  .compile(db.printer())
+
+// 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 nullable
+db.selectFrom("users")
+  .fullJoin("posts", ({ users, posts }) => users.id.eqCol(posts.userId))
+  .compile(db.printer())
+
+// CROSS JOIN
+db.selectFrom("users").crossJoin("posts").compile(db.printer())
+
+// LATERAL JOINs (correlated subqueries)
+db.selectFrom("users").innerJoinLateral(subquery, "recent_posts", onExpr).compile(db.printer())
+
+db.selectFrom("users").leftJoinLateral(subquery, "recent_posts", onExpr).compile(db.printer())
+
+db.selectFrom("users").crossJoinLateral(subquery, "latest").compile(db.printer())
 ```
 
-### EXISTS / NOT EXISTS
+---
+
+## Expressions
+
+### Computed Columns
 
 ```ts
-import { exists, notExists } from "sumak"
+import { val, cast, rawExpr } from "sumak"
+
+// Add a computed column with alias
+db.selectFrom("users").selectExpr(val("hello"), "greeting").compile(db.printer())
 
+// Multiple expressions at once
 db.selectFrom("users")
-  .where(() =>
-    exists(
-      db
-        .selectFrom("posts")
-        .where(({ userId }) => userId.eq(1))
-        .build(),
-    ),
-  )
+  .selectExprs({
+    total: count(),
+    greeting: val("hello"),
+  })
   .compile(db.printer())
 
+// CAST
 db.selectFrom("users")
-  .where(() =>
-    notExists(
-      db
-        .selectFrom("posts")
-        .where(({ userId }) => userId.eq(1))
-        .build(),
-    ),
-  )
+  .selectExpr(cast(val(42), "text"), "idAsText")
+  .compile(db.printer())
+```
+
+### Arithmetic
+
+```ts
+import { add, sub, mul, div, mod, neg } from "sumak"
+
+db.selectFrom("orders").selectExpr(mul(col.price, col.qty), "total").compile(db.printer())
+// ("price" * "qty") AS "total"
+
+db.selectFrom("orders")
+  .selectExpr(add(col.price, val(10)), "adjusted")
   .compile(db.printer())
 ```
 
-### CASE Expression
+### CASE / WHEN
 
 ```ts
 import { case_, val } from "sumak"
@@ -269,38 +412,85 @@ db.selectFrom("users")
   .compile(db.printer())
 ```
 
-### 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")
+  .selectExpr(jsonRef(col.meta, "name", "->>"), "metaName")
+  .compile(db.printer())
+
+// JSON_AGG / TO_JSON
+db.selectFrom("users").selectExpr(jsonAgg(col.name), "namesJson").compile(db.printer())
+
+// JSON_BUILD_OBJECT
+db.selectFrom("users")
+  .selectExpr(jsonBuildObject(["name", col.name], ["age", col.age]), "obj")
   .compile(db.printer())
 ```
 
-### JSON Operations
+### PostgreSQL Array Operators
 
 ```ts
-import { jsonRef } from "sumak"
+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 { count, countDistinct, sum, sumDistinct, avg, avgDistinct, min, max, coalesce } from "sumak"
+
+db.selectFrom("users").selectExpr(count(), "total").compile(db.printer())
+db.selectFrom("users").selectExpr(countDistinct(col.dept), "uniqueDepts").compile(db.printer())
+db.selectFrom("orders").selectExpr(sumDistinct(col.amount), "uniqueSum").compile(db.printer())
+db.selectFrom("orders").selectExpr(avg(col.amount), "avgAmount").compile(db.printer())
 
-// ->  (JSON object)
+// COALESCE (variadic)
 db.selectFrom("users")
-  .selectExpr(jsonRef(col.meta, "address", "->"), "address")
+  .selectExpr(coalesce(col.nick, col.name, val("Anonymous")), "displayName")
   .compile(db.printer())
+```
+
+### Aggregate with FILTER (PostgreSQL)
+
+```ts
+import { filter, count } from "sumak"
 
-// ->> (text value)
+db.selectFrom("users").selectExpr(filter(count(), activeExpr), "activeCount").compile(db.printer())
+// 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")
+  .selectExpr(stringAgg(col.name, ", ", [{ expr: col.name, direction: "ASC" }]), "names")
   .compile(db.printer())
+// STRING_AGG("name", ', ' ORDER BY "name" ASC)
+
+// ARRAY_AGG
+db.selectFrom("users").selectExpr(arrayAgg(col.id), "ids").compile(db.printer())
 ```
 
+---
+
 ## 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")),
@@ -308,109 +498,122 @@ db.selectFrom("employees")
   )
   .compile(db.printer())
 
-// 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"
+import { now, currentTimestamp } from "sumak"
 
-db.selectFrom("orders").selectExpr(abs(col.balance), "absBalance").compile(db.printer())
+now() // NOW()
+currentTimestamp() // CURRENT_TIMESTAMP()
+```
 
-db.selectFrom("orders").selectExpr(round(col.price, 2), "rounded").compile(db.printer())
+---
 
-db.selectFrom("orders").selectExpr(ceil(col.amount), "ceiling").compile(db.printer())
+## Subqueries
 
-db.selectFrom("orders").selectExpr(floor(col.amount), "floored").compile(db.printer())
-```
-
-### 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")
+  .where(() =>
+    exists(
+      db
+        .selectFrom("posts")
+        .where(({ userId }) => userId.eq(1))
+        .build(),
+    ),
+  )
   .compile(db.printer())
+```
 
-db.selectFrom("products")
-  .selectExpr(greatest(col.price, col.minPrice), "effectivePrice")
-  .compile(db.printer())
+### Derived Tables (Subquery in FROM)
 
-db.selectFrom("products")
-  .selectExpr(least(col.price, col.maxPrice), "cappedPrice")
-  .compile(db.printer())
+```ts
+const sub = db
+  .selectFrom("users")
+  .select("id", "name")
+  .where(({ age }) => age.gt(18))
+
+db.selectFromSubquery(sub, "adults").selectAll().compile(db.printer())
+// 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))
+  .compile(db.printer())
 ```
 
+---
+
 ## Set Operations
 
 ```ts
@@ -418,72 +621,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).compile(db.printer()) // UNION
+active.unionAll(premium).compile(db.printer()) // UNION ALL
+active.intersect(premium).compile(db.printer()) // INTERSECT
+active.intersectAll(premium).compile(db.printer()) // INTERSECT ALL
+active.except(premium).compile(db.printer()) // EXCEPT
+active.exceptAll(premium).compile(db.printer()) // 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).compile(db.printer())
 
 // Recursive CTE
-db.selectFrom("users").with("tree", recursiveQuery, true).compile(db.printer())
+db.selectFrom("categories").with("tree", recursiveQuery, true).compile(db.printer())
 ```
 
-## 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
@@ -495,55 +666,105 @@ db.selectFrom("users")
   .$if(withOrder, (qb) => qb.orderBy("name"))
   .compile(db.printer())
 // WHERE applied, ORDER BY skipped
+```
+
+### `$call()` — reusable query fragments
 
-// Multiple .where() calls are AND'd together
+```ts
+const withPagination = (qb) => qb.limit(10).offset(20)
+const onlyActive = (qb) => qb.where(({ active }) => active.eq(true))
+
+db.selectFrom("users")
+  .select("id", "name")
+  .$call(onlyActive)
+  .$call(withPagination)
+  .compile(db.printer())
+```
+
+### `clear*()` — reset clauses
+
+```ts
 db.selectFrom("users")
   .select("id")
-  .where(({ age }) => age.gt(18))
-  .where(({ active }) => active.eq(true))
+  .orderBy("name")
+  .clearOrderBy() // removes ORDER BY
+  .orderBy("id", "DESC") // re-add different order
   .compile(db.printer())
-// WHERE ("age" > $1) AND ("active" = $2)
 ```
 
-## INSERT Advanced
+Available: `clearWhere()`, `clearOrderBy()`, `clearLimit()`, `clearOffset()`, `clearGroupBy()`, `clearHaving()`, `clearSelect()`.
+
+---
+
+## Raw SQL
+
+### `sql` tagged template
 
 ```ts
-// INSERT ... SELECT
-const selectQuery = db.selectFrom("users").select("name", "age").build()
-db.insertInto("archive").fromSelect(selectQuery).compile(db.printer())
+import { sql } from "sumak"
 
-// INSERT ... DEFAULT VALUES
-db.insertInto("users").defaultValues().compile(db.printer())
+// Primitives are parameterized
+sql`SELECT * FROM users WHERE name = ${"Alice"}`
+// params: ["Alice"]
 
-// SQLite: INSERT OR IGNORE / INSERT OR REPLACE
-db.insertInto("users").values({ name: "Alice" }).orIgnore().compile(db.printer())
-// INSERT OR IGNORE INTO "users" ...
+// 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"
 
-db.insertInto("users").values({ name: "Alice" }).orReplace().compile(db.printer())
-// INSERT OR REPLACE INTO "users" ...
+// In queries
+db.selectFrom("users")
+  .selectExpr(sql`CURRENT_DATE`, "today")
+  .compile(db.printer())
 ```
 
-## ON CONFLICT
+### `rawExpr()` escape hatch
 
 ```ts
-// DO NOTHING (by columns)
+import { rawExpr } from "sumak"
+
+// In WHERE
+db.selectFrom("users")
+  .where(() => rawExpr<boolean>("age > 18"))
+  .compile(db.printer())
+
+// In SELECT
+db.selectFrom("users")
+  .selectExpr(rawExpr<number>("EXTRACT(YEAR FROM created_at)"), "year")
+  .compile(db.printer())
+```
+
+---
+
+## ON CONFLICT / Upsert
+
+```ts
+// PostgreSQL: ON CONFLICT DO NOTHING
 db.insertInto("users")
   .values({ name: "Alice", email: "a@b.com" })
   .onConflictDoNothing("email")
   .compile(db.printer())
 
-// 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("Updated") }])
+  .compile(db.printer())
+
+// ON CONFLICT DO UPDATE (with plain object — auto-parameterized)
 db.insertInto("users")
   .values({ name: "Alice", email: "a@b.com" })
-  .onConflictDoUpdate(["email"], [{ column: "name", value: val("Alice") }])
+  .onConflictDoUpdateSet(["email"], { name: "Alice Updated" })
   .compile(db.printer())
 
-// DO NOTHING (by constraint name)
+// 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
 
 // MySQL: ON DUPLICATE KEY UPDATE
 db.insertInto("users")
@@ -552,217 +773,239 @@ db.insertInto("users")
   .compile(db.printer())
 ```
 
+---
+
 ## 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",
-  })
+  .whenNotMatchedThenInsert({ name: "Alice", email: "a@b.com" })
   .compile(db.printer())
 
-// MERGE with conditional delete
+// Conditional delete
 db.mergeInto("users", "staging", "s", ({ target, source }) => target.id.eqCol(source.id))
   .whenMatchedThenDelete()
   .compile(db.printer())
 ```
 
+---
+
 ## Row Locking
 
 ```ts
-// FOR UPDATE
-db.selectFrom("users").select("id").forUpdate().compile(db.printer())
+db.selectFrom("users").select("id").forUpdate().compile(db.printer()) // FOR UPDATE
+db.selectFrom("users").select("id").forShare().compile(db.printer()) // FOR SHARE
+db.selectFrom("users").select("id").forNoKeyUpdate().compile(db.printer()) // FOR NO KEY UPDATE (PG)
+db.selectFrom("users").select("id").forKeyShare().compile(db.printer()) // FOR KEY SHARE (PG)
+
+// Modifiers
+db.selectFrom("users").select("id").forUpdate().skipLocked().compile(db.printer()) // SKIP LOCKED
+db.selectFrom("users").select("id").forUpdate().noWait().compile(db.printer()) // NOWAIT
+```
 
-// 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())
+## EXPLAIN
+
+```ts
+db.selectFrom("users").select("id").explain().compile(db.printer())
+// EXPLAIN SELECT "id" FROM "users"
+
+db.selectFrom("users").select("id").explain({ analyze: true }).compile(db.printer())
+// EXPLAIN ANALYZE SELECT ...
 
-// 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").explain({ format: "JSON" }).compile(db.printer())
+// EXPLAIN (FORMAT JSON) SELECT ...
 ```
 
-## DISTINCT ON (PG)
+---
+
+## Schema Builder (DDL)
+
+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.
+
+### CREATE TABLE
 
 ```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
+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()
 ```
 
-## DELETE USING / JOIN in UPDATE & DELETE
+### ALTER TABLE
 
 ```ts
-// PG: DELETE ... USING
-db.deleteFrom("orders")
-  .using("users")
-  .where(eq(col("orders.user_id"), col("users.id")))
-  .compile(db.printer())
+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()
+```
 
-// 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())
+### CREATE INDEX
 
-// MySQL: UPDATE with JOIN
-db.update("orders")
-  .set({ total: 0 })
-  .innerJoin("users", eq(col("user_id", "orders"), col("id", "users")))
-  .compile(db.printer())
+```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()
 ```
 
-## Aggregate FILTER (WHERE)
+### CREATE VIEW
 
 ```ts
-import { filter, count, sum } from "sumak"
+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()
+```
 
-// COUNT(*) FILTER (WHERE active = true)
-db.selectFrom("users").selectExpr(filter(count(), activeExpr), "activeCount").compile(db.printer())
+### DROP
+
+```ts
+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())
-
 // 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"),
-  })
+  .forSystemTime({ kind: "as_of", timestamp: lit("2024-01-01") })
   .compile(db.printer())
 
-// BETWEEN — time range
+// Time range
 db.selectFrom("users")
-  .forSystemTime({
-    kind: "between",
-    start: lit("2024-01-01"),
-    end: lit("2024-12-31"),
-  })
+  .forSystemTime({ kind: "between", start: lit("2024-01-01"), end: lit("2024-12-31") })
   .compile(db.printer())
 
-// ALL — full history
+// Full history
 db.selectFrom("users").forSystemTime({ kind: "all" }).compile(db.printer())
 ```
 
-Supported modes: `as_of`, `from_to`, `between`, `contained_in`, `all`.
-
-## Tree Shaking
+Modes: `as_of`, `from_to`, `between`, `contained_in`, `all`.
 
-Import only the dialect you need:
-
-```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)
-```
-
-### 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)
-
-// 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
@@ -771,14 +1014,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.
@@ -794,29 +1029,72 @@ const off = db.hook("query:before", handler)
 off()
 ```
 
-## Why sumak?
+---
 
-|                    | 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   |
+## Dialects
+
+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
 
 ```
-Schema → Builder → AST → Plugin/Hook → Printer → SQL
+User Code
+  │
+  ├── sumak({ dialect, tables })      ← DB type inferred
+  │
+  ├── db.selectFrom("users")          ← TypedSelectBuilder<DB, "users", O>
+  │     .select("id", "name")         ← O narrows to Pick<O, "id"|"name">
+  │     .where(({ age }) => age.gt(18))
+  │     .build()                       ← SelectNode (frozen AST)
+  │
+  ├── db.compile(node)                ← Plugin → Hooks → Printer
+  │
+  └── { sql, params }                ← Parameterized output
 ```
 
-- **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
+**5 layers:**
+
+- **Schema** — `defineTable()`, `ColumnType<S,I,U>`, auto type inference
+- **Builder** — `TypedSelectBuilder<DB,TB,O>`, proxy-based expressions
+- **AST** — Frozen node types, discriminated unions, visitor pattern
+- **Plugin/Hook** — `SumakPlugin`, `Hookable` lifecycle hooks
+- **Printer** — `BasePrinter` + 4 dialect subclasses, Wadler document algebra
+
+|                    | 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   |
+| **DDL support**    | Full (schema builder) | drizzle-kit | Full           |
+| **Dependencies**   | 0                     | 0           | 0              |
+
+---
 
 ## License