@zio.dev/zio-blocks 0.0.33 → 0.0.51

package/reference/sql/db-con.md

@@ -0,0 +1,271 @@
+---
+id: db-con
+title: "DbCon"
+description: "Reference for DbCon, the implicit execution context in the sql module carrying a DbConnection, SqlDialect, and SqlLogger through SQL operations."
+keywords:
+  - "DbCon implicit context"
+  - "Transactor connection scope"
+  - "DbTx transaction scope"
+  - "SqlDialect dialect selection"
+  - "SqlLogger query observability"
+  - "sql module context threading"
+  - "DbConnection JDBC abstraction"
+---
+
+`DbCon` is the implicit execution context that threads database connection state through every SQL operation in the `sql` module. It is a plain trait with three abstract members — `connection`, `dialect`, and `logger` — and carries no type parameters:
+
+```scala
+trait DbCon {
+  def connection: DbConnection
+  def dialect: SqlDialect
+  def logger: SqlLogger
+}
+```
+
+Application code never constructs a `DbCon` directly. Instead, `Transactor#connect` and `Transactor#transact` each create one internally and supply it as a Scala 3 context parameter (`?=>`) to the block they receive. 
+
+All `Frag` execution methods (`query`, `queryOne`, `queryLimit`, `update`, `updateReturningKeys`) and all `Repo` CRUD methods (`all`, `find`, `insert`, `update`, `delete`, and friends) require an implicit `DbCon` in scope — so any code that runs inside a `Transactor#connect` or `Transactor#transact` block automatically has everything it needs to execute SQL.
+
+Key properties:
+- **Implicit context type** — carries the active database session without explicit parameter threading.
+- **Three concrete members** — `connection` (the active `DbConnection`), `dialect` (the `SqlDialect`), and `logger` (the `SqlLogger`).
+- **Extended by `DbTx`** — `DbTx` is a subtype of `DbCon` that marks transactional scope; any method that accepts `DbCon` also accepts `DbTx`.
+- **Lifetime managed by `Transactor`** — the connection is closed when the enclosing `connect` or `transact` block returns, whether it succeeds or throws.
+
+## Usage
+
+The following example shows how `DbCon` is obtained from a `Transactor`, how the context is propagated into helper methods, and how the three members can be accessed when needed:
+
+```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
+}
+
+val tx: Transactor = JdbcTransactor.fromUrl("jdbc:sqlite::memory:", SqlDialect.SQLite)
+// tx: Transactor = zio.blocks.sql.JdbcTransactor@4c1ffa3c
+
+// DbCon is supplied automatically by connect — no explicit argument needed
+tx.connect {
+  // Frag execution picks up the given DbCon implicitly
+  Frag.literal("CREATE TABLE users (id INTEGER NOT NULL, name TEXT NOT NULL)").update
+  sql"INSERT INTO users (id, name) VALUES (${1}, ${"Alice"})".update
+  val users: List[User] = sql"SELECT id, name FROM users".query[User]
+  // Access the context members directly when needed
+  val dialectName: String = summon[DbCon].dialect.toString
+  (users, dialectName)
+}
+// res1: Tuple2[List[User], String] = (
+//   List(User(id = 1, name = "Alice")),
+//   "SQLite"
+// )
+```
+
+## Entry Points
+
+`DbCon` is never instantiated by application code. A `Transactor` creates and supplies the instance automatically. There are two entry points depending on whether transactional behaviour is needed.
+
+### `Transactor#connect` — Non-transactional connection scope
+
+`Transactor#connect` acquires a JDBC connection from the underlying source, wraps it in a `DbCon`, and calls the provided context function. The connection is closed when the block returns, whether it completes normally or throws. Auto-commit remains at the driver default (enabled for most JDBC drivers), so each statement issued inside the block commits independently.
+
+The signature from `Transactor` is:
+
+```scala
+trait Transactor {
+  def connect[A](f: DbCon ?=> A): A
+}
+```
+
+The following example shows a non-transactional read that uses the supplied `DbCon` to execute a query:
+
+```scala
+import zio.blocks.sql._
+
+val tx: Transactor = JdbcTransactor.fromUrl("jdbc:sqlite::memory:", SqlDialect.SQLite)
+
+// The `DbCon` binding is supplied by `connect` — no manual construction
+val names: List[String] = tx.connect {
+  sql"SELECT name FROM users ORDER BY name".query[String]
+}
+```
+
+:::caution
+Do not capture the `DbCon` value or the `DbConnection` it contains and use them outside the `connect` block. The connection is closed when the block returns, and any statement prepared or executed on it afterward will throw.
+:::
+
+### `Transactor#transact` — Transactional connection scope
+
+`Transactor#transact` acquires a connection, disables auto-commit, and supplies a `DbTx` context — a subtype of `DbCon` — to the block. On normal return the transaction commits; on any thrown exception it rolls back. The connection is closed after commit or rollback. Because `DbTx extends DbCon`, all `Frag` and `Repo` methods that accept `DbCon` work unchanged inside `transact`.
+
+The signature from `Transactor` is:
+
+```scala
+trait Transactor {
+  def transact[A](f: DbTx ?=> A): A
+}
+```
+
+The following example shows a transactional write that inserts two rows atomically — if the second insert throws, the first is rolled back:
+
+```scala
+import zio.blocks.sql._
+
+val tx: Transactor = JdbcTransactor.fromUrl("jdbc:sqlite::memory:", SqlDialect.SQLite)
+
+tx.transact {
+  // Both inserts commit together; an exception rolls back both
+  sql"INSERT INTO users (id, name) VALUES (${1}, ${"Alice"})".update
+  sql"INSERT INTO users (id, name) VALUES (${2}, ${"Bob"})".update
+}
+```
+
+## Core Operations
+
+`DbCon` exposes three read-only members. They are rarely accessed directly in application code — the `Transactor` configures them at construction time and `Frag` / `Repo` consume them implicitly — but they become useful when integrating with lower-level JDBC abstractions, logging frameworks, or custom dialect rendering.
+
+### Context Access
+
+The three context-access members return the `DbConnection`, `SqlDialect`, and `SqlLogger` held by the current `DbCon` instance.
+
+#### `DbCon#connection` — Underlying JDBC-abstraction connection
+
+`DbCon#connection` returns the `DbConnection` wrapping the active JDBC `java.sql.Connection`. `DbConnection` exposes `prepareStatement`, `prepareStatementReturningKeys`, transaction-control methods, and `close`. It is consumed internally by every `Frag` and `Repo` operation that executes a statement. Access it directly only when you need to drop below the `Frag` layer to a raw prepared statement.
+
+```scala
+trait DbCon {
+  def connection: DbConnection
+}
+```
+
+The following example shows how to retrieve the `DbConnection` and use it to execute a raw prepared statement — useful for operations that the `Frag` API does not cover directly:
+
+```scala
+import zio.blocks.sql._
+
+val tx: Transactor = JdbcTransactor.fromUrl("jdbc:sqlite::memory:", SqlDialect.SQLite)
+
+tx.connect {
+  val conn: DbConnection = summon[DbCon].connection
+  val ps = conn.prepareStatement("SELECT COUNT(*) FROM users")
+  try {
+    val rs = ps.executeQuery()
+    try { rs.next(); rs.reader.getInt(1) }
+    finally rs.close()
+  } finally ps.close()
+}
+```
+
+:::caution
+Never call `connection.close()` manually. The `Transactor` closes the connection when the enclosing `connect` or `transact` block finishes, whether it returns normally or throws. Closing the connection early will cause all subsequent statements in the block to fail.
+:::
+
+#### `DbCon#dialect` — SQL dialect for fragment rendering
+
+`DbCon#dialect` returns the `SqlDialect` used to render `Frag` values to parameterized SQL strings. Every `Frag` execution method calls `frag.sql(dialect)` internally to produce the driver-specific SQL before binding parameters. The dialect also governs how DDL type names are spelled when generating `CREATE TABLE` statements from `Table#createTable`.
+
+```scala
+trait DbCon {
+  def dialect: SqlDialect
+}
+```
+
+The following example shows reading the dialect from a context to render a `Frag` explicitly — for instance, to log the SQL before execution:
+
+```scala
+import zio.blocks.sql._
+
+val tx: Transactor = JdbcTransactor.fromUrl("jdbc:sqlite::memory:", SqlDialect.SQLite)
+// tx: Transactor = zio.blocks.sql.JdbcTransactor@606f8c9a
+
+tx.connect {
+  val frag = sql"SELECT id FROM users WHERE id = ${42}"
+  frag.sql(summon[DbCon].dialect)
+}
+// res6: String = "SELECT id FROM users WHERE id = ?"
+```
+
+#### `DbCon#logger` — Query execution logger
+
+`DbCon#logger` returns the `SqlLogger` that the `Transactor` was configured with. After each successful statement `SqlLogger#onSuccess` receives the rendered SQL, the parameter list, the execution duration, and the affected-row count. After a failed statement `SqlLogger#onError` receives the same information plus the thrown exception. The default implementation — `SqlLogger.noop` — discards all events; replace it with a custom `SqlLogger` to integrate with your preferred logging framework.
+
+```scala
+trait DbCon {
+  def logger: SqlLogger
+}
+```
+
+The following example shows passing a logging `SqlLogger` to `JdbcTransactor` so that every query executed inside `connect` or `transact` is recorded:
+
+```scala
+import zio.blocks.sql._
+
+val loggingLogger: SqlLogger = new SqlLogger {
+  def onSuccess(event: SqlLogger.SuccessEvent): Unit =
+    println(s"OK [${event.duration.toMillis} ms, ${event.rowCount} rows]: ${event.sql}")
+  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
+
+val tx: Transactor =
+  new JdbcTransactor(
+    () => java.sql.DriverManager.getConnection("jdbc:sqlite::memory:"),
+    SqlDialect.SQLite,
+    loggingLogger
+  )
+// tx: Transactor = zio.blocks.sql.JdbcTransactor@7abee0ec
+
+tx.connect {
+  // Every Frag execution notifies loggingLogger automatically
+  Frag.literal("SELECT 1").query[Int]
+}
+// OK [0 ms, 1 rows]: SELECT 1
+// res8: List[Int] = List(1)
+```
+
+## Transactional Scope — `DbTx`
+
+`DbTx` is the only subtype of `DbCon`. It is a marker trait — it adds no new members — whose sole purpose is to distinguish code that runs inside `Transactor#transact` from code that runs inside `Transactor#connect` at the type level:
+
+```scala
+trait DbTx extends DbCon
+```
+
+Because `DbTx` has no additional members, it exists purely to make the transactional / non-transactional boundary visible in method signatures. A method that requires `DbTx` cannot be called from a `connect` block, but a method that requires `DbCon` can be called from either. This asymmetry is enforced by the compiler: `DbTx <: DbCon` so `DbTx` satisfies a `DbCon` requirement, but a plain `DbCon` does not satisfy a `DbTx` requirement.
+
+The following example illustrates how to write a helper method that is restricted to transactional scope:
+
+```scala
+import zio.blocks.sql._
+
+// This helper compiles only inside a `transact` block, never inside `connect`
+def insertUser(id: Int, name: String)(using DbTx): Unit = {
+  sql"INSERT INTO users (id, name) VALUES ($id, $name)".update
+  ()
+}
+
+val tx: Transactor = JdbcTransactor.fromUrl("jdbc:sqlite::memory:", SqlDialect.SQLite)
+
+tx.transact {
+  insertUser(1, "Alice") // OK — DbTx satisfies the `using DbTx` requirement
+}
+
+// tx.connect {
+//   insertUser(1, "Alice") // Compile error — DbCon does not satisfy `using DbTx`
+// }
+```
+
+When a helper only reads data and should work in both contexts, declare it with `using DbCon`:
+
+```scala
+import zio.blocks.sql._
+import zio.blocks.maybe.Maybe
+
+// Usable inside both `connect` and `transact` blocks
+def findUser(id: Int)(using DbCon): Maybe[String] =
+  sql"SELECT name FROM users WHERE id = $id".queryOne[String]
+```

package/reference/sql/db-connection.md

@@ -0,0 +1,153 @@
+---
+id: db-connection
+title: "DbConnection"
+description: "The JDBC Connection abstraction in the sql module"
+keywords:
+  - "DbConnection JDBC abstraction"
+  - "prepareStatement SQL"
+  - "DbPreparedStatement executeQuery"
+  - "DbResultSet result reading"
+  - "transaction control commit rollback"
+  - "AutoCloseable connection lifecycle"
+  - "Transactor connection management"
+---
+
+`DbConnection` is a `trait` that extends `AutoCloseable` and abstracts over a JDBC `java.sql.Connection`. It exposes the minimum surface needed to prepare statements, control transaction boundaries, and query connection state. 
+
+It is part of a three-tier abstraction:
+- `DbConnection` manages the connection itself
+- `DbPreparedStatement` executes statements with parameters
+- `DbResultSet` reads result rows
+
+## Core API
+
+Here is the core API which `DbConnection` exposes:
+
+```scala
+trait DbConnection extends AutoCloseable {
+  // Statement preparation
+  def prepareStatement(sql: String): DbPreparedStatement
+  def prepareStatementReturningKeys(sql: String): DbPreparedStatement
+
+  // Transaction control
+  def setAutoCommit(autoCommit: Boolean): Unit
+  def getAutoCommit: Boolean
+  def commit(): Unit
+  def rollback(): Unit
+
+  // Connection state
+  def isClosed: Boolean
+  def close(): Unit
+}
+```
+
+## Creating Instances
+
+`DbConnection` has no public constructor. Application code never instantiates it. `Transactor#connect` and `Transactor#transact` create the concrete `JdbcConnection` internally and make it available through `DbCon#connection` inside the block.
+
+For testing, implement the trait directly with a mock or use a lightweight in-memory JDBC driver such as SQLite's `:memory:` database.
+
+:::caution
+Never call `con.close()` inside a `connect` or `transact` block. The `Transactor` closes the connection after the block returns; closing it early will cause the rest of the block to fail with a "connection already closed" JDBC error.
+:::
+
+## Statement Preparation
+
+### `prepareStatement` — Prepare a SQL statement for execution
+
+`prepareStatement(sql: String): DbPreparedStatement` asks the JDBC driver to compile and cache the SQL string and returns a `DbPreparedStatement` that can have parameters bound to it before execution. The `sql` string must use `?` placeholders for parameters.
+
+```scala
+import zio.blocks.sql._
+
+val transactor: Transactor = JdbcTransactor.fromUrl("jdbc:sqlite::memory:", SqlDialect.SQLite)
+
+// Inside a connect block:
+transactor.connect {
+  val con  = summon[DbCon].connection
+  val stmt = con.prepareStatement("INSERT INTO tags (name) VALUES (?)")
+  stmt.paramWriter.setString(1, "scala")
+  val rowCount = stmt.executeUpdate()
+  stmt.close()
+  rowCount
+}
+```
+
+### `prepareStatementReturningKeys` — Prepare an insert that returns generated keys
+
+`prepareStatementReturningKeys(sql: String): DbPreparedStatement` prepares a statement with the JDBC `RETURN_GENERATED_KEYS` hint, enabling `executeUpdateReturningKeys` to return an auto-generated primary key. Use this for `INSERT` statements on tables with a database-generated `SERIAL` or `AUTOINCREMENT` primary key.
+
+```scala
+import zio.blocks.sql._
+
+val transactor: Transactor = JdbcTransactor.fromUrl("jdbc:sqlite::memory:", SqlDialect.SQLite)
+
+// Inside a connect block:
+transactor.connect {
+  val con  = summon[DbCon].connection
+  val stmt = con.prepareStatementReturningKeys("INSERT INTO orders (amount) VALUES (?)")
+  stmt.paramWriter.setBigDecimal(1, new java.math.BigDecimal("99.99"))
+  val keyRs  = stmt.executeUpdateReturningKeys()
+  val genKey = if (keyRs.next()) keyRs.reader.getLong(1) else -1L
+  keyRs.close()
+  stmt.close()
+  genKey
+}
+```
+
+## Transaction Control
+
+`setAutoCommit`, `getAutoCommit`, `commit`, and `rollback` manage the connection's transactional state.
+
+`setAutoCommit(autoCommit: Boolean)` switches the connection between auto-commit and manual-commit mode. `getAutoCommit: Boolean` queries the current mode. `commit()` commits the current transaction; `rollback()` rolls it back. These methods wrap the corresponding `java.sql.Connection` calls.
+
+`Transactor#transact` calls `setAutoCommit(false)` before the block and calls `commit()` on success or `rollback()` on exception — so within a `transact` block, you should not call these methods yourself. Use them directly only in a `connect` block where you need fine-grained control over transaction boundaries.
+
+```scala
+import zio.blocks.sql._
+
+val transactor: Transactor = JdbcTransactor.fromUrl("jdbc:sqlite::memory:", SqlDialect.SQLite)
+
+// Manual transaction management inside a connect block (uncommon)
+transactor.connect {
+  val con = summon[DbCon].connection
+  con.setAutoCommit(false)
+  try {
+    // ... execute statements ...
+    con.commit()
+  } catch {
+    case t: Throwable =>
+      con.rollback()
+      throw t
+  }
+}
+```
+
+## Connection State
+
+### `isClosed` — Check whether the connection is still open
+
+`isClosed: Boolean` returns `true` if the connection has already been closed. Inside a `connect` or `transact` block the connection is always open; this method is primarily useful in test code that verifies the `Transactor` closes connections correctly.
+
+```scala
+import zio.blocks.sql._
+
+val transactor: Transactor = JdbcTransactor.fromUrl("jdbc:sqlite::memory:", SqlDialect.SQLite)
+// transactor: Transactor = zio.blocks.sql.JdbcTransactor@7d102738
+
+var capturedCon: DbConnection = null
+// capturedCon: DbConnection = null
+
+transactor.connect {
+  capturedCon = summon[DbCon].connection
+  capturedCon.isClosed // still open inside the block
+}
+// res4: Boolean = false
+
+capturedCon.isClosed // closed after the block returned
+// res5: Boolean = true
+```
+
+### `close` — Close the connection
+
+`close(): Unit` closes the connection and releases the underlying JDBC resources. Normally the `Transactor` calls this automatically after the `connect` or `transact` block completes. Calling it manually inside a block will cause subsequent operations to fail with a "connection already closed" error.

package/reference/sql/db-param-writer.md

@@ -0,0 +1,77 @@
+---
+id: db-param-writer
+title: "DbParamWriter"
+description: "Reference for DbParamWriter, the interface for binding typed Scala values to SQL prepared-statement parameters."
+keywords:
+  - "DbParamWriter Parameter Binding"
+  - "Typed SQL Parameters"
+  - "Prepared Statement Binding"
+  - "JDBC Parameter Binding"
+---
+
+`DbParamWriter` is a trait for binding typed Scala values to the `?` placeholders in a SQL prepared statement. It provides methods to set parameters by their 1-based index (following JDBC convention).
+
+Application code does not use `DbParamWriter` directly — the framework calls it internally when executing queries through `Frag` or `Repo`. It is the write-side counterpart to `DbResultReader`, which reads values from result sets.
+
+## Core API
+
+```scala
+trait DbParamWriter {
+  // Numeric types
+  def setInt(index: Int, value: Int): Unit
+  def setLong(index: Int, value: Long): Unit
+  def setDouble(index: Int, value: Double): Unit
+  def setFloat(index: Int, value: Float): Unit
+  def setShort(index: Int, value: Short): Unit
+  def setByte(index: Int, value: Byte): Unit
+  def setBigDecimal(index: Int, value: java.math.BigDecimal): Unit
+
+  // Text and binary
+  def setString(index: Int, value: String): Unit
+  def setBytes(index: Int, value: Array[Byte]): Unit
+
+  // Date and time
+  def setLocalDate(index: Int, value: java.time.LocalDate): Unit
+  def setLocalDateTime(index: Int, value: java.time.LocalDateTime): Unit
+  def setLocalTime(index: Int, value: java.time.LocalTime): Unit
+  def setInstant(index: Int, value: java.time.Instant): Unit
+  def setDuration(index: Int, value: java.time.Duration): Unit
+
+  // Other types
+  def setBoolean(index: Int, value: Boolean): Unit
+  def setUUID(index: Int, value: java.util.UUID): Unit
+  def setArray(index: Int, elementType: String, elements: IndexedSeq[Any]): Unit
+
+  // Null handling
+  def setNull(index: Int, sqlType: Int): Unit
+}
+```
+
+## Usage
+
+You access `DbParamWriter` through `DbPreparedStatement.paramWriter` when using raw prepared statements in a `connect` block:
+
+```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("INSERT INTO users (name, age) VALUES (?, ?)")
+  
+  stmt.paramWriter.setString(1, "Alice")  // First ?
+  stmt.paramWriter.setInt(2, 30)          // Second ?
+  
+  stmt.executeUpdate()
+  stmt.close()
+}
+```
+
+Note that indices are 1-based, not 0-based.
+
+## How It Works
+
+When you use higher-level operations like `Frag.query` or `Repo.insert`, `DbCodec` internally calls `DbParamWriter` methods to bind your Scala values to SQL parameters. You see this trait only when dropping down to raw prepared statements for advanced use cases like stored procedures or batch operations.
+
+See [DbConnection](./db-connection.md) for examples of raw prepared-statement usage, and [DbCodec](./db-codec.md) for how parameter binding integrates with the codec system.

package/reference/sql/db-param.md

@@ -0,0 +1,66 @@
+---
+id: db-param
+title: "DbParam"
+description: "Reference for DbParam, the typeclass that converts Scala values to DbValue for the sql interpolator and bound SQL parameters in the sql module."
+keywords:
+  - "DbParam typeclass"
+  - "sql interpolator parameters"
+  - "toDbValue conversion"
+  - "DbParam given instances"
+  - "fromDbCodec bridge"
+  - "Option Maybe nullable parameters"
+  - "Compile-time SQL parameters"
+---
+
+`DbParam[A]` is a single-method typeclass that converts a Scala value of type `A` to a `DbValue` for use as a bound SQL parameter. Its sole abstract method is `toDbValue(value: A): DbValue`. The `sql"..."` string interpolator summons a `DbParam[A]` instance at compile time for every interpolated expression and delegates to it during execution to produce the typed `DbValue` that is stored in `Frag#params`. 
+
+The structural shape of `DbParam` is:
+
+```scala
+trait DbParam[A] {
+  def toDbValue(value: A): DbValue
+}
+
+object DbParam {
+  def apply[A](implicit p: DbParam[A]): DbParam[A]
+  // given instances for:
+  //   Int, Long, Double, Float, Boolean, String, Short, Byte,
+  //   BigDecimal, Array[Byte], LocalDate, LocalDateTime, LocalTime,
+  //   Instant, Duration, UUID, DbValue (identity),
+  //   Option[A], Maybe[A], and fromDbCodec[A]
+}
+```
+
+## Usage
+
+The following example shows the three common entry points for `DbParam`: the `sql"..."` interpolator (which calls `toDbValue` behind the scenes), direct instance summoning for inspection:
+
+```scala
+import zio.blocks.sql._
+import java.time.Instant
+import java.util.UUID
+
+// 1. Implicitly used by the sql"..." interpolator — no explicit call needed
+val userId  = 42
+// userId: Int = 42
+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 = ", ""),
+//   params = Vector(DbInt(42), DbBoolean(true))
+// )
+query.params
+// res0: IndexedSeq[DbValue] = Vector(DbInt(42), DbBoolean(true))
+
+// 2. Summon an instance explicitly with DbParam.apply to inspect conversion
+val instant = Instant.parse("2024-01-15T10:00:00Z")
+// instant: Instant = 2024-01-15T10:00:00Z
+DbParam[Instant].toDbValue(instant)
+// res1: DbValue = DbInstant(2024-01-15T10:00:00Z)
+
+DbParam[Option[Int]].toDbValue(Some(7))
+// res2: DbValue = DbInt(7)
+DbParam[Option[Int]].toDbValue(None)
+// res3: DbValue = DbNull
+```