@zio.dev/zio-blocks 0.0.33 → 0.0.51

package/reference/sql/sql-logger.md

@@ -0,0 +1,62 @@
+---
+id: sql-logger
+title: "SqlLogger"
+description: "Reference for SqlLogger, the callback interface for observing SQL execution."
+keywords:
+  - "SqlLogger observability"
+  - "SQL execution logging"
+  - "SuccessEvent ErrorEvent"
+---
+
+`SqlLogger` is a callback interface that reports SQL execution events. Every statement calls either `onSuccess` or `onError` with details about the execution: rendered SQL, bound parameters, duration, and row count.
+
+Key points:
+
+- **Synchronous** — Callbacks run on the JDBC thread immediately after statement completion. Keep implementations fast; use a background thread for heavy I/O.
+- **SqlLogger.noop** — Pre-built no-op instance that discards all events. Default when no custom logger is configured.
+
+## Core API
+
+```scala
+trait SqlLogger {
+  def onSuccess(event: SqlLogger.SuccessEvent): Unit
+  def onError(event: SqlLogger.ErrorEvent): Unit
+}
+```
+
+## Usage
+
+Implement the trait to observe SQL execution:
+
+```scala
+import zio.blocks.sql.SqlLogger
+
+val myLogger: 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"FAIL: ${event.error.getMessage}")
+}
+// myLogger: SqlLogger = repl.MdocSession$MdocApp0$$anon$1@1b9203b8
+```
+
+Pass the logger when creating a `JdbcTransactor`:
+
+```scala
+import zio.blocks.sql._
+
+val dataSource: javax.sql.DataSource = ???
+val myLogger: SqlLogger = SqlLogger.noop
+
+val tx = new JdbcTransactor(() => dataSource.getConnection(), SqlDialect.PostgreSQL, myLogger)
+```
+
+Use the predefined no-op logger when you don't need logging:
+
+```scala
+import zio.blocks.sql._
+
+val dataSource: javax.sql.DataSource = ???
+val tx: JdbcTransactor = JdbcTransactor.fromDataSource(dataSource, SqlDialect.PostgreSQL)
+```

package/reference/sql/sql-name-mapper.md

@@ -0,0 +1,70 @@
+---
+id: sql-name-mapper
+title: "SqlNameMapper"
+description: "Reference for SqlNameMapper, the interface for mapping Scala field names to SQL column names."
+keywords:
+  - "SqlNameMapper Column Naming"
+  - "SnakeCase Conversion"
+  - "Identity Passthrough"
+  - "Custom Column Naming"
+---
+
+`SqlNameMapper` converts Scala field names to SQL column names. Three implementations are built in: `SnakeCase` (default, converts `firstName` to `first_name`), `Identity` (no change), and `Custom` (arbitrary function).
+
+## Core API
+
+The simplified structural shape of `SqlNameMapper` is:
+
+```scala
+sealed trait SqlNameMapper extends (String => String)
+
+object SqlNameMapper {
+  case object SnakeCase                        extends SqlNameMapper
+  case object Identity                         extends SqlNameMapper
+  final case class Custom(f: String => String) extends SqlNameMapper
+}
+```
+
+## Usage
+
+Call a mapper like a function:
+
+```scala
+import zio.blocks.sql.SqlNameMapper
+
+SqlNameMapper.SnakeCase("firstName")
+// res1: String = "first_name"
+SqlNameMapper.SnakeCase("userID")
+// res2: String = "user_id"
+SqlNameMapper.Identity("firstName")
+// res3: String = "firstName"
+
+val upper = SqlNameMapper.Custom(_.toUpperCase)
+// upper: Custom = Custom(
+//   repl.MdocSession$MdocApp0$$Lambda$20339/0x00007f2996f5b000@1850c853
+// )
+upper("firstName")
+// res4: String = "FIRSTNAME"
+```
+
+Use a custom mapper when deriving codecs:
+
+```scala
+import zio.blocks.sql.{DbCodec, DbCodecDeriver, SqlNameMapper}
+import zio.blocks.schema.Schema
+
+case class Order(orderId: Int, totalAmount: BigDecimal)
+object Order { given schema: Schema[Order] = Schema.derived }
+
+// Use UPPERCASE column names instead of snake_case
+val upperDeriver = DbCodecDeriver.withColumnNameMapper(SqlNameMapper.Custom(_.toUpperCase))
+// upperDeriver: DbCodecDeriver = zio.blocks.sql.DbCodecDeriver@646cca72
+val codec: DbCodec[Order] = Order.schema.deriving(upperDeriver).derive
+// codec: DbCodec[Order] = zio.blocks.sql.DbCodecDeriver$$anon$20@596dacd
+codec.columns
+// res6: IndexedSeq[String] = Vector("ORDERID", "TOTALAMOUNT")
+```
+
+## Key Points
+
+For full control over individual field names, use `@Modifier.rename("column_name")` on specific fields without changing the global mapper. It takes precedence over any `SqlNameMapper` in use.

package/reference/sql/table-metadata.md

@@ -0,0 +1,134 @@
+---
+id: table-metadata
+title: "TableMetadata"
+description: "Reference for TableMetadata, the utility for deriving column metadata from a Schema."
+keywords:
+  - "Table Metadata"
+  - "Column Metadata"
+  - "Table Naming Policy"
+  - "Schema DDL Column Derivation"
+---
+
+`TableMetadata` derives column metadata from a `Schema`. It returns a list of `ColumnMeta` instances, each describing a column's name, type, and nullability. `TableNamingPolicy` controls how Scala type names become table names.
+
+## Core API
+
+```scala
+object TableMetadata {
+  def columnsFor[A](
+    schema: Schema[A],
+    columnNameMapper: SqlNameMapper = SqlNameMapper.SnakeCase
+  ): IndexedSeq[ColumnMeta]
+}
+
+final case class ColumnMeta(name: String, dbValue: DbValue, nullable: Boolean)
+
+sealed trait TableNamingPolicy {
+  def defaultName(typeName: String): String
+}
+
+object TableNamingPolicy {
+  case object Singular                         extends TableNamingPolicy
+  case object Plural                           extends TableNamingPolicy
+  final case class Custom(f: String => String) extends TableNamingPolicy
+}
+```
+
+## Usage
+
+Derive column metadata from a schema:
+
+```scala
+import zio.blocks.sql.{TableMetadata, SqlDialect}
+import zio.blocks.schema.Schema
+
+case class Product(id: Int, name: String, price: Option[BigDecimal])
+object Product { given schema: Schema[Product] = Schema.derived }
+
+val cols = TableMetadata.columnsFor(Product.schema)
+// cols: IndexedSeq[ColumnMeta] = Vector(
+//   ColumnMeta(name = "id", dbValue = DbInt(0), nullable = false),
+//   ColumnMeta(name = "name", dbValue = DbString(""), nullable = false),
+//   ColumnMeta(name = "price", dbValue = DbBigDecimal(0), nullable = true)
+// )
+cols
+// res1: IndexedSeq[ColumnMeta] = Vector(
+//   ColumnMeta(name = "id", dbValue = DbInt(0), nullable = false),
+//   ColumnMeta(name = "name", dbValue = DbString(""), nullable = false),
+//   ColumnMeta(name = "price", dbValue = DbBigDecimal(0), nullable = true)
+// )
+
+cols.map(_.name)
+// res2: IndexedSeq[String] = Vector("id", "name", "price")
+cols.map(_.nullable)
+// res3: IndexedSeq[Boolean] = Vector(false, false, true)
+```
+
+Use the column metadata to get DDL types:
+
+```scala
+cols.map(col => SqlDialect.PostgreSQL.typeName(col.dbValue))
+// res4: IndexedSeq[String] = Vector("INTEGER", "TEXT", "NUMERIC")
+```
+
+Control table naming when deriving a Table:
+
+```scala
+import zio.blocks.sql.{Table, TableNamingPolicy}
+
+// Singular table name (default)
+val table1 = Table.derived[Product]
+// table1: Table[Product] = Table(
+//   name = "product",
+//   codec = zio.blocks.sql.DbCodecDeriver$$anon$20@40f5588b,
+//   columnsMeta = Vector(
+//     ColumnMeta(name = "id", dbValue = DbInt(0), nullable = false),
+//     ColumnMeta(name = "name", dbValue = DbString(""), nullable = false),
+//     ColumnMeta(name = "price", dbValue = DbBigDecimal(0), nullable = true)
+//   )
+// )
+table1.name
+// res5: String = "product"
+
+// Plural table name
+val table2 = Table.derived[Product](TableNamingPolicy.Plural)
+// table2: Table[Product] = Table(
+//   name = "products",
+//   codec = zio.blocks.sql.DbCodecDeriver$$anon$20@13590a4,
+//   columnsMeta = Vector(
+//     ColumnMeta(name = "id", dbValue = DbInt(0), nullable = false),
+//     ColumnMeta(name = "name", dbValue = DbString(""), nullable = false),
+//     ColumnMeta(name = "price", dbValue = DbBigDecimal(0), nullable = true)
+//   )
+// )
+table2.name
+// res6: String = "products"
+
+// Custom naming
+val table3 = Table.derived[Product](TableNamingPolicy.Custom("t_" + _))
+// table3: Table[Product] = Table(
+//   name = "t_Product",
+//   codec = zio.blocks.sql.DbCodecDeriver$$anon$20@2fa45824,
+//   columnsMeta = Vector(
+//     ColumnMeta(name = "id", dbValue = DbInt(0), nullable = false),
+//     ColumnMeta(name = "name", dbValue = DbString(""), nullable = false),
+//     ColumnMeta(name = "price", dbValue = DbBigDecimal(0), nullable = true)
+//   )
+// )
+table3.name
+// res7: String = "t_Product"
+```
+
+## Key Points
+
+**`columnsFor`** — Walks a schema's structure and returns metadata for each column, respecting `@Modifier.transient` (skip field), `@Modifier.rename` (override name), and `Option[A]` / `Maybe[A]` (mark nullable).
+
+**ColumnMeta** — Holds the column name, a representative `DbValue` for type inference, and a nullable flag. The actual value in `dbValue` doesn't matter—only its variant is used by `SqlDialect#typeName`.
+
+**TableNamingPolicy** — Controls default table naming: `Singular` converts `"UserAccount"` to `"user_account"`, `Plural` to `"user_accounts"`, `Custom(f)` applies function `f` directly.
+
+## How It Works
+
+`Table.derived` calls `columnsFor` to extract column metadata from the schema. For each `ColumnMeta`, the dialect's `typeName` method is called to get the SQL type string. The metadata tracks which columns are nullable based on `Option[A]` or `Maybe[A]` types. Fields annotated with `@Modifier.rename` use their explicit name instead of the mapper.
+
+For how Table uses this metadata, see [Table](./table.md). For DDL generation, see [Ddl](./ddl.md).