effect-qb 0.12.3 → 0.13.0

package/README.md

@@ -2,12 +2,66 @@
 
 Type-safe SQL query construction for PostgreSQL and MySQL, with query plans that carry result shapes, nullability, dialect compatibility, and statement constraints in the type system.
 
+## Overview
+
+`effect-qb` builds immutable query plans and pushes the interesting parts of SQL into the type system:
+
+- exact projection shapes
+- nullability and predicate-driven narrowing
+- join optionality
+- aggregate and grouping validation
+- dialect compatibility
+- statement and execution result types
+
+The main contract is compile-time. `Query.ResultRow<typeof plan>` is the logical row type after query analysis, while `Query.RuntimeResultRow<typeof plan>` describes the conservative runtime remap shape. At runtime, the library renders SQL, executes it, normalizes raw driver values, applies schema-backed transforms where they exist, and remaps aliased columns back into nested objects.
+
+## Why effect-qb
+
+Use `effect-qb` when you want SQL plans to carry more than column names:
+
+- exact nested projection shapes
+- nullability refinement from predicates
+- join optionality that changes with query structure
+- grouped-query validation before SQL is rendered
+- dialect-locked plans, renderers, and executor error channels
+
+It is a query-construction library, not an ORM. It does not manage migrations, model identities, or runtime row decoding.
+
+## Installation
+
+If you only want the typed DSL and SQL rendering:
+
+```bash
+bun add effect-qb
+npm install effect-qb
+```
+
+If you want to execute plans with the built-in Postgres executor:
+
+```bash
+bun add effect-qb effect @effect/sql @effect/sql-pg
+npm install effect-qb effect @effect/sql @effect/sql-pg
+```
+
+If you want to execute plans with the built-in MySQL executor:
+
+```bash
+bun add effect-qb effect @effect/sql @effect/sql-mysql2
+npm install effect-qb effect @effect/sql @effect/sql-mysql2
+```
+
+The built-in executors require an ambient `@effect/sql` `SqlClient`. If your app already uses Effect and `@effect/sql`, you likely already have the extra runtime packages installed.
+
+For local development in this repository:
+
+```bash
+bun install
+```
+
 ## Table of Contents
 
-- [Overview](#overview)
-- [Why effect-qb](#why-effect-qb)
-- [Installation](#installation)
 - [Choose An Entrypoint](#choose-an-entrypoint)
+- [Postgres Function](#postgres-function)
 - [Quick Start](#quick-start)
 - [Execution Model](#execution-model)
 - [Feature Map](#feature-map)
@@ -57,63 +111,53 @@ Type-safe SQL query construction for PostgreSQL and MySQL, with query plans that
 - [Limitations](#limitations)
 - [Contributing](#contributing)
 
-## Overview
-
-`effect-qb` builds immutable query plans and pushes the interesting parts of SQL into the type system:
-
-- exact projection shapes
-- nullability and predicate-driven narrowing
-- join optionality
-- aggregate and grouping validation
-- dialect compatibility
-- statement and execution result types
+## Choose An Entrypoint
 
-The main contract is compile-time. `Query.ResultRow<typeof plan>` is the logical row type after query analysis, while `Query.RuntimeResultRow<typeof plan>` describes the conservative runtime remap shape. At runtime, the library renders SQL, executes it, and remaps aliased columns back into nested objects. It does not build or validate query-result schemas.
+Available entrypoints:
 
-## Why effect-qb
+- `effect-qb/postgres`
+- `effect-qb/mysql`
 
-Use `effect-qb` when you want SQL plans to carry more than column names:
+Use `effect-qb/postgres` when you want explicit Postgres branding throughout the plan, renderer, executor, datatypes, and errors.
 
-- exact nested projection shapes
-- nullability refinement from predicates
-- join optionality that changes with query structure
-- grouped-query validation before SQL is rendered
-- dialect-locked plans, renderers, and executor error channels
+That entrypoint also exposes `Postgres.Function` for typed SQL functions and JSON helpers.
 
-It is a query-construction library, not an ORM. It does not manage migrations, model identities, or runtime row decoding.
+Use `effect-qb/mysql` when you want the MySQL-specific DSL, renderer, executor, datatypes, and errors. It also exposes `Mysql.Function` for typed SQL functions and JSON helpers.
 
-## Installation
+## Postgres Function
 
-Install the library:
+`effect-qb/postgres` exposes `Postgres.Function` for typed SQL expressions. The helpers are expressions, so they compose like other query values and keep their result types.
 
-```bash
-bun add effect-qb
-```
+```ts
+import { Column as C, Function as F, Query as Q, Table } from "effect-qb/postgres"
 
-For local development in this repository:
+const users = Table.make("users", {
+  id: C.uuid().pipe(C.primaryKey),
+  email: C.text(),
+  bio: C.text().pipe(C.nullable)
+})
 
-```bash
-bun install
+const userSummary = Q.select({
+  email: F.lower(users.email),
+  bio: F.coalesce(users.bio, "anonymous"),
+  seenAt: F.currentTimestamp()
+}).pipe(
+  Q.from(users)
+)
 ```
 
-## Choose An Entrypoint
-
-Available entrypoints:
-
-- `effect-qb`
-- `effect-qb/postgres`
-- `effect-qb/mysql`
-
-Use `effect-qb` when Postgres defaults are acceptable and you want the shortest imports.
+`Postgres.Function` currently covers:
 
-Use `effect-qb/postgres` when you want explicit Postgres branding throughout the plan, renderer, executor, datatypes, and errors.
-
-Use `effect-qb/mysql` when you want the MySQL-specific DSL, renderer, executor, datatypes, and errors.
+- scalar helpers like `coalesce`, `lower`, `upper`, and `concat`
+- aggregate helpers like `count`, `max`, and `min`
+- window helpers like `over`, `rowNumber`, `rank`, and `denseRank`
+- temporal helpers like `now`, `currentDate`, `currentTime`, `currentTimestamp`, `localTime`, and `localTimestamp`
+- JSON helpers via `Function.json`
 
 ## Quick Start
 
 ```ts
-import { Column as C, Query as Q, Renderer, Table } from "effect-qb"
+import { Column as C, Function as F, Query as Q, Renderer, Table } from "effect-qb/postgres"
 
 const users = Table.make("users", {
   id: C.uuid().pipe(C.primaryKey),
@@ -129,7 +173,7 @@ const posts = Table.make("posts", {
 const postsPerUser = Q.select({
   userId: users.id,
   email: users.email,
-  postCount: Q.count(posts.id)
+  postCount: F.count(posts.id)
 }).pipe(
   Q.from(users),
   Q.leftJoin(posts, Q.eq(users.id, posts.userId)),
@@ -157,18 +201,18 @@ The runtime model is intentionally small:
 
 1. build a typed plan
 2. render SQL plus bind params
-3. execute the statement
-4. remap flat aliases like `profile__email` back into nested objects
+3. normalize raw driver values into canonical `effect-qb` runtime values
+4. apply propagated runtime schemas where they exist
+5. remap flat aliases like `profile__email` back into nested objects
 
-What it does not do is decode rows against a runtime schema. `Q.ResultRow<typeof plan>` is the logical static result, while `Q.RuntimeResultRow<typeof plan>` is the conservative runtime shape.
+For the logical/static row split, see `ResultRow vs RuntimeResultRow` below.
 
 ```ts
 import * as SqlClient from "@effect/sql/SqlClient"
 import * as Effect from "effect/Effect"
-import * as Postgres from "effect-qb/postgres"
+import { Executor as PostgresExecutor } from "effect-qb/postgres"
 
-const renderer = Postgres.Renderer.make()
-const executor = Postgres.Executor.fromSqlClient(renderer)
+const executor = PostgresExecutor.make()
 
 const rowsEffect = executor.execute(postsPerUser)
 
@@ -177,7 +221,7 @@ const rows = Effect.runSync(
 )
 ```
 
-If you want runtime validation, add it after execution.
+Schema-backed columns and preserved projections can enforce runtime transforms during execution. Arbitrary query plans still do not become one big derived query schema automatically.
 
 ## Feature Map
 
@@ -186,6 +230,7 @@ The rest of this README goes deeper, but the main surface area is:
 - table builders with keys, indexes, nullability, defaults, and schema-backed JSON columns
 - select plans with joins, CTEs, derived tables, `values(...)`, `unnest(...)`, subqueries, and set operators
 - mutation plans for `insert`, `update`, `delete`, `returning`, and conflict handling
+- typed SQL functions via `Postgres.Function` and `Mysql.Function`
 - renderers and executors for Postgres and MySQL
 - type-level checks for missing sources, grouped selections, dialect compatibility, and JSON mutation compatibility
 
@@ -193,65 +238,92 @@ Dialect-specific capabilities are called out later. Postgres currently has the w
 
 ## Effect Schema Integration
 
-`effect-qb` is tightly integrated with `effect/Schema`.
+`effect-qb` uses `effect/Schema` as the runtime contract for columns and tables.
 
 That integration shows up in three places:
 
-- built-in columns are backed by Effect Schema primitives like `Schema.String`, `Schema.UUID`, and `Schema.Date`
-- custom and JSON columns can be defined directly from your own Effect Schemas
-- every table derives runtime `select`, `insert`, and `update` schemas from its column definitions
+- column definitions carry runtime schemas
+- tables derive `select`, `insert`, and `update` schemas from those columns
+- built-in executors apply schema-backed transforms when selected projections carry a runtime schema
 
-There is no separate `C.schema(...)` helper. The schema-backed entrypoints are:
+The schema-aware column APIs are:
 
+- built-in columns like `C.uuid()`, `C.text()`, `C.number()`, `C.date()`, and `C.timestamp()`
+- `C.schema(schema)` to replace a column's runtime schema without changing its SQL type or key/default metadata
 - `C.custom(schema, dbType)` for arbitrary non-JSON columns
 - `C.json(schema)` for JSON columns
-- `column.schema` when you need the underlying Effect Schema attached to a column definition
 
-This means the same table definition drives:
+### Defaults And Generated Columns
+
+`C.default(expr)` and `C.generated(expr)` only affect write-shape:
+
+- `C.default(expr)` keeps a column selectable and updatable, but optional on insert because the database may fill it
+- `C.generated(expr)` omits a column from insert and update because the database owns the value
+- both helpers keep the expression around for DDL rendering
 
-- SQL construction
-- static TypeScript row and payload types
-- runtime validation for table-shaped inputs
+The important rule for `C.schema(...)` is that the schema must accept the column's current runtime output, not the raw driver value.
+
+- `C.date()` produces a canonical `LocalDateString`, so `C.date().pipe(C.schema(Schema.DateFromString))` is valid
+- `C.int().pipe(C.schema(Schema.DateFromString))` is rejected because the column runtime type is `number`, not `string`
 
 Example:
 
 ```ts
 import * as Schema from "effect/Schema"
-import { Column as C, Table } from "effect-qb"
+import { Column as C, Executor, Function as F, Query as Q, Table } from "effect-qb/postgres"
 
-const UserProfile = Schema.Struct({
-  displayName: Schema.String,
-  bio: Schema.NullOr(Schema.String)
+const users = Table.make("users", {
+  id: C.uuid().pipe(C.primaryKey, C.generated(Q.literal("generated-user-id"))),
+  happenedOn: C.date().pipe(C.schema(Schema.DateFromString)),
+  profile: C.json(Schema.Struct({
+    visits: Schema.NumberFromString
+  })),
+  createdAt: C.timestamp().pipe(C.default(F.localTimestamp()))
 })
 
-const users = Table.make("users", {
-  id: C.uuid().pipe(C.primaryKey, C.generated),
-  email: C.text(),
-  profile: C.json(UserProfile),
-  createdAt: C.timestamp().pipe(C.hasDefault),
-  status: C.custom(
-    Schema.Literal("active", "disabled"),
-    { dialect: "postgres", kind: "text" } as const
-  )
+type UserSelect = Table.SelectOf<typeof users>
+type UserInsert = Table.InsertOf<typeof users>
+type UserUpdate = Table.UpdateOf<typeof users>
+
+const decoded = Schema.decodeUnknownSync(users.schemas.select)({
+  id: "11111111-1111-1111-1111-111111111111",
+  happenedOn: "2026-03-20",
+  profile: {
+    visits: "42"
+  },
+  createdAt: "2026-03-20T10:00:00"
 })
+
+decoded.happenedOn
+// Date
+
+decoded.profile.visits
+// number
+
+const plan = Q.select({
+  happenedOn: users.happenedOn,
+  profile: users.profile
+}).pipe(
+  Q.from(users)
+)
+
+const rowsEffect = Executor.make().execute(plan)
 ```
 
 From that one definition you get:
 
-- bound SQL columns like `users.email`
-- a schema for reading table rows: `users.schemas.select`
-- a schema for inserts that respects generated/default/nullable columns: `users.schemas.insert`
-- a schema for updates that excludes primary keys and generated columns: `users.schemas.update`
+- bound SQL columns like `users.profile`
+- derived table schemas: `users.schemas.select`, `users.schemas.insert`, `users.schemas.update`
+- static helper types that line up with those schemas
+- executor-side transforms for schema-backed projections
 
-The helper types line up with those schemas:
+That last point matters. Built-in executors do not just remap aliases. They first normalize raw driver values into canonical `effect-qb` runtime values, then apply propagated schemas where they exist. So a selected `users.happenedOn` can become a `Date`, and a selected `users.profile` can decode `"42"` into `42` via `Schema.NumberFromString`.
 
-```ts
-type UserSelect = Table.SelectOf<typeof users>
-type UserInsert = Table.InsertOf<typeof users>
-type UserUpdate = Table.UpdateOf<typeof users>
-```
+The boundary is still important:
 
-One important boundary: table schemas are runtime schemas for table-shaped data, while query plans remain schema-free at execution time. `effect-qb` derives and exposes Effect Schemas for tables and JSON columns, but `executor.execute(plan)` still remaps rows without decoding arbitrary query results through `effect/Schema`.
+- table schemas are full `effect/Schema` values for table-shaped data
+- schema-backed columns and preserved projections can enforce runtime transforms on reads
+- arbitrary query plans do not automatically become one big derived query schema
 
 ## Core Concepts
 
@@ -263,10 +335,10 @@ Every table exposes derived Effect Schemas:
 import * as Schema from "effect/Schema"
 
 const users = Table.make("users", {
-  id: C.uuid().pipe(C.primaryKey, C.generated),
+  id: C.uuid().pipe(C.primaryKey, C.generated(Q.literal("generated-user-id"))),
   email: C.text().pipe(C.unique),
   bio: C.text().pipe(C.nullable),
-  createdAt: C.timestamp().pipe(C.hasDefault)
+  createdAt: C.timestamp().pipe(C.default(F.localTimestamp()))
 })
 
 Schema.isSchema(users.schemas.select)
@@ -288,7 +360,7 @@ Tables are typed sources, not loose name strings. Columns carry DB types, nullab
 
 ```ts
 import * as Schema from "effect/Schema"
-import { Column as C, Table } from "effect-qb"
+import { Column as C, Table } from "effect-qb/postgres"
 
 const users = Table.make("users", {
   id: C.uuid().pipe(C.primaryKey),
@@ -311,6 +383,41 @@ const events = analytics.table("events", {
 })
 ```
 
+### Table Options
+
+Table-level options live on the table definition itself. They are pipeable and render into DDL:
+
+- `Table.primaryKey(...)` for table-level composite keys
+- `Table.unique(...)` for table-level unique constraints
+- `Table.index(...)` for table-level indexes
+- `Table.foreignKey(...)` for table-level foreign keys
+- `Table.check(...)` for expression-only check constraints
+
+```ts
+import { Column as C, Query as Q, Table } from "effect-qb/postgres"
+
+const orgs = Table.make("orgs", {
+  id: C.uuid().pipe(C.primaryKey),
+  slug: C.text().pipe(C.unique)
+})
+
+const membershipsBase = Table.make("memberships", {
+  id: C.uuid().pipe(C.primaryKey),
+  orgId: C.uuid(),
+  role: C.text(),
+  note: C.text().pipe(C.nullable)
+})
+
+const memberships = membershipsBase.pipe(
+  Table.foreignKey("orgId", () => orgs, "id"),
+  Table.unique(["orgId", "role"] as const),
+  Table.index(["role", "orgId"] as const),
+  Table.check("role_not_empty", Q.neq(membershipsBase.role, Q.literal("")))
+)
+```
+
+The `check` helper must receive an expression. Raw SQL strings are not accepted.
+
 ### Plans, Not Strings
 
 `effect-qb` does not build rows from ad hoc string fragments. It builds typed plans. Partial plans are allowed while assembling a query, but rendering and execution require a complete plan.
@@ -378,13 +485,13 @@ const docs = Table.make("docs", {
   }))
 })
 
-const cityPath = Q.json.path(
-  Q.json.key("profile"),
-  Q.json.key("address"),
-  Q.json.key("city")
+const cityPath = F.json.path(
+  F.json.key("profile"),
+  F.json.key("address"),
+  F.json.key("city")
 )
 
-const city = Q.json.get(docs.payload, cityPath)
+const city = F.json.get(docs.payload, cityPath)
 type City = Q.OutputOfExpression<typeof city, {
   readonly docs: {
     readonly name: "docs"
@@ -396,17 +503,11 @@ type City = Q.OutputOfExpression<typeof city, {
 
 ### Dialect-specific Entrypoints
 
-The root entrypoint defaults to the Postgres-flavored `Query` and `Table` DSLs:
-
-```ts
-import { Query as Q, Table } from "effect-qb"
-```
-
 Dialect entrypoints expose dialect-specific builders:
 
 ```ts
-import * as Postgres from "effect-qb/postgres"
-import * as Mysql from "effect-qb/mysql"
+import { Query as PostgresQuery } from "effect-qb/postgres"
+import { Query as MysqlQuery } from "effect-qb/mysql"
 ```
 
 This matters for:
@@ -450,16 +551,14 @@ Projection typing is local. You usually do not need to define row interfaces you
 `from(...)` and joins make referenced sources available to the plan. Derived tables, CTEs, and correlated sources stay typed.
 
 ```ts
-const activePosts = Q.as(
-  Q.select({
+const activePosts = Q.select({
     userId: posts.userId,
     title: posts.title
   }).pipe(
     Q.from(posts),
-    Q.where(Q.isNotNull(posts.title))
-  ),
-  "active_posts"
-)
+    Q.where(Q.isNotNull(posts.title)),
+    Q.as("active_posts")
+  )
 
 const usersWithPosts = Q.select({
   userId: users.id,
@@ -478,9 +577,9 @@ type UsersWithPostsRow = Q.ResultRow<typeof usersWithPosts>
 
 The same source story applies to:
 
-- `Q.with(subquery, alias)`
-- `Q.withRecursive(subquery, alias)`
-- `Q.lateral(subquery, alias)`
+- `subquery.pipe(Q.with("alias"))`
+- `subquery.pipe(Q.withRecursive("alias"))`
+- `subquery.pipe(Q.lateral("alias"))`
 - `Q.values(...)`
 - `Q.unnest(...)`
 
@@ -491,7 +590,7 @@ Predicates do more than render SQL. They can narrow result types.
 ```ts
 const allPosts = Q.select({
   title: posts.title,
-  upperTitle: Q.upper(posts.title)
+  upperTitle: F.upper(posts.title)
 }).pipe(
   Q.from(posts)
 )
@@ -504,7 +603,7 @@ type AllPostsRow = Q.ResultRow<typeof allPosts>
 
 const titledPosts = Q.select({
   title: posts.title,
-  upperTitle: Q.upper(posts.title)
+  upperTitle: F.upper(posts.title)
 }).pipe(
   Q.from(posts),
   Q.where(Q.isNotNull(posts.title))
@@ -530,6 +629,7 @@ The expression surface is large, but the important point is that result-shaping
 
 ```ts
 import * as Schema from "effect/Schema"
+import { Column as C, Function as F, Query as Q, Table } from "effect-qb/postgres"
 
 const docs = Table.make("docs", {
   id: C.uuid().pipe(C.primaryKey),
@@ -542,17 +642,17 @@ const docs = Table.make("docs", {
   }))
 })
 
-const cityPath = Q.json.path(
-  Q.json.key("profile"),
-  Q.json.key("address"),
-  Q.json.key("city")
+const cityPath = F.json.path(
+  F.json.key("profile"),
+  F.json.key("address"),
+  F.json.key("city")
 )
 
 const shapedDocs = Q.select({
   title: Q.case()
     .when(Q.isNull(posts.title), "missing")
-    .else(Q.upper(posts.title)),
-  profileCity: Q.json.text(docs.payload, cityPath),
+    .else(F.upper(posts.title)),
+  profileCity: F.json.text(docs.payload, cityPath),
   titleAsText: Q.cast(posts.title, Q.type.text())
 }).pipe(
   Q.from(posts),
@@ -562,12 +662,12 @@ const shapedDocs = Q.select({
 
 The same JSON path object can be reused across:
 
-- `Q.json.get(...)`
-- `Q.json.text(...)`
-- `Q.json.set(...)`
-- `Q.json.insert(...)`
-- `Q.json.delete(...)`
-- `Q.json.pathExists(...)`
+- `Function.json.get(...)`
+- `Function.json.text(...)`
+- `Function.json.set(...)`
+- `Function.json.insert(...)`
+- `Function.json.delete(...)`
+- `Function.json.pathExists(...)`
 
 Comparison and cast safety are dialect-aware. Incompatible operands are rejected unless you make the conversion explicit with `Q.cast(...)`.
 
@@ -576,13 +676,26 @@ Comparison and cast safety are dialect-aware. Incompatible operands are rejected
 Grouped queries are checked structurally, not just by source provenance.
 
 ```ts
+const invalidPostsPerUser = Q.select({
+  userId: users.id,
+  title: posts.title,
+  postCount: F.count(posts.id)
+}).pipe(
+  Q.from(users),
+  Q.leftJoin(posts, Q.eq(users.id, posts.userId)),
+  Q.groupBy(users.id)
+)
+
+type InvalidPostsPerUser = Q.CompletePlan<typeof invalidPostsPerUser>
+// {
+//   __effect_qb_error__: "effect-qb: invalid grouped selection"
+//   __effect_qb_hint__:
+//     "Scalar selections must be covered by groupBy(...) when aggregates are present"
+// }
+
 const postsPerUser = Q.select({
   userId: users.id,
-  postCount: Q.count(posts.id),
-  rowNumber: Q.over(Q.rowNumber(), {
-    partitionBy: [users.id],
-    orderBy: [{ value: users.id, direction: "asc" }]
-  })
+  postCount: F.count(posts.id)
 }).pipe(
   Q.from(users),
   Q.leftJoin(posts, Q.eq(users.id, posts.userId)),
@@ -593,11 +706,10 @@ type PostsPerUserRow = Q.ResultRow<typeof postsPerUser>
 // {
 //   userId: string
 //   postCount: number
-//   rowNumber: number
 // }
 ```
 
-Scalar selections must be covered by `groupBy(...)` when aggregates are present. Invalid grouped selections are rejected at the complete-plan boundary.
+This catches invalid grouped queries before rendering, then the fixed plan keeps only grouped or aggregate selections.
 
 ### Combining Queries
 
@@ -654,15 +766,15 @@ const recentUsers = Q.select({
 Postgres-only `distinct on` is available from the Postgres entrypoint:
 
 ```ts
-import * as Postgres from "effect-qb/postgres"
+import { Query as Q } from "effect-qb/postgres"
 
-const recentEmails = Postgres.Query.select({
+const recentEmails = Q.select({
   id: users.id,
   email: users.email
 }).pipe(
-  Postgres.Query.from(users),
-  Postgres.Query.distinctOn(users.email),
-  Postgres.Query.orderBy(users.email)
+  Q.from(users),
+  Q.distinctOn(users.email),
+  Q.orderBy(users.email)
 )
 ```
 
@@ -679,28 +791,38 @@ const insertUser = Q.insert(users, {
 })
 ```
 
+If every writable column is optional because of `C.default(...)`, `C.generated(...)`, or nullability, `Q.insert(table)` is the default-only form.
+
 Composable sources are available when the input rows come from elsewhere:
 
 ```ts
 const pendingUsers = Q.values([
   { id: "user-1", email: "alice@example.com" },
   { id: "user-2", email: "bob@example.com" }
-], "pending_users")
+]).pipe(
+  Q.as("pending_users")
+)
 
-const insertMany = Q.insertFrom(users, pendingUsers)
+const insertMany = Q.insert(users).pipe(
+  Q.from(pendingUsers)
+)
 ```
 
-`insertFrom(...)` also accepts `select(...)`, `unnest(...)`, and other compatible sources.
+`from(...)` also accepts `select(...)`, `unnest(...)`, and other compatible sources.
 
 ### Update
 
-Updates stay expression-aware and can use joined sources where the dialect supports it.
+Updates stay expression-aware and can use `from(...)` sources where the dialect supports it.
 
 ```ts
-const updateUsers = Q.innerJoin(posts, Q.eq(posts.userId, users.id))(
-  Q.update(users, {
-    email: "has-posts@example.com"
-  })
+const updateUsers = Q.update(users, {
+  email: "author@example.com"
+}).pipe(
+  Q.from(posts),
+  Q.where(Q.and(
+    Q.eq(posts.userId, users.id),
+    Q.eq(posts.title, "hello")
+  ))
 )
 ```
 
@@ -721,19 +843,25 @@ const deleteUser = Q.delete(users).pipe(
 Conflict handling is modeled as a composable modifier instead of a string escape hatch.
 
 ```ts
-const insertOrIgnore = Q.onConflict(["id"] as const, {
-  action: "doNothing"
-})(Q.insert(users, {
+const insertOrIgnore = Q.insert(users, {
   id: "user-1",
   email: "alice@example.com"
-}))
+}).pipe(
+  Q.onConflict(["id"] as const, {
+    action: "doNothing"
+  })
+)
 
-const upsertUser = Q.upsert(users, {
+const upsertUser = Q.insert(users, {
   id: "user-1",
   email: "alice@example.com"
-}, ["id"] as const, {
-  email: "alice@example.com"
-})
+}).pipe(
+  Q.onConflict(["id"] as const, {
+    update: {
+      email: Q.excluded(users.email)
+    }
+  })
+)
 ```
 
 Conflict targets are checked against the target table.
@@ -743,13 +871,15 @@ Conflict targets are checked against the target table.
 Mutation plans can project typed rows with `returning(...)`.
 
 ```ts
-const insertedUser = Q.returning({
-  id: users.id,
-  email: users.email
-})(Q.insert(users, {
+const insertedUser = Q.insert(users, {
   id: "user-1",
   email: "alice@example.com"
-}))
+}).pipe(
+  Q.returning({
+    id: users.id,
+    email: users.email
+  })
+)
 
 type InsertedUserRow = Q.ResultRow<typeof insertedUser>
 // {
@@ -763,15 +893,15 @@ type InsertedUserRow = Q.ResultRow<typeof insertedUser>
 Write plans can feed later reads in the same statement:
 
 ```ts
-const insertedUsers = Q.with(
+const insertedUsers = Q.insert(users, {
+  id: "user-1",
+  email: "alice@example.com"
+}).pipe(
   Q.returning({
     id: users.id,
     email: users.email
-  })(Q.insert(users, {
-    id: "user-1",
-    email: "alice@example.com"
-  })),
-  "inserted_users"
+  }),
+  Q.with("inserted_users")
 )
 
 const insertedUsersPlan = Q.select({
@@ -789,9 +919,9 @@ This is one of the places where the capability model matters: write-bearing nest
 ### Renderer
 
 ```ts
-import * as Postgres from "effect-qb/postgres"
+import { Renderer as PostgresRenderer } from "effect-qb/postgres"
 
-const rendered = Postgres.Renderer.make().render(postsPerUser)
+const rendered = PostgresRenderer.make().render(postsPerUser)
 
 rendered.sql
 rendered.params
@@ -810,24 +940,26 @@ They do not carry a query-result schema.
 ### Executor
 
 ```ts
-import * as Postgres from "effect-qb/postgres"
+import { Executor as PostgresExecutor, Query as Q } from "effect-qb/postgres"
 
-const renderer = Postgres.Renderer.make()
-const executor = Postgres.Executor.fromSqlClient(renderer)
+const executor = PostgresExecutor.make()
 
 const rowsEffect = executor.execute(postsPerUser)
 
-type Rows = Postgres.Query.ResultRows<typeof postsPerUser>
-type Error = Postgres.Executor.PostgresQueryError<typeof postsPerUser>
+type Rows = Q.ResultRows<typeof postsPerUser>
+type Error = PostgresExecutor.PostgresQueryError<typeof postsPerUser>
 ```
 
+Pass `{ renderer }`, `{ driver }`, or both when you need to customize execution.
+
 Execution is:
 
 1. render the plan
-2. execute SQL
-3. remap flat aliases into nested objects
+2. normalize raw driver values into canonical runtime values
+3. apply schema-backed transforms where they exist
+4. remap flat aliases into nested objects
 
-There is no query-result schema decode stage.
+There is no automatically derived whole-query schema.
 
 ### Query-sensitive Error Channels
 
@@ -841,10 +973,10 @@ Those types are narrower than the raw dialect error catalogs. For example, known
 ### Transaction Helpers
 
 ```ts
-import { Executor } from "effect-qb"
+import { Executor as PostgresExecutor } from "effect-qb/postgres"
 
-const transactional = Executor.withTransaction(rowsEffect)
-const savepoint = Executor.withSavepoint(rowsEffect)
+const transactional = PostgresExecutor.withTransaction(rowsEffect)
+const savepoint = PostgresExecutor.withSavepoint(rowsEffect)
 ```
 
 These preserve the original effect type parameters and add the ambient SQL transaction boundary.
@@ -865,8 +997,8 @@ The unusual part is that these are not separate features bolted together. The bu
 Both dialect entrypoints expose an `Errors` module:
 
 ```ts
-import * as Postgres from "effect-qb/postgres"
-import * as Mysql from "effect-qb/mysql"
+import { Errors as PostgresErrors } from "effect-qb/postgres"
+import { Errors as MysqlErrors } from "effect-qb/mysql"
 ```
 
 The catalogs are backed by official vendor references:
@@ -879,7 +1011,7 @@ That means the tags and descriptor metadata are systematic, not handwritten one-
 Postgres errors normalize around SQLSTATE codes:
 
 ```ts
-const descriptor = Postgres.Errors.getPostgresErrorDescriptor("23505")
+const descriptor = PostgresErrors.getPostgresErrorDescriptor("23505")
 descriptor.tag
 // "@postgres/integrity-constraint-violation/unique-violation"
 descriptor.classCode
@@ -887,7 +1019,7 @@ descriptor.className
 descriptor.condition
 descriptor.primaryFields
 
-const postgresError = Postgres.Errors.normalizePostgresDriverError({
+const postgresError = PostgresErrors.normalizePostgresDriverError({
   code: "23505",
   message: "duplicate key value violates unique constraint",
   constraint: "users_email_key"
@@ -901,7 +1033,7 @@ postgresError.constraintName
 MySQL errors normalize around official symbols and documented numbers:
 
 ```ts
-const descriptor = Mysql.Errors.getMysqlErrorDescriptor("ER_DUP_ENTRY")
+const descriptor = MysqlErrors.getMysqlErrorDescriptor("ER_DUP_ENTRY")
 descriptor.tag
 // "@mysql/server/dup-entry"
 descriptor.category
@@ -909,7 +1041,7 @@ descriptor.number
 descriptor.sqlState
 descriptor.messageTemplate
 
-const mysqlError = Mysql.Errors.normalizeMysqlDriverError({
+const mysqlError = MysqlErrors.normalizeMysqlDriverError({
   code: "ER_DUP_ENTRY",
   errno: 1062,
   sqlState: "23000",
@@ -958,7 +1090,7 @@ const descriptors =
 
 Executors narrow their error channels based on what the plan is allowed to do.
 
-This happens in the built-in `fromDriver(...)` and `fromSqlClient(...)` paths. They normalize the raw failure first, then decide whether the plan should expose the full dialect error surface or the read-only narrowed surface.
+This happens in the built-in `Executor.make(...)` and `Executor.driver(...)` paths. They normalize the raw failure first, then decide whether the plan should expose the full dialect error surface or the read-only narrowed surface.
 
 That matters most for read-only plans. If a raw driver error clearly requires write capabilities, the executor does not surface it directly on a read query. It wraps it in a query-requirements error instead:
 
@@ -979,11 +1111,13 @@ If the plan really is write-bearing, including write CTEs, the original normaliz
 This is reflected at the type level too:
 
 ```ts
+import { Executor as PostgresExecutor } from "effect-qb/postgres"
+
 type ReadError =
-  Postgres.Executor.PostgresQueryError<typeof readPlan>
+  PostgresExecutor.PostgresQueryError<typeof readPlan>
 
 type WriteError =
-  Postgres.Executor.PostgresQueryError<typeof writePlan>
+  PostgresExecutor.PostgresQueryError<typeof writePlan>
 ```
 
 For a read-only plan, `ReadError` is the narrowed read-query surface. For a write-bearing plan, `WriteError` is the full normalized Postgres executor error surface. The MySQL executor follows the same rule.
@@ -992,10 +1126,10 @@ You can also inspect requirements directly:
 
 ```ts
 const postgresRequirements =
-  Postgres.Errors.requirements_of_postgres_error(postgresError)
+  PostgresErrors.requirements_of_postgres_error(postgresError)
 
 const mysqlRequirements =
-  Mysql.Errors.requirements_of_mysql_error(mysqlError)
+  MysqlErrors.requirements_of_mysql_error(mysqlError)
 ```
 
 ### Matching Errors In Application Code
@@ -1017,15 +1151,15 @@ const rows = executor.execute(plan).pipe(
 Use the dialect guards for precise narrowing inside shared helpers:
 
 ```ts
-if (Postgres.Errors.hasSqlState(error, "23505")) {
+if (PostgresErrors.hasSqlState(error, "23505")) {
   error.constraintName
 }
 
-if (Mysql.Errors.hasSymbol(error, "ER_DUP_ENTRY")) {
+if (MysqlErrors.hasSymbol(error, "ER_DUP_ENTRY")) {
   error.number
 }
 
-if (Mysql.Errors.hasNumber(error, "1062")) {
+if (MysqlErrors.hasNumber(error, "1062")) {
   error.symbol
 }
 ```
@@ -1076,22 +1210,22 @@ The same branded error shape applies when `where(...)`, joins, or projections re
 Predicates refine result types, not just SQL.
 
 ```ts
-const filteredPosts = Q.select({
+const helloPosts = Q.select({
   title: posts.title,
-  upperTitle: Q.upper(posts.title)
+  upperTitle: F.upper(posts.title)
 }).pipe(
   Q.from(posts),
-  Q.where(Q.isNotNull(posts.title))
+  Q.where(Q.eq(posts.title, "hello"))
 )
 
-type FilteredPostsRow = Q.ResultRow<typeof filteredPosts>
+type HelloPostsRow = Q.ResultRow<typeof helloPosts>
 // {
 //   title: string
 //   upperTitle: string
 // }
 ```
 
-This is one of the biggest differences between `ResultRow` and a hand-written row interface.
+Equality against a non-null literal narrows too. You do not need `isNotNull(...)` to get non-null output.
 
 ### Join Optionality
 
@@ -1111,9 +1245,24 @@ type MaybePostsRow = Q.ResultRow<typeof maybePosts>
 //   userId: string
 //   postId: string | null
 // }
+
+const titledPosts = Q.select({
+  userId: users.id,
+  postId: posts.id
+}).pipe(
+  Q.from(users),
+  Q.leftJoin(posts, Q.eq(users.id, posts.userId)),
+  Q.where(Q.isNotNull(posts.title))
+)
+
+type TitledPostsRow = Q.ResultRow<typeof titledPosts>
+// {
+//   userId: string
+//   postId: string
+// }
 ```
 
-Add `where(Q.isNotNull(posts.id))` and the logical row type becomes non-null for `postId`.
+Any non-null proof on the joined table can promote the whole joined source, not just the join key.
 
 ### Grouped Query Validation
 
@@ -1123,7 +1272,7 @@ Grouped queries are checked structurally:
 const invalidGroupedPlan = Q.select({
   userId: users.id,
   title: posts.title,
-  postCount: Q.count(posts.id)
+  postCount: F.count(posts.id)
 }).pipe(
   Q.from(users),
   Q.leftJoin(posts, Q.eq(users.id, posts.userId)),
@@ -1145,29 +1294,24 @@ This catches invalid grouped queries before rendering.
 Plans, tables, renderers, and executors are dialect-branded.
 
 ```ts
-import * as Mysql from "effect-qb/mysql"
-import * as Postgres from "effect-qb/postgres"
+import { Column as MysqlColumn, Query as MysqlQuery, Table as MysqlTable } from "effect-qb/mysql"
+import { Executor as PostgresExecutor } from "effect-qb/postgres"
 
-const mysqlUsers = Mysql.Table.make("users", {
-  id: Mysql.Column.uuid().pipe(Mysql.Column.primaryKey)
+const mysqlUsers = MysqlTable.make("users", {
+  id: MysqlColumn.uuid().pipe(MysqlColumn.primaryKey)
 })
 
-const mysqlPlan = Mysql.Query.select({
+const mysqlPlan = MysqlQuery.select({
   id: mysqlUsers.id
 }).pipe(
-  Mysql.Query.from(mysqlUsers)
+  MysqlQuery.from(mysqlUsers)
 )
 
-type WrongDialect =
-  Postgres.Query.DialectCompatiblePlan<typeof mysqlPlan, "postgres">
-// {
-//   __effect_qb_error__:
-//     "effect-qb: plan dialect is not compatible with the target renderer or executor"
-//   __effect_qb_plan_dialect__: "mysql"
-//   __effect_qb_target_dialect__: "postgres"
-//   __effect_qb_hint__:
-//     "Use the matching dialect module or renderer/executor"
-// }
+const postgresExecutor = PostgresExecutor.make()
+
+// @ts-expect-error mysql plans are not dialect-compatible with the postgres executor
+postgresExecutor.execute(mysqlPlan)
+// effect-qb: plan dialect is not compatible with the target renderer or executor
 ```
 
 ### JSON Schema Compatibility In Mutations
@@ -1176,6 +1320,7 @@ Schema-backed JSON columns are checked on insert and update.
 
 ```ts
 import * as Schema from "effect/Schema"
+import { Column as C, Function as F, Query as Q, Table } from "effect-qb/postgres"
 
 const docs = Table.make("docs", {
   id: C.uuid().pipe(C.primaryKey),
@@ -1191,13 +1336,13 @@ const docs = Table.make("docs", {
   }))
 })
 
-const cityPath = Q.json.path(
-  Q.json.key("profile"),
-  Q.json.key("address"),
-  Q.json.key("city")
+const cityPath = F.json.path(
+  F.json.key("profile"),
+  F.json.key("address"),
+  F.json.key("city")
 )
 
-const incompatibleObject = Q.json.buildObject({
+const incompatibleObject = F.json.buildObject({
   profile: {
     address: {
       postcode: "1000"
@@ -1207,7 +1352,7 @@ const incompatibleObject = Q.json.buildObject({
   note: null
 })
 
-const deletedRequiredField = Q.json.delete(docs.payload, cityPath)
+const deletedRequiredField = F.json.delete(docs.payload, cityPath)
 
 Q.insert(docs, {
   id: "doc-1",
@@ -1243,7 +1388,7 @@ That makes invalid plans easier to inspect in editor tooltips and type aliases.
 
 ### PostgreSQL
 
-- default root entrypoint
+- `effect-qb/postgres`
 - `distinctOn(...)`
 - wider JSON operator surface, including `json.pathMatch(...)`
 - schema-qualified tables default to `public`
@@ -1273,7 +1418,7 @@ Current practical limits:
 - some features are dialect-specific by design
 - JSON support is not identical between Postgres and MySQL
 - admin and DDL workflows are not the focus of this README
-- runtime execution is schema-free, so the database is expected to honor the query contract
+- runtime schema enforcement follows propagated column and projection schemas, not full query-derived schemas
 
 ## Contributing
 
@@ -1282,13 +1427,16 @@ Useful commands:
 ```bash
 bun test
 bun run test:types
+bun run test:integration
+bun run release
 ```
 
 Useful places to start:
 
-- [src/index.ts](./src/index.ts)
+- [src/postgres.ts](./src/postgres.ts)
 - [src/internal/query-factory.ts](./src/internal/query-factory.ts)
-- [test/query.behavior.test.ts](./test/query.behavior.test.ts)
-- [test/types/query-composition-types.ts](./test/types/query-composition-types.ts)
+- [src/postgres/private/query.ts](./src/postgres/private/query.ts)
+- [test/public/behavior/query.behavior.test.ts](./test/public/behavior/query.behavior.test.ts)
+- [test/public/types/query-composition-types.ts](./test/public/types/query-composition-types.ts)
 
 The codebase is organized around typed plans, dialect-specialized entrypoints, and behavior-first tests.