@zio.dev/zio-blocks 0.0.51 → 0.0.56

package/reference/sql/db-codec.md

@@ -78,7 +78,7 @@ import zio.blocks.schema.Schema
 case class User(id: Int, name: String, email: Option[String]) derives DbCodec
 
 val codec = DbCodec[User]
-// codec: DbCodec[User] = zio.blocks.sql.DbCodecDeriver$$anon$20@55869d8
+// codec: DbCodec[User] = zio.blocks.sql.DbCodecDeriver$$anon$10@28731048
 
 codec.columns
 // res1: IndexedSeq[String] = Vector("id", "name", "email")
@@ -100,7 +100,7 @@ val nullParams = codec.toDbValues(User(2, "Bob", None))
 // Adapt any codec to a newtype with transform — no full Schema needed
 case class UserId(value: Int)
 val userIdCodec: DbCodec[UserId] = DbCodec[Int].transform(UserId(_))(_.value)
-// userIdCodec: DbCodec[UserId] = zio.blocks.sql.DbCodec$$anon$1@2f13d28a
+// userIdCodec: DbCodec[UserId] = zio.blocks.sql.DbCodec$$anon$1@7c9318fc
 
 userIdCodec.columns
 // res3: IndexedSeq[String] = Vector("value")
@@ -173,13 +173,13 @@ object Product { implicit val schema: Schema[Product] = Schema.derived }
 // tags is stored as a JSON string in the "tags" column
 val tagsCodec: DbCodec[Tags] =
   DbCodec[String].transform(json => Tags(json.split(",").toList))(_.values.mkString(","))
-// tagsCodec: DbCodec[Tags] = zio.blocks.sql.DbCodec$$anon$1@3592645d
+// tagsCodec: DbCodec[Tags] = zio.blocks.sql.DbCodec$$anon$1@5596e273
 
 val productCodec: DbCodec[Product] =
   DbCodec.derivedWith[Product](
     _.instance(TypeId.of[Product], "tags", tagsCodec)
   )
-// productCodec: DbCodec[Product] = zio.blocks.sql.DbCodecDeriver$$anon$20@73120731
+// productCodec: DbCodec[Product] = zio.blocks.sql.DbCodecDeriver$$anon$10@34140b70
 
 productCodec.columns
 // res7: IndexedSeq[String] = Vector("id", "tags")
@@ -189,31 +189,31 @@ productCodec.columnCount
 
 ### `DbCodec.jsonb` — JSONB column codec
 
-`DbCodec.jsonb` creates a `DbCodec[A]` that stores and retrieves a value of type `A` as a JSON string in a single database column. Two overloads are available: one using an implicit `JsonSchemaCodec[A]` for the encode/decode pair, and one accepting explicit functions.
+`DbCodec.jsonb` creates a `DbCodec[A]` that stores and retrieves a value of type `A` as a JSON string in a single database column. Two overloads are available: one using an implicit `JsonCodec[A]` for the encode/decode pair, and one accepting explicit functions.
 
 ```scala
 object DbCodec {
-  def jsonb[A](using jsonCodec: JsonSchemaCodec[A]): DbCodec[A]
+  def jsonb[A](using jsonCodec: JsonCodec[A]): DbCodec[A]
   def jsonb[A](encode: A => String, decode: String => A): DbCodec[A]
 }
 ```
 
-The first overload requires a `JsonSchemaCodec[A]` (aliased from `zio.blocks.schema.json.JsonCodec`) in implicit scope:
+The first overload requires a `JsonCodec[A]` (`zio.blocks.schema.json.JsonCodec`) in implicit scope:
 
 ```scala
 import zio.blocks.sql._
 import zio.blocks.schema.Schema
-import zio.blocks.schema.json.{JsonCodec => JsonSchemaCodec, JsonCodecDeriver}
+import zio.blocks.schema.json.{JsonCodec, JsonCodecDeriver}
 
 case class Address(street: String, city: String)
 object Address {
-  implicit val schema: Schema[Address]             = Schema.derived
-  implicit val jsonCodec: JsonSchemaCodec[Address] = schema.deriving(JsonCodecDeriver).derive
+  implicit val schema: Schema[Address]         = Schema.derived
+  implicit val jsonCodec: JsonCodec[Address] = schema.deriving(JsonCodecDeriver).derive
 }
 
 // Address is stored as a JSON string in a single TEXT/JSONB column
 val codec: DbCodec[Address] = DbCodec.jsonb[Address]
-// codec: DbCodec[Address] = zio.blocks.sql.DbCodec$$anon$1@68d986d1
+// codec: DbCodec[Address] = zio.blocks.sql.DbCodec$$anon$1@43b1650c
 
 codec.columns
 // res10: IndexedSeq[String] = Vector("value")
@@ -223,7 +223,7 @@ codec.toDbValues(Address("Main St", "NYC"))
 // )
 ```
 
-Use the two-argument overload when you supply custom encode/decode logic instead of relying on `JsonSchemaCodec`:
+Use the two-argument overload when you supply custom encode/decode logic instead of relying on `JsonCodec`:
 
 ```scala
 import zio.blocks.sql._
@@ -235,7 +235,7 @@ val pointCodec: DbCodec[Point] = DbCodec.jsonb[Point](
   p => s"${p.x},${p.y}",
   s => { val parts = s.split(","); Point(parts(0).toDouble, parts(1).toDouble) }
 )
-// pointCodec: DbCodec[Point] = zio.blocks.sql.DbCodec$$anon$1@1144ae3c
+// pointCodec: DbCodec[Point] = zio.blocks.sql.DbCodec$$anon$1@2634e34a
 
 pointCodec.toDbValues(Point(1.0, 2.0))
 // res12: IndexedSeq[DbValue] = Vector(DbString("1.0,2.0"))
@@ -243,11 +243,11 @@ pointCodec.toDbValues(Point(1.0, 2.0))
 
 ### `DbCodec.jsonbOption` — Nullable JSONB column codec
 
-`DbCodec.jsonbOption` creates a `DbCodec[Option[A]]` that stores `Some(a)` as a JSON string and `None` as SQL `NULL`. Like `jsonb`, it has an implicit `JsonSchemaCodec[A]` overload and a two-argument overload:
+`DbCodec.jsonbOption` creates a `DbCodec[Option[A]]` that stores `Some(a)` as a JSON string and `None` as SQL `NULL`. Like `jsonb`, it has an implicit `JsonCodec[A]` overload and a two-argument overload:
 
 ```scala
 object DbCodec {
-  def jsonbOption[A](using jsonCodec: JsonSchemaCodec[A]): DbCodec[Option[A]]
+  def jsonbOption[A](using jsonCodec: JsonCodec[A]): DbCodec[Option[A]]
   def jsonbOption[A](encode: A => String, decode: String => A): DbCodec[Option[A]]
 }
 ```
@@ -256,11 +256,11 @@ The codec delegates to `DbCodec[Option[String]]` and applies the JSON encode/dec
 
 ```scala
 import zio.blocks.sql._
-import zio.blocks.schema.json.{JsonCodec => JsonSchemaCodec}
+import zio.blocks.schema.json.JsonCodec
 
-// Assume JsonSchemaCodec[Address] is in scope from the previous example
+// Assume JsonCodec[Address] is in scope from the previous example
 val nullableCodec: DbCodec[Option[Address]] = DbCodec.jsonbOption[Address]
-// nullableCodec: DbCodec[Option[Address]] = zio.blocks.sql.DbCodec$$anon$1@4c7b464f
+// nullableCodec: DbCodec[Option[Address]] = zio.blocks.sql.DbCodec$$anon$1@5a2ab2eb
 
 nullableCodec.toDbValues(Some(Address("Elm St", "LA")))
 // res13: IndexedSeq[DbValue] = Vector(
@@ -293,7 +293,7 @@ object ProductId {
 
 // DbCodec[ProductId] is resolved automatically — no explicit given needed
 val codec = DbCodec[ProductId]
-// codec: DbCodec[ProductId] = zio.blocks.sql.DbCodec$$anon$6@3261707e
+// codec: DbCodec[ProductId] = zio.blocks.sql.DbCodec$$anon$6@7ba8fb55
 codec.columns
 // res16: IndexedSeq[String] = Vector("value")
 ```
@@ -344,7 +344,7 @@ case class Order(id: Long, status: String) derives DbCodec
 
 // Summon the derived codec
 val codec: DbCodec[Order] = DbCodec[Order]
-// codec: DbCodec[Order] = zio.blocks.sql.DbCodecDeriver$$anon$20@678700e1
+// codec: DbCodec[Order] = zio.blocks.sql.DbCodecDeriver$$anon$10@5b7defec
 codec.columns
 // res19: IndexedSeq[String] = Vector("id", "status")
 ```
@@ -560,7 +560,7 @@ import zio.blocks.sql._
 case class Item(id: Int, name: String, price: Option[BigDecimal]) derives DbCodec
 
 val codec = DbCodec[Item]
-// codec: DbCodec[Item] = zio.blocks.sql.DbCodecDeriver$$anon$20@1ffebf02
+// codec: DbCodec[Item] = zio.blocks.sql.DbCodecDeriver$$anon$10@25059cd7
 
 codec.toDbValues(Item(1, "Widget", Some(BigDecimal("9.99"))))
 // res29: IndexedSeq[DbValue] = Vector(
@@ -595,7 +595,7 @@ case class ProductId(value: String)
 // Adapt the String codec to ProductId without a Schema
 val productIdCodec: DbCodec[ProductId] =
   DbCodec[String].transform(ProductId(_))(_.value)
-// productIdCodec: DbCodec[ProductId] = zio.blocks.sql.DbCodec$$anon$1@95d8a43
+// productIdCodec: DbCodec[ProductId] = zio.blocks.sql.DbCodec$$anon$1@41471826
 
 productIdCodec.columns
 // res32: IndexedSeq[String] = Vector("value")

package/reference/sql/db-con.md

@@ -46,7 +46,7 @@ object User {
 }
 
 val tx: Transactor = JdbcTransactor.fromUrl("jdbc:sqlite::memory:", SqlDialect.SQLite)
-// tx: Transactor = zio.blocks.sql.JdbcTransactor@4c1ffa3c
+// tx: Transactor = zio.blocks.sql.JdbcTransactor@1fecb11a
 
 // DbCon is supplied automatically by connect — no explicit argument needed
 tx.connect {
@@ -179,7 +179,7 @@ The following example shows reading the dialect from a context to render a `Frag
 import zio.blocks.sql._
 
 val tx: Transactor = JdbcTransactor.fromUrl("jdbc:sqlite::memory:", SqlDialect.SQLite)
-// tx: Transactor = zio.blocks.sql.JdbcTransactor@606f8c9a
+// tx: Transactor = zio.blocks.sql.JdbcTransactor@51223a09
 
 tx.connect {
   val frag = sql"SELECT id FROM users WHERE id = ${42}"
@@ -209,7 +209,7 @@ val loggingLogger: SqlLogger = new SqlLogger {
   def onError(event: SqlLogger.ErrorEvent): Unit =
     println(s"ERR [${event.duration.toMillis} ms]: ${event.sql} — ${event.error.getMessage}")
 }
-// loggingLogger: SqlLogger = repl.MdocSession$MdocApp7$$anon$9@1d96b35a
+// loggingLogger: SqlLogger = repl.MdocSession$MdocApp7$$anon$9@192cce5a
 
 val tx: Transactor =
   new JdbcTransactor(
@@ -217,7 +217,7 @@ val tx: Transactor =
     SqlDialect.SQLite,
     loggingLogger
   )
-// tx: Transactor = zio.blocks.sql.JdbcTransactor@7abee0ec
+// tx: Transactor = zio.blocks.sql.JdbcTransactor@7407235d
 
 tx.connect {
   // Every Frag execution notifies loggingLogger automatically

package/reference/sql/db-connection.md

@@ -133,7 +133,7 @@ transactor.connect {
 import zio.blocks.sql._
 
 val transactor: Transactor = JdbcTransactor.fromUrl("jdbc:sqlite::memory:", SqlDialect.SQLite)
-// transactor: Transactor = zio.blocks.sql.JdbcTransactor@7d102738
+// transactor: Transactor = zio.blocks.sql.JdbcTransactor@4f5f053
 
 var capturedCon: DbConnection = null
 // capturedCon: DbConnection = null

package/reference/sql/db-param.md

@@ -47,7 +47,7 @@ val active  = true
 // active: Boolean = true
 val query   = sql"SELECT * FROM users WHERE id = $userId AND active = $active"
 // query: Frag = Frag(
-//   parts = ArraySeq("SELECT * FROM users WHERE id = ", " AND active = ", ""),
+//   parts = Vector("SELECT * FROM users WHERE id = ", " AND active = ", ""),
 //   params = Vector(DbInt(42), DbBoolean(true))
 // )
 query.params

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

@@ -58,13 +58,15 @@ trait DbResultReader {
   // Other types
   def getUUID(index: Int): java.util.UUID
   def getUUID(label: String): java.util.UUID
-  def getArray(index: Int): java.sql.Array   // default: throws UnsupportedOperationException
-  def getArray(label: String): java.sql.Array // default: throws UnsupportedOperationException
+  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
 }
 ```
 

package/reference/sql/db-tx.md

@@ -12,26 +12,28 @@ keywords:
   - "JDBC Transaction Lifecycle"
 ---
 
-`DbTx` is a marker trait in the `zio-blocks-sql` module that extends `DbCon` to signal a transactional execution scope. It declares no members of its own — its distinct type is what instructs `Transactor#transact` to disable auto-commit, commit the connection on success, and roll back on any thrown exception. 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 block exits, whether it commits, rolls back, or throws.
+`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 marker** — A `DbTx` value in scope guarantees the underlying JDBC connection has auto-commit disabled.
-- **Commit-on-success semantics** — The `Transactor` commits the connection when the `transact` block returns normally.
-- **Rollback-on-failure semantics** — Any uncaught exception causes the `Transactor` to roll back the connection before re-throwing.
+- **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
-```
-
-Every context member that `DbTx` exposes is inherited from `DbCon`, which declares the three fields every SQL operation consumes:
+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
 
-```scala
-trait DbCon {
+  // inherited from DbCon
   def connection: DbConnection
-  def dialect:    SqlDialect
-  def logger:     SqlLogger
+  def dialect: SqlDialect
+  def logger: SqlLogger
 }
 ```
 
@@ -49,9 +51,9 @@ object User {
 }
 
 val repo = Repo.derived[User, Int]("users", "id", _.id)
-// repo: Repo[User, Int] = zio.blocks.sql.Repo$DerivedRepo@1b21124
+// repo: Repo[User, Int] = zio.blocks.sql.Repo$DerivedRepo@789742a3
 val tx   = JdbcTransactor.fromUrl("jdbc:sqlite::memory:", SqlDialect.SQLite)
-// tx: JdbcTransactor = zio.blocks.sql.JdbcTransactor@1583ec4c
+// tx: JdbcTransactor = zio.blocks.sql.JdbcTransactor@5276be33
 
 // On normal return: transaction commits and connection closes.
 // On any exception: transaction rolls back, then the exception propagates.
@@ -80,3 +82,33 @@ tx.transact {
 //   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/ddl.md

@@ -33,7 +33,7 @@ Create a `ColumnDef` for each column, then pass them to `Ddl.createTable`:
 import zio.blocks.sql._
 
 val transactor: Transactor = JdbcTransactor.fromUrl("jdbc:sqlite::memory:", SqlDialect.SQLite)
-// transactor: Transactor = zio.blocks.sql.JdbcTransactor@1bf2e7e
+// transactor: Transactor = zio.blocks.sql.JdbcTransactor@13b61c12
 
 val columns = IndexedSeq(
   ColumnDef("id",         "INTEGER", nullable = false),

package/reference/sql/frag.md

@@ -9,7 +9,7 @@ keywords:
   - "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`.
+`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.
 
@@ -33,6 +33,8 @@ object 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]
   }
@@ -86,7 +88,7 @@ val userId = 42
 // userId: Int = 42
 val frag = sql"SELECT * FROM users WHERE id = $userId"
 // frag: Frag = Frag(
-//   parts = ArraySeq("SELECT * FROM users WHERE id = ", ""),
+//   parts = Vector("SELECT * FROM users WHERE id = ", ""),
 //   params = Vector(DbInt(42))
 // )
 frag.params
@@ -98,7 +100,7 @@ frag.params
 ```scala
 val query = sql"SELECT * FROM users" ++ Frag.literal(" ORDER BY name")
 // query: Frag = Frag(
-//   parts = ArraySeq("SELECT * FROM users ORDER BY name"),
+//   parts = Vector("SELECT * FROM users ORDER BY name"),
 //   params = Vector()
 // )
 query.sql(SqlDialect.SQLite)
@@ -146,12 +148,12 @@ val hasFilter = true
 // hasFilter: Boolean = true
 val where = if (hasFilter) sql" WHERE active = ${true}" else Frag.empty
 // where: Frag = Frag(
-//   parts = ArraySeq(" WHERE active = ", ""),
+//   parts = Vector(" WHERE active = ", ""),
 //   params = Vector(DbBoolean(true))
 // )
 val query = sql"SELECT * FROM users" ++ where
 // query: Frag = Frag(
-//   parts = ArraySeq("SELECT * FROM users WHERE active = ", ""),
+//   parts = Vector("SELECT * FROM users WHERE active = ", ""),
 //   params = Vector(DbBoolean(true))
 // )
 query.sql(SqlDialect.SQLite)
@@ -166,13 +168,10 @@ import zio.blocks.sql._
 val status = "active"
 // status: String = "active"
 val base   = sql"SELECT * FROM users"
-// base: Frag = Frag(
-//   parts = ArraySeq("SELECT * FROM users"),
-//   params = Vector()
-// )
+// base: Frag = Frag(parts = Vector("SELECT * FROM users"), params = Vector())
 val where  = sql" WHERE status = $status"
 // where: Frag = Frag(
-//   parts = ArraySeq(" WHERE status = ", ""),
+//   parts = Vector(" WHERE status = ", ""),
 //   params = Vector(DbString("active"))
 // )
 val order  = Frag.literal(" ORDER BY name")
@@ -233,6 +232,41 @@ 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

package/reference/sql/index.md

@@ -39,10 +39,10 @@ The core SQL module and the ZIO integration module publish separately. Add the a
 ```scala
 // Core SQL module (cross-built for JVM and Scala.js; the JDBC-backed
 // JdbcTransactor implementation itself is JVM-only)
-libraryDependencies += "dev.zio" %% "zio-blocks-sql" % "0.0.51"
+libraryDependencies += "dev.zio" %% "zio-blocks-sql" % "0.0.56"
 
 // ZIO integration (lifts JDBC into ZIO effects; JVM-only)
-libraryDependencies += "dev.zio" %% "zio-blocks-sql-zio" % "0.0.51"
+libraryDependencies += "dev.zio" %% "zio-blocks-sql-zio" % "0.0.56"
 ```
 
 Both modules require a JDBC driver on the classpath (for example, `org.xerial:sqlite-jdbc` for SQLite or `org.postgresql:postgresql` for PostgreSQL). Swap the JDBC URL and `SqlDialect` constant to switch databases.
@@ -144,9 +144,9 @@ object User {
 
 // 1. Create transactor and repository
 val tx   = JdbcTransactor.fromUrl("jdbc:sqlite::memory:", SqlDialect.SQLite)
-// tx: JdbcTransactor = zio.blocks.sql.JdbcTransactor@3fe7357a
+// tx: JdbcTransactor = zio.blocks.sql.JdbcTransactor@ec75b64
 val repo = Repo.derived[User, Int]("users", "id", _.id)
-// repo: Repo[User, Int] = zio.blocks.sql.Repo$DerivedRepo@4206125b
+// repo: Repo[User, Int] = zio.blocks.sql.Repo$DerivedRepo@41c4138d
 
 // 2. Set up schema and run a transactional workflow
 tx.transact {
@@ -200,7 +200,7 @@ object BlogPost {
 }
 
 val repo = Repo.derived[BlogPost, Int]("post_id", _.id)
-// repo: Repo[BlogPost, Int] = zio.blocks.sql.Repo$DerivedRepo@243d4111
+// repo: Repo[BlogPost, Int] = zio.blocks.sql.Repo$DerivedRepo@6abcba30
 repo.table.name
 // res3: String = "blog_post"
 repo.table.codec.columns
@@ -269,7 +269,7 @@ val active: Option[Boolean] = Some(true)
 val frag =
   sql"SELECT * FROM users WHERE id = $userId AND name LIKE $namePattern AND active = $active"
 // frag: Frag = Frag(
-//   parts = ArraySeq(
+//   parts = Vector(
 //     "SELECT * FROM users WHERE id = ",
 //     " AND name LIKE ",
 //     " AND active = ",
@@ -298,7 +298,7 @@ case class Order(id: Int, tags: List[String], metadata: Map[String, String]) der
 
 // `tags` and `metadata` are encoded via DbCodec.jsonb when read/written through Frag/Repo
 val codec = DbCodec[Order]
-// codec: DbCodec[Order] = zio.blocks.sql.DbCodecDeriver$$anon$20@10cf0d2d
+// codec: DbCodec[Order] = zio.blocks.sql.DbCodecDeriver$$anon$10@4d46abe5
 codec.columns
 // res12: IndexedSeq[String] = Vector("id", "tags", "metadata")
 ```

package/reference/sql/repo.md

@@ -49,9 +49,9 @@ object User {
 
 // All SQL is generated here, once, from User's Schema.
 val repo = Repo.derived[User, Int]("users", "id", _.id)
-// repo: Repo[User, Int] = zio.blocks.sql.Repo$DerivedRepo@16e9cebd
+// repo: Repo[User, Int] = zio.blocks.sql.Repo$DerivedRepo@c90e314
 val tx   = JdbcTransactor.fromUrl("jdbc:sqlite::memory:", SqlDialect.SQLite)
-// tx: JdbcTransactor = zio.blocks.sql.JdbcTransactor@aae0228
+// tx: JdbcTransactor = zio.blocks.sql.JdbcTransactor@7c7933b1
 
 tx.transact {
   repo.table.createTable(summon[DbTx].dialect).update // CREATE TABLE IF NOT EXISTS users …
@@ -116,7 +116,7 @@ object Article {
 }
 
 val repo = Repo.derived[Article, Int]("id", _.id)
-// repo: Repo[Article, Int] = zio.blocks.sql.Repo$DerivedRepo@2f907618
+// repo: Repo[Article, Int] = zio.blocks.sql.Repo$DerivedRepo@4462dfed
 repo.table.name
 // res3: String = "article"
 repo.table.codec.columns
@@ -150,7 +150,7 @@ object OrderLine {
 
 // Overrides the default "order_line" table name with the legacy one
 val repo = Repo.derived[OrderLine, Int]("tbl_order_lines", "line_id", _.lineId)
-// repo: Repo[OrderLine, Int] = zio.blocks.sql.Repo$DerivedRepo@2bc241ca
+// repo: Repo[OrderLine, Int] = zio.blocks.sql.Repo$DerivedRepo@7cda6782
 repo.table.name
 // res6: String = "tbl_order_lines"
 ```
@@ -185,7 +185,7 @@ object Tag {
 
 // Inspects Tag's Schema, finds the unique Long field "id", maps it to column "id"
 val repo = Repo.derived[Tag, Long]
-// repo: Repo[Tag, Long] = zio.blocks.sql.Repo$DerivedRepo@589393f1
+// repo: Repo[Tag, Long] = zio.blocks.sql.Repo$DerivedRepo@3cdba0a6
 repo.idColumn
 // res8: String = "id"
 ```
@@ -234,7 +234,7 @@ The read operations query the database without modifying it. `Repo#all`, `Repo#f
 
 #### `all` — Retrieve all rows
 
-`Repo#all` executes `SELECT <columns> FROM <table>` and decodes every result-set row into an `E` using the entity's `DbCodec`, returning all rows as a `List[E]` in database-native order.
+`Repo#all` executes `SELECT "<columns>" FROM "<table>"` and decodes every result-set row into an `E` using the entity's `DbCodec`, returning all rows as a `List[E]` in database-native order.
 
 ```scala
 class Repo[E, ID] {
@@ -264,7 +264,7 @@ val users: List[User] = repo.all
 
 #### `findAll` — Retrieve rows by a set of primary keys
 
-`Repo#findAll` executes `SELECT <columns> FROM <table> WHERE <idColumn> IN (...)` for the given IDs and decodes every matching row into an `E`. It returns an empty `List` immediately, without executing any SQL, when `ids` is empty.
+`Repo#findAll` executes `SELECT "<columns>" FROM "<table>" WHERE "<idColumn>" IN (...)` for the given IDs and decodes every matching row into an `E`. It returns an empty `List` immediately, without executing any SQL, when `ids` is empty.
 
 ```scala
 class Repo[E, ID] {
@@ -289,7 +289,7 @@ val users: List[User] = repo.findAll(List(1, 2, 3))
 
 #### `find` — Find a row by primary key
 
-`Repo#find` executes `SELECT <columns> FROM <table> WHERE <idColumn> = ?`, binding the ID through `idCodec`. It returns `Maybe.absent` if no row with the given key exists, or `Maybe(entity)` if a row is found.
+`Repo#find` executes `SELECT "<columns>" FROM "<table>" WHERE "<idColumn>" = ?`, binding the ID through `idCodec`. It returns `Maybe.absent` if no row with the given key exists, or `Maybe(entity)` if a row is found.
 
 ```scala
 class Repo[E, ID] {
@@ -340,7 +340,7 @@ val exists: Boolean = repo.exists(99)
 
 #### `count` — Count all rows
 
-`Repo#count` executes `SELECT COUNT(*) FROM <table>` and returns the row count as a `Long`. The result is `0L` when the table is empty.
+`Repo#count` executes `SELECT COUNT(*) FROM "<table>"` and returns the row count as a `Long`. The result is `0L` when the table is empty.
 
 ```scala
 class Repo[E, ID] {
@@ -369,7 +369,7 @@ The write operations insert, update, or delete rows in the database. `Repo#inser
 
 #### `insert` — Insert a single entity
 
-`Repo#insert` encodes the entity with `DbCodec[E]` and executes `INSERT INTO <table> (<columns>) VALUES (?, …, ?)`, returning the number of affected rows — normally 1 on success.
+`Repo#insert` encodes the entity with `DbCodec[E]` and executes `INSERT INTO "<table>" ("<columns>") VALUES (?, …, ?)`, returning the number of affected rows — normally 1 on success.
 
 ```scala
 class Repo[E, ID] {
@@ -456,7 +456,7 @@ val rowsAffected: Int = repo.insertBatch(users)
 
 #### `insertAll` — Multi-row insert returning primary keys
 
-`Repo#insertAll` assembles a single `INSERT INTO <table> (<columns>) VALUES (?, …, ?), …, (?, …, ?)` statement covering all rows and executes it in one database round-trip. It then extracts the primary keys from the input entities via `getId` and returns them in input order.
+`Repo#insertAll` assembles a single `INSERT INTO "<table>" ("<columns>") VALUES (?, …, ?), …, (?, …, ?)` statement covering all rows and executes it in one database round-trip. It then extracts the primary keys from the input entities via `getId` and returns them in input order.
 
 ```scala
 class Repo[E, ID] {
@@ -490,7 +490,7 @@ val ids: Seq[Int] = repo.insertAll(newUsers)
 
 #### `update` — Update an entity's non-ID columns
 
-`Repo#update` executes `UPDATE <table> SET <col1> = ?, …, <colN> = ? WHERE <idColumn> = ?` for all non-ID columns of the entity, identifying the target row by its primary key. It returns the number of affected rows — 0 when no row with that ID exists.
+`Repo#update` executes `UPDATE "<table>" SET "<col1>" = ?, …, "<colN>" = ? WHERE "<idColumn>" = ?` for all non-ID columns of the entity, identifying the target row by its primary key. It returns the number of affected rows — 0 when no row with that ID exists.
 
 ```scala
 class Repo[E, ID] {
@@ -519,7 +519,7 @@ val rowsAffected: Int = repo.update(User(1, "Alice Smith", "alice.smith@example.
 
 #### `delete` — Delete by primary key
 
-`Repo#delete` executes `DELETE FROM <table> WHERE <idColumn> = ?`, binding the ID through `idCodec`. It returns the number of deleted rows — 0 if no row with the given ID exists.
+`Repo#delete` executes `DELETE FROM "<table>" WHERE "<idColumn>" = ?`, binding the ID through `idCodec`. It returns the number of deleted rows — 0 if no row with the given ID exists.
 
 ```scala
 class Repo[E, ID] {
@@ -546,7 +546,7 @@ To delete by an entity value rather than a bare ID, extract the key with `getId`
 
 #### `deleteAll` — Delete rows by a set of primary keys
 
-`Repo#deleteAll` executes `DELETE FROM <table> WHERE <idColumn> IN (...)` for the given IDs in a single round-trip and returns the total number of deleted rows. It returns `0` immediately, without executing any SQL, when `ids` is empty.
+`Repo#deleteAll` executes `DELETE FROM "<table>" WHERE "<idColumn>" IN (...)` for the given IDs in a single round-trip and returns the total number of deleted rows. It returns `0` immediately, without executing any SQL, when `ids` is empty.
 
 ```scala
 class Repo[E, ID] {
@@ -571,7 +571,7 @@ val rowsAffected: Int = repo.deleteAll(List(1, 2, 3))
 
 #### `clear` — Remove all rows
 
-`Repo#clear` executes `DELETE FROM <table>` without a `WHERE` clause and returns the number of deleted rows.
+`Repo#clear` executes `DELETE FROM "<table>"` without a `WHERE` clause and returns the number of deleted rows.
 
 ```scala
 class Repo[E, ID] {

package/reference/sql/sql-dialect.md

@@ -42,7 +42,7 @@ The dialect is available through `DbCon#dialect` inside a transaction:
 import zio.blocks.sql._
 
 val tx = JdbcTransactor.fromUrl("jdbc:sqlite::memory:", SqlDialect.SQLite)
-// tx: JdbcTransactor = zio.blocks.sql.JdbcTransactor@f150688
+// tx: JdbcTransactor = zio.blocks.sql.JdbcTransactor@4f23e58f
 
 tx.connect {
   val dialect = summon[DbCon].dialect

package/reference/sql/sql-logger.md

@@ -38,7 +38,7 @@ val myLogger: SqlLogger = new SqlLogger {
   def onError(event: SqlLogger.ErrorEvent): Unit =
     println(s"FAIL: ${event.error.getMessage}")
 }
-// myLogger: SqlLogger = repl.MdocSession$MdocApp0$$anon$1@1b9203b8
+// myLogger: SqlLogger = repl.MdocSession$MdocApp0$$anon$1@3ea7a988
 ```
 
 Pass the logger when creating a `JdbcTransactor`: