@zio.dev/zio-blocks 0.0.33 → 0.0.55

package/reference/sql/db-result-reader.md

@@ -0,0 +1,148 @@
+---
+id: db-result-reader
+title: "DbResultReader"
+description: "Reference for DbResultReader, the interface for reading typed column values from a SQL result set."
+keywords:
+  - "DbResultReader Column Access"
+  - "Result Set Abstraction"
+---
+
+`DbResultReader` is a trait for reading typed column values from a database result set. It provides methods to access columns by either their 1-based index (following JDBC convention) or by column label.
+
+Application code does not use `DbResultReader` directly — the framework creates it automatically when a `Frag` is executed. It is the read-side counterpart to `DbParamWriter`, which writes values to prepared statements.
+
+## Core API
+
+The core API reads numeric, text, binary, boolean, temporal, and UUID values, plus column metadata and NULL status. `getArray` also exists but defaults to throwing `UnsupportedOperationException` in the shared trait; only backends that override it (the JVM implementation does) actually support SQL array access:
+
+```scala
+trait DbResultReader {
+  // Numeric types
+  def getInt(index: Int): Int
+  def getInt(label: String): Int
+  def getLong(index: Int): Long
+  def getLong(label: String): Long
+  def getDouble(index: Int): Double
+  def getDouble(label: String): Double
+  def getFloat(index: Int): Float
+  def getFloat(label: String): Float
+  def getShort(index: Int): Short
+  def getShort(label: String): Short
+  def getByte(index: Int): Byte
+  def getByte(label: String): Byte
+  def getBigDecimal(index: Int): java.math.BigDecimal
+  def getBigDecimal(label: String): java.math.BigDecimal
+
+  // Text and binary
+  def getString(index: Int): String
+  def getString(label: String): String
+  def getBytes(index: Int): Array[Byte]
+  def getBytes(label: String): Array[Byte]
+
+  // Boolean
+  def getBoolean(index: Int): Boolean
+  def getBoolean(label: String): Boolean
+
+  // Date and time
+  def getLocalDate(index: Int): java.time.LocalDate
+  def getLocalDate(label: String): java.time.LocalDate
+  def getLocalDateTime(index: Int): java.time.LocalDateTime
+  def getLocalDateTime(label: String): java.time.LocalDateTime
+  def getLocalTime(index: Int): java.time.LocalTime
+  def getLocalTime(label: String): java.time.LocalTime
+  def getInstant(index: Int): java.time.Instant
+  def getInstant(label: String): java.time.Instant
+  def getDuration(index: Int): java.time.Duration
+  def getDuration(label: String): java.time.Duration
+
+  // Other types
+  def getUUID(index: Int): java.util.UUID
+  def getUUID(label: String): java.util.UUID
+  def getArray(index: Int): Array[String]    // default: throws UnsupportedOperationException
+  def getArray(label: String): Array[String] // default: throws UnsupportedOperationException
+
+  // Metadata and NULL detection
+  def columnLabel(index: Int): String
+  def hasColumn(label: String): Boolean
+  def wasNull: Boolean
+  def isNull(index: Int): Boolean  // default: false
+  def isNull(label: String): Boolean // default: false
+}
+```
+
+## Usage
+
+You access `DbResultReader` through `DbResultSet.reader` after calling `executeQuery` on a prepared statement:
+
+```scala
+import zio.blocks.sql._
+
+val transactor: Transactor = JdbcTransactor.fromUrl("jdbc:sqlite::memory:", SqlDialect.SQLite)
+
+transactor.connect {
+  val con = summon[DbCon].connection
+  val stmt = con.prepareStatement("SELECT id, name, age FROM users")
+  val rs = stmt.executeQuery()
+  
+  if (rs.next()) {
+    // Read by column label
+    val id: Long    = rs.reader.getLong("id")
+    val name: String = rs.reader.getString("name")
+    val age: Int    = rs.reader.getInt("age")
+  }
+  
+  rs.close()
+  stmt.close()
+}
+```
+
+## NULL Handling
+
+Numeric and boolean getters return zero-like defaults (`0`, `0L`, `false`) for SQL `NULL`. String, decimal, and temporal getters return `null`. After any `get*` call, check `wasNull` to detect `NULL`:
+
+```scala
+import zio.blocks.sql._
+
+val transactor: Transactor = JdbcTransactor.fromUrl("jdbc:sqlite::memory:", SqlDialect.SQLite)
+
+transactor.connect {
+  val con = summon[DbCon].connection
+  val stmt = con.prepareStatement("SELECT bio FROM users LIMIT 1")
+  val rs = stmt.executeQuery()
+  
+  if (rs.next()) {
+    val bio: String = rs.reader.getString("bio")
+    val bioOption: Option[String] = if (rs.reader.wasNull) None else Some(bio)
+  }
+  
+  rs.close()
+  stmt.close()
+}
+```
+
+:::caution
+Always call `wasNull` immediately after the `get*` call whose NULL status you want to check. Do not call another `get*` method in between, or `wasNull` will reflect the wrong result.
+:::
+
+## How It Works
+
+When you use high-level operations like `Frag.query` or `Repo.find`, `DbCodec` internally calls `DbResultReader` methods to decode result rows. You only see this trait directly when dropping down to raw prepared statements for advanced use cases.
+
+Label-based access (preferred) lets you ignore column order:
+
+```scala
+import zio.blocks.sql._
+
+val reader: DbResultReader = ???
+val name = reader.getString("name")  // Works regardless of SELECT order
+```
+
+Index-based access (1-based per JDBC) is faster but requires stable column order:
+
+```scala
+import zio.blocks.sql._
+
+val reader: DbResultReader = ???
+val name = reader.getString(2)  // Assumes name is the 2nd column
+```
+

package/reference/sql/db-tx.md

@@ -0,0 +1,114 @@
+---
+id: db-tx
+title: "DbTx"
+description: "Reference for DbTx, the SQL module's transactional scope marker that extends DbCon with commit-on-success and rollback-on-failure semantics."
+keywords:
+  - "DbTx Transaction Scope"
+  - "Transactor Transact Context"
+  - "DbCon Subtype Marker"
+  - "Auto-Commit Disabled Transaction"
+  - "Commit Rollback Semantics"
+  - "SQL Module Connection Context"
+  - "JDBC Transaction Lifecycle"
+---
+
+`DbTx` is the transactional connection context supplied by `Transactor#transact`. It extends `DbCon` (so every `Frag`/`Repo` operation that needs `DbCon` also accepts `DbTx`) and adds savepoint-based nested transaction support. You never construct a `DbTx` directly; the `Transactor` creates one and supplies it as a given context to the block passed to `transact`. The connection is always closed when the outermost block exits, whether it commits, rolls back, or throws.
+
+Key properties:
+- **Transactional context** — A `DbTx` value in scope guarantees the underlying JDBC connection has auto-commit disabled.
+- **Commit-on-success / rollback-on-failure** — The outermost `Transactor.transact` commits on normal return and rolls back on any uncaught exception (with suppressed rollback failures).
+- **Savepoint-based nesting** — Inner blocks reuse the same connection via SQL savepoints (`SAVEPOINT` / `RELEASE SAVEPOINT` / `ROLLBACK TO SAVEPOINT`).
+- **`transact(isolation, readOnly)`** — The two-arg `Transactor.transact` overload sets isolation level and `readOnly` before disabling auto-commit; `DbTx` nested blocks inherit those settings on the same connection.
+
+The structural declaration of `DbTx` is:
+
+```scala
+trait DbTx extends DbCon {
+  def savepoint(name: String): Unit
+  def release(name: String): Unit
+  def rollbackTo(name: String): Unit
+  def currentDepth: Int
+  private[sql] def currentDepth_=(depth: Int): Unit
+
+  // inherited from DbCon
+  def connection: DbConnection
+  def dialect: SqlDialect
+  def logger: SqlLogger
+}
+```
+
+## Usage
+
+The following example opens a transaction via `Transactor#transact`, accesses all three context members, and combines a `Repo` CRUD operation with a hand-written `Frag` query — both of which accept `DbTx` transparently in place of `DbCon`:
+
+```scala
+import zio.blocks.sql._
+import zio.blocks.schema.Schema
+
+case class User(id: Int, name: String, email: String)
+object User {
+  implicit val schema: Schema[User] = Schema.derived
+}
+
+val repo = Repo.derived[User, Int]("users", "id", _.id)
+// repo: Repo[User, Int] = zio.blocks.sql.Repo$DerivedRepo@783c5728
+val tx   = JdbcTransactor.fromUrl("jdbc:sqlite::memory:", SqlDialect.SQLite)
+// tx: JdbcTransactor = zio.blocks.sql.JdbcTransactor@2ee9e31d
+
+// On normal return: transaction commits and connection closes.
+// On any exception: transaction rolls back, then the exception propagates.
+tx.transact {
+  // All three context members are accessible via summon[DbTx]
+  val conn: DbConnection = summon[DbTx].connection // managed JDBC connection — do not close manually
+  val d:    SqlDialect   = summon[DbTx].dialect
+  val log:  SqlLogger    = summon[DbTx].logger
+
+  // Repo and Frag operations accept DbTx because DbTx extends DbCon
+  repo.table.createTable(summon[DbTx].dialect).update
+  repo.insert(User(1, "Alice", "alice@example.com"))
+  repo.insert(User(2, "Bob",   "bob@example.com"))
+
+  val all:    List[User] = repo.all
+  val custom: List[User] =
+    sql"SELECT id, name, email FROM users WHERE name LIKE ${"A%"}".query[User]
+
+  (all, custom)
+}
+// res1: Tuple2[List[User], List[User]] = (
+//   List(
+//     User(id = 1, name = "Alice", email = "alice@example.com"),
+//     User(id = 2, name = "Bob", email = "bob@example.com")
+//   ),
+//   List(User(id = 1, name = "Alice", email = "alice@example.com"))
+// )
+```
+
+## Nested Transactions via Savepoints
+
+Nested transactions reuse the same underlying JDBC connection via SQL savepoints. The `DbTx` given in scope exposes an extension `transact` and the `transactNested` helpers:
+
+```scala
+import zio.blocks.sql._
+
+val transactor = JdbcTransactor.fromUrl("jdbc:sqlite::memory:", SqlDialect.SQLite)
+
+// Savepoint-based nesting — same connection, isolated rollback
+transactor.transact {
+  sql"INSERT INTO t VALUES (1)".update
+
+  // Inner block runs inside SAVEPOINT zib_tx_1
+  summon[DbTx].transact {
+    sql"INSERT INTO t VALUES (2)".update
+  }
+
+  // Equivalent using the `using` helper
+  // DbTx.transactNested { sql"INSERT INTO t VALUES (3)".update }
+  // transactNested { sql"INSERT INTO t VALUES (4)".update }
+}
+```
+
+Savepoint names are `zib_tx_1 .. zib_tx_N` where `N` is the nesting depth tracked in `currentDepth`. On success the savepoint is released via `RELEASE SAVEPOINT`; on failure it is rolled back via `ROLLBACK TO SAVEPOINT` and the exception is rethrown (with any rollback failure added as suppressed). Depth is decremented in `finally`, so sibling nested blocks reuse the same name sequence without leaking savepoints. `savepoint`/`release`/`rollbackTo` are also available directly for manual control and validate identifiers via `SqlIdentifier` to prevent injection.
+
+:::caution
+Only the outermost `Transactor.transact` issues a real `COMMIT`/`ROLLBACK`. Inner `summon[DbTx].transact` blocks are savepoint-scoped — outer commit still decides the final persistence of all work, including inner blocks that succeeded.
+:::

package/reference/sql/db-value.md

@@ -0,0 +1,41 @@
+---
+id: db-value
+title: "DbValue"
+description: "Reference for DbValue, the sealed ADT of typed SQL column values shared by Frag, DbCodec, and SqlDialect in the sql module."
+keywords:
+  - "DbValue sealed ADT"
+  - "SQL column value types"
+  - "DbNull DbInt DbString"
+  - "typed database parameters"
+  - "SqlDialect typeName"
+  - "DbCodec toDbValues"
+  - "Frag params representation"
+---
+
+`DbValue` is a sealed ADT representing every typed SQL column value the `sql` module handles, one `case class` per Scala type. `Frag` stores its bound parameters as `IndexedSeq[DbValue]`, `DbCodec#toDbValues` produces them, and `SqlDialect#typeName` maps a `DbValue` to its DDL type string — it is the common typed currency all three share, with no JDBC imports or dependencies of its own.
+
+| Variant           | Scala field type          | PostgreSQL DDL     | SQLite DDL |
+|-------------------|----------------------------|---------------------|------------|
+| `DbNull`          | *(none)*                   | `NULL`               | `NULL`     |
+| `DbInt`           | `Int`                       | `INTEGER`             | `INTEGER`  |
+| `DbLong`          | `Long`                      | `BIGINT`              | `INTEGER`  |
+| `DbDouble`        | `Double`                    | `DOUBLE PRECISION`    | `REAL`     |
+| `DbFloat`         | `Float`                     | `REAL`                | `REAL`     |
+| `DbBoolean`       | `Boolean`                   | `BOOLEAN`             | `INTEGER`  |
+| `DbString`        | `String`                    | `TEXT`                | `TEXT`     |
+| `DbBigDecimal`    | `scala.BigDecimal`          | `NUMERIC`             | `TEXT`     |
+| `DbBytes`         | `Array[Byte]`               | `BYTEA`               | `BLOB`     |
+| `DbShort`         | `Short`                     | `SMALLINT`            | `INTEGER`  |
+| `DbByte`          | `Byte`                      | `SMALLINT`            | `INTEGER`  |
+| `DbChar`          | `Char`                      | `CHAR(1)`             | `TEXT`     |
+| `DbLocalDate`     | `java.time.LocalDate`       | `DATE`                | `TEXT`     |
+| `DbLocalDateTime` | `java.time.LocalDateTime`   | `TIMESTAMP`           | `TEXT`     |
+| `DbLocalTime`     | `java.time.LocalTime`       | `TIME`                | `TEXT`     |
+| `DbInstant`       | `java.time.Instant`         | `TIMESTAMPTZ`         | `TEXT`     |
+| `DbDuration`      | `java.time.Duration`        | `INTERVAL`            | `TEXT`     |
+| `DbUUID`          | `java.util.UUID`            | `UUID`                | `TEXT`     |
+| `DbArray`         | `(String, IndexedSeq[Any])` | *(not in typeName)*   | *(not in typeName)* |
+
+`DbNull` is what `DbParam[Option[A]]` produces for `None` and `DbParam[Maybe[A]]` produces for `Maybe.absent`; `DbCodec` matches on it to decode nullable columns, throwing `IllegalStateException` if a non-optional codec hits it. `DbArray` is the one variant with two fields (`elementType`, `elements`) instead of `value`, used for collection-typed columns and not currently covered by `SqlDialect#typeName`.
+
+See [Frag](./frag.md), [DbCodec](./db-codec.md), and the [SQL module index](./index.md).

package/reference/sql/ddl.md

@@ -0,0 +1,85 @@
+---
+id: ddl
+title: "Ddl"
+description: "Reference for Ddl, the helper singleton that generates CREATE TABLE and DROP TABLE SQL fragments."
+keywords:
+  - "Ddl createTable"
+  - "Ddl dropTable"
+  - "ColumnDef SQL type"
+  - "CREATE TABLE IF NOT EXISTS"
+  - "DROP TABLE IF EXISTS"
+---
+
+`Ddl` is a helper object that generates DDL (Data Definition Language) SQL fragments for creating and dropping tables. `ColumnDef` is a simple data class pairing a column name with a SQL type string and a nullability flag.
+
+Normally you don't call `Ddl` directly — `Table#createTable` and `Table#dropTable` use it internally. You may need `Ddl` directly when building custom DDL tooling.
+
+## Core API
+
+```scala
+object Ddl {
+  def createTable(tableName: String, columns: IndexedSeq[ColumnDef]): Frag
+  def dropTable(tableName: String): Frag
+}
+
+final case class ColumnDef(name: String, sqlType: String, nullable: Boolean)
+```
+
+## Usage
+
+Create a `ColumnDef` for each column, then pass them to `Ddl.createTable`:
+
+```scala
+import zio.blocks.sql._
+
+val transactor: Transactor = JdbcTransactor.fromUrl("jdbc:sqlite::memory:", SqlDialect.SQLite)
+// transactor: Transactor = zio.blocks.sql.JdbcTransactor@3200cfda
+
+val columns = IndexedSeq(
+  ColumnDef("id",         "INTEGER", nullable = false),
+  ColumnDef("name",       "TEXT",    nullable = false),
+  ColumnDef("created_at", "TEXT",    nullable = true)
+)
+// columns: IndexedSeq[ColumnDef] = Vector(
+//   ColumnDef(name = "id", sqlType = "INTEGER", nullable = false),
+//   ColumnDef(name = "name", sqlType = "TEXT", nullable = false),
+//   ColumnDef(name = "created_at", sqlType = "TEXT", nullable = true)
+// )
+
+val createFrag = Ddl.createTable("users", columns)
+// createFrag: Frag = Frag(
+//   parts = Vector(
+//     """CREATE TABLE IF NOT EXISTS users (
+//   id INTEGER NOT NULL,
+//   name TEXT NOT NULL,
+//   created_at TEXT
+// )"""
+//   ),
+//   params = Vector()
+// )
+val dropFrag   = Ddl.dropTable("users")
+// dropFrag: Frag = Frag(
+//   parts = Vector("DROP TABLE IF EXISTS users"),
+//   params = Vector()
+// )
+
+// Execute the fragments
+transactor.transact {
+  createFrag.update
+  // ... do work ...
+  dropFrag.update
+}
+// res1: Int = 0
+```
+
+## How It Works
+
+`Ddl` is typically used by `Table#createTable`, which derives `ColumnDef` from schema metadata:
+
+1. `Table.derived[A]` builds a schema.
+2. `Table#createTable(dialect)` converts schema columns to `ColumnDef` using `dialect.typeName`.
+3. `Ddl.createTable` receives the `ColumnDef` list and generates the SQL fragment.
+
+You call `Ddl` directly only when you need custom DDL that doesn't fit the `Table` abstraction.
+
+See [Table](./table.md) for the high-level DDL API.

package/reference/sql/frag.md

@@ -0,0 +1,288 @@
+---
+id: frag
+title: "Frag"
+description: "Reference for Frag, the SQL fragment type with safe parameterization and JDBC execution."
+keywords:
+  - "SQL Fragment"
+  - "Frag SQL Interpolator"
+  - "Type-safe SQL parameters"
+  - "SQL Injection Prevention"
+---
+
+`Frag` is an immutable SQL fragment — a piece of SQL text with typed parameter values kept safely separate from the literal SQL. The `sql"..."` string interpolator builds fragments by checking at compile time that every interpolated expression can be bound as a parameter. Fragments compose with `++` and execute through methods like `query`, `update`, and `queryOne`, plus the chunked streaming methods `queryStream` and `queryChunked`.
+
+`Frag` is safe from SQL injection because parameter values never appear in the SQL string — they are stored separately and bound to `?` placeholders at execution time.
+
+## Core API
+
+```scala
+final case class Frag(parts: IndexedSeq[String], params: IndexedSeq[DbValue]) {
+  def ++(other: Frag): Frag
+  def sql(dialect: SqlDialect): String
+  def queryParams: IndexedSeq[DbValue]
+  def isEmpty: Boolean
+}
+
+object Frag {
+  val empty: Frag
+  def literal(sqlStr: String): Frag
+  def sequence(frags: Frag*): Frag
+  def values[A](rows: Seq[A])(using codec: DbCodec[A]): Frag
+
+  extension (frag: Frag) {
+    def query[A](using DbCon, DbCodec[A]): List[A]
+    def queryOne[A](using DbCon, DbCodec[A]): Maybe[A]
+    def queryLimit[A](limit: Int)(using DbCon, DbCodec[A]): List[A]
+    def queryStream[A](using DbCon, DbCodec[A]): Stream[Throwable, Chunk[A]]
+    def queryChunked[A](chunkSize: Int)(using DbCon, DbCodec[A]): Stream[Throwable, Chunk[A]]
+    def update(using DbCon): Int
+    def updateReturningKeys[A](using DbCon, DbCodec[A]): List[A]
+  }
+}
+```
+
+## Usage
+
+Build fragments with the `sql"..."` interpolator and execute them inside a `Transactor` block:
+
+```scala
+import zio.blocks.sql._
+import zio.blocks.schema.Schema
+import zio.blocks.maybe.Maybe
+
+case class User(id: Int, name: String, email: String)
+object User { implicit val schema: Schema[User] = Schema.derived }
+
+val tx: Transactor = JdbcTransactor.fromUrl("jdbc:sqlite::memory:", SqlDialect.SQLite)
+
+val userId  = 42
+val active  = true
+
+tx.connect {
+  // Query — returns all matching rows
+  val users: List[User] = 
+    sql"SELECT id, name, email FROM users WHERE id > $userId AND active = $active".query[User]
+  
+  // QueryOne — returns at most one row
+  val one: Maybe[User] = 
+    sql"SELECT id, name, email FROM users WHERE id = ${1}".queryOne[User]
+  
+  // Update — returns affected row count
+  val deleted: Int = 
+    sql"DELETE FROM users WHERE active = ${false}".update
+  
+  // UpdateReturningKeys — returns generated keys after INSERT
+  val keys: List[Long] = 
+    sql"INSERT INTO users (name, email) VALUES (${"Alice"}, ${"alice@example.com"})".updateReturningKeys[Long]
+}
+```
+
+## Building Fragments
+
+**`sql"..."` interpolator** — The primary way to build fragments. Compile-time checked: every interpolated value must have a `DbParam` instance (provided for all common Scala and Java types).
+
+```scala
+import zio.blocks.sql._
+
+val userId = 42
+// userId: Int = 42
+val frag = sql"SELECT * FROM users WHERE id = $userId"
+// frag: Frag = Frag(
+//   parts = Vector("SELECT * FROM users WHERE id = ", ""),
+//   params = Vector(DbInt(42))
+// )
+frag.params
+// res2: IndexedSeq[DbValue] = Vector(DbInt(42))
+```
+
+**`Frag.literal`** — Wrap static SQL text (no parameters):
+
+```scala
+val query = sql"SELECT * FROM users" ++ Frag.literal(" ORDER BY name")
+// query: Frag = Frag(
+//   parts = Vector("SELECT * FROM users ORDER BY name"),
+//   params = Vector()
+// )
+query.sql(SqlDialect.SQLite)
+// res3: String = "SELECT * FROM users ORDER BY name"
+```
+
+**`Frag.values`** — Build a multi-row INSERT VALUES clause:
+
+```scala
+import zio.blocks.sql._
+
+case class Product(name: String, price: BigDecimal) derives DbCodec
+
+val products = List(Product("Widget", BigDecimal("9.99")), Product("Gadget", BigDecimal("24.99")))
+// products: List[Product] = List(
+//   Product(name = "Widget", price = 9.99),
+//   Product(name = "Gadget", price = 24.99)
+// )
+val insert = Frag.literal("INSERT INTO product (name, price) VALUES ") ++ Frag.values(products)
+// insert: Frag = Frag(
+//   parts = Vector(
+//     "INSERT INTO product (name, price) VALUES (",
+//     ", ",
+//     "), (",
+//     ", ",
+//     ")"
+//   ),
+//   params = Vector(
+//     DbString("Widget"),
+//     DbBigDecimal(9.99),
+//     DbString("Gadget"),
+//     DbBigDecimal(24.99)
+//   )
+// )
+insert.sql(SqlDialect.SQLite)
+// res5: String = "INSERT INTO product (name, price) VALUES (?, ?), (?, ?)"
+```
+
+**`Frag.empty`** — The identity fragment for composition. Useful for optional clauses:
+
+```scala
+import zio.blocks.sql._
+
+val hasFilter = true
+// hasFilter: Boolean = true
+val where = if (hasFilter) sql" WHERE active = ${true}" else Frag.empty
+// where: Frag = Frag(
+//   parts = Vector(" WHERE active = ", ""),
+//   params = Vector(DbBoolean(true))
+// )
+val query = sql"SELECT * FROM users" ++ where
+// query: Frag = Frag(
+//   parts = Vector("SELECT * FROM users WHERE active = ", ""),
+//   params = Vector(DbBoolean(true))
+// )
+query.sql(SqlDialect.SQLite)
+// res7: String = "SELECT * FROM users WHERE active = ?"
+```
+
+**`Frag.sequence`** — Concatenate multiple fragments with no separator:
+
+```scala
+import zio.blocks.sql._
+
+val status = "active"
+// status: String = "active"
+val base   = sql"SELECT * FROM users"
+// base: Frag = Frag(parts = Vector("SELECT * FROM users"), params = Vector())
+val where  = sql" WHERE status = $status"
+// where: Frag = Frag(
+//   parts = Vector(" WHERE status = ", ""),
+//   params = Vector(DbString("active"))
+// )
+val order  = Frag.literal(" ORDER BY name")
+// order: Frag = Frag(parts = Vector(" ORDER BY name"), params = Vector())
+val full   = Frag.sequence(base, where, order)
+// full: Frag = Frag(
+//   parts = Vector("SELECT * FROM users WHERE status = ", " ORDER BY name"),
+//   params = Vector(DbString("active"))
+// )
+full.sql(SqlDialect.SQLite)
+// res9: String = "SELECT * FROM users WHERE status = ? ORDER BY name"
+```
+
+## Execution Methods
+
+All execution methods require an implicit `DbCon` (provided by `Transactor#connect` or `Transactor#transact`). They render the fragment to SQL, bind parameters, execute, and log the operation.
+
+**`query[A]`** — Execute SELECT and return all rows:
+
+```scala
+import zio.blocks.sql._
+import zio.blocks.schema.Schema
+
+case class User(id: Int, name: String)
+object User { implicit val schema: Schema[User] = Schema.derived }
+
+given DbCon = ???
+
+val users: List[User] = sql"SELECT id, name FROM users".query[User]
+```
+
+**`queryOne[A]`** — Execute SELECT and return at most one row:
+
+```scala
+import zio.blocks.sql._
+import zio.blocks.schema.Schema
+import zio.blocks.maybe.Maybe
+
+case class User(id: Int, name: String)
+object User { implicit val schema: Schema[User] = Schema.derived }
+
+given DbCon = ???
+
+val user: Maybe[User] = sql"SELECT id, name FROM users WHERE id = ${1}".queryOne[User]
+```
+
+**`queryLimit[A](n)`** — Execute SELECT and return up to n rows (fetched from Scala side):
+
+```scala
+import zio.blocks.sql._
+import zio.blocks.schema.Schema
+
+case class User(id: Int, name: String)
+object User { implicit val schema: Schema[User] = Schema.derived }
+
+given DbCon = ???
+
+val page: List[User] = sql"SELECT id, name FROM users ORDER BY name".queryLimit[User](10)
+```
+
+**`queryStream[A]`** — Execute SELECT and return rows as a chunked stream (`zio.blocks.streams.Stream`), batching `DefaultQueryChunkSize` (64) rows per chunk. Acquisition is lazy — nothing touches the connection until the first pull — so consume the stream within the scope that provides the `DbCon`; leaving `Transactor.connect`/`transact` closes the captured connection, and pulling afterwards fails.
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.sql._
+import zio.blocks.schema.Schema
+import zio.blocks.streams.Stream
+
+case class User(id: Int, name: String)
+object User { implicit val schema: Schema[User] = Schema.derived }
+
+given DbCon = ???
+
+val chunks: Stream[Throwable, Chunk[User]] =
+  sql"SELECT id, name FROM users".queryStream[User]
+val all: Either[Throwable, List[User]] = chunks.runCollect.map(_.toList.flatten)
+```
+
+**`queryChunked[A](n)`** — Like `queryStream`, but with an explicit batch size. The statement and result set are acquired lazily on the first pull and released when the stream is closed or fully drained; each chunk holds up to `n` rows, so memory stays bounded for large result sets. The same lifetime rule applies: consume the stream before the enclosing `Transactor.connect`/`transact` callback returns — afterwards the captured connection is closed and the first pull fails.
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.sql._
+import zio.blocks.schema.Schema
+import zio.blocks.streams.Stream
+
+case class User(id: Int, name: String)
+object User { implicit val schema: Schema[User] = Schema.derived }
+
+given DbCon = ???
+
+val batches: Stream[Throwable, Chunk[User]] =
+  sql"SELECT id, name FROM users".queryChunked[User](500)
+```
+
+**`update`** — Execute INSERT, UPDATE, or DELETE and return affected row count:
+
+```scala
+import zio.blocks.sql._
+
+given DbCon = ???
+
+val deleted: Int = sql"DELETE FROM users WHERE inactive = ${true}".update
+```
+
+**`updateReturningKeys[A]`** — Execute INSERT and return auto-generated primary key(s):
+
+```scala
+import zio.blocks.sql._
+
+given DbCon = ???
+
+val keys: List[Long] = sql"INSERT INTO users (name) VALUES (${"Alice"})".updateReturningKeys[Long]
+```