@zio.dev/zio-blocks 0.0.51 → 0.0.56

package/guides/getting-started-with-mux.md

@@ -634,22 +634,6 @@ This example creates a mux and opens your first stream, demonstrating the basic
   <summary>mux-examples/src/main/scala/mux/Example1CreatingAMux.scala</summary>
 
 ```scala title="mux-examples/src/main/scala/mux/Example1CreatingAMux.scala" showLineNumbers
-/*
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
 package mux
 
 import zio.blocks.mux._
@@ -698,22 +682,6 @@ This example demonstrates the two-perspective communication model where applicat
   <summary>mux-examples/src/main/scala/mux/Example2UnderstandingStreamsAndMessageQueues.scala</summary>
 
 ```scala title="mux-examples/src/main/scala/mux/Example2UnderstandingStreamsAndMessageQueues.scala" showLineNumbers
-/*
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
 package mux
 
 import zio.blocks.mux._
@@ -791,22 +759,6 @@ This example shows all three ways to close a stream: graceful two-phase closure
   <summary>mux-examples/src/main/scala/mux/Example3StreamLifecycle.scala</summary>
 
 ```scala title="mux-examples/src/main/scala/mux/Example3StreamLifecycle.scala" showLineNumbers
-/*
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
 package mux
 
 import zio.blocks.mux._
@@ -904,22 +856,6 @@ This example opens three independent streams and exchanges messages on each one,
   <summary>mux-examples/src/main/scala/mux/Example4WorkingWithMultipleStreams.scala</summary>
 
 ```scala title="mux-examples/src/main/scala/mux/Example4WorkingWithMultipleStreams.scala" showLineNumbers
-/*
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
 package mux
 
 import zio.blocks.mux._
@@ -1037,22 +973,6 @@ This example demonstrates both mux-level capacity (controlling concurrent stream
   <summary>mux-examples/src/main/scala/mux/Example5ManagingCapacity.scala</summary>
 
 ```scala title="mux-examples/src/main/scala/mux/Example5ManagingCapacity.scala" showLineNumbers
-/*
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
 package mux
 
 import zio.blocks.mux._
@@ -1172,22 +1092,6 @@ This example documents which operations are thread-safe (mux-level and send/offe
   <summary>mux-examples/src/main/scala/mux/Example6ThreadSafety.scala</summary>
 
 ```scala title="mux-examples/src/main/scala/mux/Example6ThreadSafety.scala"
-/*
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
 package mux
 
 import zio.blocks.mux._
@@ -1310,22 +1214,6 @@ This comprehensive example demonstrates a complete request-response system that
   <summary>mux-examples/src/main/scala/mux/CompleteExample.scala</summary>
 
 ```scala title="mux-examples/src/main/scala/mux/CompleteExample.scala" showLineNumbers
-/*
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
 package mux
 
 import zio.blocks.mux._

package/guides/query-dsl-extending.md

@@ -52,7 +52,7 @@ None of these can be expressed with `SchemaExpr` alone. You could generate the S
 This guide builds on [Part 1: Expressions](./query-dsl-reified-optics.md) and [Part 2: SQL Generation](./query-dsl-sql.md). You should be comfortable building `SchemaExpr` values and translating them to SQL.
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.51"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.56"
 ```
 
 ```scala

package/guides/query-dsl-fluent-builder.md

@@ -57,7 +57,7 @@ In this guide, we solve both problems: bridge extensions eliminate `.toExpr`, an
 This guide builds on [Part 1: Expressions](./query-dsl-reified-optics.md), [Part 2: SQL Generation](./query-dsl-sql.md), and [Part 3: Extending the Expression Language](./query-dsl-extending.md).
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.51"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.56"
 ```
 
 ## Domain Setup

package/guides/query-dsl-reified-optics.md

@@ -43,7 +43,7 @@ In this guide, we'll solve this by using ZIO Blocks' `SchemaExpr` and reified op
 Add the ZIO Blocks Schema dependency:
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.51"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.56"
 ```
 
 ```scala

package/guides/query-dsl-sql.md

@@ -43,7 +43,7 @@ This is fragile, repetitive, and vulnerable to SQL injection. Every new query sh
 This guide builds on [Part 1: Expressions](./query-dsl-reified-optics.md). You should be comfortable building `SchemaExpr` values with optic operators (`===`, `>`, `&&`, etc.).
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.51"
+libraryDependencies += "dev.zio" %% "zio-blocks-schema" % "0.0.56"
 ```
 
 ```scala
@@ -749,6 +749,400 @@ println(toSql(Product.price * 0.9))
 // (price * 0.9)
 ```
 
+## Upsert (ON CONFLICT)
+
+Upsert (insert-or-update) combines an `INSERT` with a conflict handler so the
+statement is idempotent. When a row with the conflicting key already exists, the
+database either skips the insert or updates specified columns.
+
+All identifiers (table name, column names, conflict column) are validated through
+`SqlIdentifier.validate` and assignment columns are additionally checked against
+`Table.columns`. Invalid or unknown names throw `IllegalArgumentException` at
+build time, not at execution time.
+
+### Table-aware builders
+
+The high-level `Upsert` builders accept a `Table[A]` and an entity. The table
+provides column names and a codec that extracts `DbValue` parameters.
+
+`Upsert.insertDoNothing` builds `INSERT ... ON CONFLICT ("id") DO NOTHING`:
+
+```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 table: Table[User] = Table.derived[User]
+val user = User(42, "Alice", "alice@example.com")
+
+// INSERT INTO "user" ("id", "name", "email") VALUES (?, ?, ?) ON CONFLICT ("id") DO NOTHING
+val frag: Frag = Upsert.insertDoNothing(table, user, conflictColumn = "id")
+```
+
+`Upsert.insertDoUpdate` builds `INSERT ... ON CONFLICT ("id") DO UPDATE SET`
+for **all** non-conflict columns:
+
+```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 table: Table[User] = Table.derived[User]
+val user = User(42, "Alice", "alice@example.com")
+
+// INSERT INTO "user" ("id", "name", "email") VALUES (?, ?, ?)
+//   ON CONFLICT ("id") DO UPDATE SET "name" = ?, "email" = ?
+val frag: Frag = Upsert.insertDoUpdate(table, user, conflictColumn = "id")
+```
+
+Pass `updateColumns` to restrict which columns are overwritten on conflict:
+
+```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 table: Table[User] = Table.derived[User]
+val user = User(42, "Alice", "alice@example.com")
+
+// Only "name" is updated on conflict; "email" keeps its original value
+val frag: Frag = Upsert.insertDoUpdate(table, user, conflictColumn = "id", updateColumns = Seq("name"))
+```
+
+### Low-level builders
+
+When you need full control over column names and values (e.g. computed or
+transformed data), use the low-level `Upsert.doNothing`, `Upsert.doNothingRaw`,
+and `Upsert.doUpdate` builders:
+
+```scala
+import zio.blocks.sql.*
+
+// Low-level DO NOTHING with explicit columns and values
+val frag1: Frag = Upsert.doNothing(
+  tableName   = "users",
+  columns     = IndexedSeq("id", "name", "email"),
+  values      = IndexedSeq(DbValue.DbInt(1), DbValue.DbString("Bob"), DbValue.DbString("bob@example.com")),
+  conflictColumn = "id"
+)
+
+// Comma-joined column string variant
+val frag2: Frag = Upsert.doNothingRaw(
+  tableName   = "users",
+  allColumns  = "id, name, email",
+  values      = IndexedSeq(DbValue.DbInt(1), DbValue.DbString("Bob"), DbValue.DbString("bob@example.com")),
+  conflictColumn = "id"
+)
+
+// Low-level DO UPDATE with explicit assignments
+val frag3: Frag = Upsert.doUpdate(
+  tableName      = "users",
+  columns        = IndexedSeq("id", "name", "email"),
+  values         = IndexedSeq(DbValue.DbInt(1), DbValue.DbString("Bob"), DbValue.DbString("bob@example.com")),
+  conflictColumn = "id",
+  assignments    = IndexedSeq("name" -> DbValue.DbString("Bob"), "email" -> DbValue.DbString("bob@example.com"))
+)
+```
+
+### Suffix builders
+
+To append an `ON CONFLICT` clause to an existing `INSERT` `Frag`, use the suffix
+builders:
+
+```scala
+import zio.blocks.sql.*
+
+val base: Frag = Frag.literal("INSERT INTO users (id, name) VALUES (?, ?)")
+
+// Append DO NOTHING suffix
+val withNothing: Frag = base ++ Upsert.doNothingSuffix(conflictColumn = "id")
+
+// Append DO UPDATE suffix with explicit assignments
+val withUpdate: Frag = base ++ Upsert.doUpdateSuffix(
+  conflictColumn = "id",
+  assignments    = IndexedSeq("name" -> DbValue.DbString("updated"))
+)
+```
+
+### Repository integration
+
+`Repo` provides `insertOrUpdate` and `insertOrUpdateBatch` as convenience
+wrappers that use `Upsert.insertDoUpdate` under the hood. The conflict target is
+the repository's validated ID column, and all non-ID columns are overwritten with
+the entity's values.
+
+```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 }
+
+given DbCon = ???
+
+val table: Table[User] = Table.derived[User]
+val repo: Repo[User, Int] = ???
+
+val user = User(42, "Alice", "alice@example.com")
+
+// Single upsert
+val affected: Int = repo.insertOrUpdate(user)
+
+// Batch upsert
+val users: List[User] = List(user, User(43, "Bob", "bob@example.com"))
+val totalAffected: Int = repo.insertOrUpdateBatch(users)
+```
+
+These generate SQL like:
+
+```sql
+INSERT INTO "user" ("id", "name", "email") VALUES (?, ?, ?)
+  ON CONFLICT ("id") DO UPDATE SET "name" = ?, "email" = ?
+```
+
+`insertOrUpdateBatch` uses a JDBC batch for efficiency, mirroring the pattern of
+`insertBatch`. Both return the total affected row count.
+
+## Keyset Pagination
+
+Keyset (cursor) pagination avoids the cost and drift of `OFFSET` by seeking
+after the last seen key: `WHERE id > ? ORDER BY id ASC LIMIT n`. The row
+identified by the cursor is excluded (`>` not `>=`) so consecutive pages do
+not duplicate the boundary row.
+
+`Repo` exposes this directly for primary-key cursors:
+
+```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 }
+
+given DbCon = ???
+
+val repo: Repo[User, Int] = ??? // e.g. Repo(table, "id", idCodec, _.id)
+
+val firstPage: List[User]  = repo.pageAfter(cursorId = 0, limit = 20)
+val nextPage: List[User]   = repo.pageAfter(cursorId = firstPage.last.id, limit = 20)
+// when cursorId == last id, nextPage is empty
+```
+
+It renders as:
+
+```sql
+SELECT "id", "name", "email" FROM "user" WHERE "id" > ? ORDER BY "id" ASC LIMIT 20
+```
+
+where `?` is bound via `idCodec.toDbValues(cursorId)`. `limit` must be `> 0`.
+
+For non-ID orderings or ad-hoc queries, `Frag.keysetAfter` builds the
+portable `WHERE col > ? ORDER BY col ASC LIMIT n` fragment without a `Repo`:
+
+```scala
+import zio.blocks.sql.*
+
+case class User(id: Int, name: String, email: String)
+import zio.blocks.schema.Schema
+object User { implicit val schema: Schema[User] = Schema.derived }
+val table: Table[User] = Table.derived[User]
+
+// Table-validated: rejects unknown columns
+val frag: Frag = Frag.keysetAfter(table, orderCol = "id", lastValue = DbValue.DbInt(42), limit = 20)
+// frag.sql(dialect) == " WHERE id > ? ORDER BY id ASC LIMIT 20"
+
+// Without a table: identifier-only validation
+val frag2: Frag = Frag.keysetAfter(orderCol = "created_at", lastValue = DbValue.DbLong(1000L), limit = 10)
+```
+
+- `Frag.keysetAfter(table, orderCol, lastValue, limit)` validates `orderCol`
+  with `SqlIdentifier.validate` and checks membership in `table.columns`;
+  unknown columns throw `IllegalArgumentException`.
+- `Frag.keysetAfter(orderCol, lastValue, limit)` validates the identifier only.
+- `limit` must be `> 0`; single-column cursors only (composite cursors are v2).
+
+Compose with a base `SELECT`:
+
+```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 table: Table[User] = Table.derived[User]
+
+val base     = Frag.literal("SELECT id, name, email FROM user")
+val pageFrag = base ++ Frag.keysetAfter(table, "id", DbValue.DbInt(42), 20)
+// Rendering the SQL does not require a DbCon:
+val sql: String = pageFrag.sql(SqlDialect.SQLite) // SELECT id, name, email FROM user WHERE id > ? ORDER BY id ASC LIMIT 20
+// Executing needs givens at the call site:
+// given DbCon = ???
+// given DbCodec[User] = table.codec
+// val rows: List[User] = pageFrag.query[User]
+```
+
+## Inspecting SQL
+
+The custom interpreter above produces raw strings useful for debugging. The `sql` module's query IR (`zio.blocks.sql.query.SqlQuery`) provides richer inspection APIs.
+
+### explain(dialect): String
+
+The `explain` method renders the full SQL text with numbered parameter placeholders (`?1`, `?2`, ...) and a trailing comment listing each parameter's position and type:
+
+```scala
+import zio.blocks.sql._
+import zio.blocks.sql.query.{Rel, SqlQuery => Select}
+
+val userTable = Table.derived[User]
+val repoTable = Table.derived[Repo]
+
+val q = Select
+  .from(userTable)
+  .innerJoin(Rel(repoTable, "owner_id", userTable, "id"))
+  .filter(Frag(IndexedSeq("""t0."name" = """, ""), IndexedSeq(DbValue.DbString("alice"))))
+
+println(q.explain(SqlDialect.PostgreSQL))
+// SELECT t0."id", t0."name", t1."id", t1."owner_id", t1."name" FROM "user" AS t0 INNER JOIN "repo" AS t1 ON t1."owner_id" = t0."id" WHERE t0."name" = ?1
+// -- params: 1:String
+```
+
+`explain` renders a single-line SQL string with numbered `?N` placeholders. The `?N`
+placeholders correspond one-to-one with the parameter list you can obtain separately via
+`toFrag(dialect).params`. This makes `explain` useful for logging and visual debugging without touching a
+database.
+
+### Inspecting the query IR
+
+The query itself is a case class, so every part is available programmatically:
+
+```scala
+q.source       // Table[User] for "user"
+q.joins        // Vector(JoinNode(repoTable, "t1", Inner, <on-frag>))
+q.filters      // Vector(Frag(t0."name" = ?, DbString(alice)))
+q.groupBy      // Vector.empty
+q.orderBy      // Vector.empty
+q.limit        // None
+q.offset       // None
+q.toFrag       // Frag (re-renderable to SQL via frag.sql(dialect))
+```
+
+Inspecting the IR directly lets you examine joins, filters, ordering, and limits programmatically. This is useful for building monitoring dashboards, query analyzers, or dynamic query modification layers.
+
+### sql(dialect): String
+
+The query IR also provides a simpler `sql` method that renders `?` placeholders for execution:
+
+```scala
+println(q.sql(SqlDialect.PostgreSQL))
+// SELECT t0."id", t0."name", t1."id", t1."owner_id", t1."name" FROM "user" AS t0 INNER JOIN "repo" AS t1 ON t1."owner_id" = t0."id" WHERE t0."name" = ?
+```
+
+### previewSql() for Migrations
+
+When using `SmallMigrator` or `LargeMigrator` from the `data-migration` module, `previewSql()` returns the full sequence of SQL statements the migrator would execute, without opening any database connection:
+
+```scala
+import zio.blocks.data.migration._
+
+given transactor: Transactor = tx
+
+val migrator = SmallMigrator(
+  repoV1 = userRepo,
+  repoV2 = userRepoV2,
+  migration = userMigration,
+  queueTable = "migration_queue",
+  batchSize = 100,
+  target = TargetStrategy.InPlace
+)
+
+val statements: Vector[String] = migrator.previewSql()
+// Vector(
+//   "CREATE TABLE ...",     -- queue DDL
+//   "CREATE TABLE ...",     -- shadow table
+//   "CREATE TRIGGER ...",   -- capture triggers
+//   "SELECT ...",           -- dequeue template
+//   "ALTER TABLE ..."       -- finalize (rename)
+// )
+```
+
+This gives you a dry run of the migration SQL before any schema changes are applied.
+
+## Compile-time SQL Dumps
+
+The `Dump` object emits SQL files at compile time. When the JVM property `zib.sql.dumpDir` is set, inline macro calls to `Dump.dumpTable` or `Dump.dumpQuery` write `.sql` files to that directory. When the property is absent, the calls become no-ops with zero runtime cost.
+
+### Enabling Dumps
+
+The `Dump` macros read `System.getProperty("zib.sql.dumpDir")` at compile time from the JVM running sbt's compiler. This is a JVM system property, not a scalac flag. Passing it via `scalacOptions` does nothing.
+
+The simplest way to set it is as a JVM flag on the sbt command line:
+
+```bash
+sbt -Dzib.sql.dumpDir=target/sql-dumps "++3.8.3; sqlJVM/compile"
+```
+
+If you prefer not to type `-D` every time, export it through `SBT_OPTS`:
+
+```bash
+SBT_OPTS="-Dzib.sql.dumpDir=target/sql-dumps" sbt compile
+```
+
+Both approaches set the property on the sbt process, which is the same JVM that runs the Scala compiler and the macros within it.
+
+### Entry Points
+
+There are two inline macro entry points, all in `zio.blocks.sql.Dump`:
+
+```scala
+import zio.blocks.sql._
+
+// Dump a Table's CREATE TABLE DDL (both PostgreSQL and SQLite)
+Dump.dumpTable(userTable)
+
+// Dump a query IR's SELECT
+Dump.dumpQuery(queryIr)
+```
+
+Each call emits one file per dialect (PostgreSQL and SQLite by default).
+
+### Naming Scheme
+
+Files are named `<owner>-<dialect>.sql` where `<owner>` is derived from the enclosing symbol and `<dialect>` is the lowercased dialect name:
+
+```
+target/sql-dumps/
+  user-postgresql.sql
+  user-sqlite.sql
+  repo-postgresql.sql
+  repo-sqlite.sql
+```
+
+For `dumpTable`, the owner comes from the `Table`'s type name. For `dumpQuery`, the macro walks the call site to extract the enclosing method, val name, or argument name. If the macro cannot determine a meaningful name, it falls back to `query`.
+
+### Content-hash Skip
+
+Each dump file is written only when its content differs from the existing file. The macro compares the new bytes against any existing file at the target path. If they match, the write is skipped. This means incremental compilations do not produce noisy diffs or unnecessary filesystem writes.
+
+All files use UTF-8 encoding with a trailing newline.
+
+### Limitations
+
+Compile-time dumps work well for statically constructed queries, but some SQL patterns cannot be dumped:
+
+- **Dynamic `Frag` chains.** Fragments built at runtime from user input, database lookups, or conditional branching are invisible to the macro. Only the static structure known at compile time appears in the dump.
+- **Repo internals.** The `Repo` abstraction's generated queries (insert, update, delete, select-by-id) are assembled at runtime from the `DbCodec` and `Table` metadata. `Dump.dumpTable` captures the DDL, but the CRUD queries themselves are not emitted.
+- **Phase 2 note.** A future phase may extend `Dump` to cover `Repo`-level CRUD operations and dynamic fragment composition. For now, treat the dump as a DDL and static-query snapshot, not a complete representation of every SQL statement your application will execute.
+
+:::tip
+Pair `Dump.dumpTable` with `previewSql()` for a fuller picture: `dumpTable` captures the schema DDL at compile time, while `previewSql` captures the migration SQL at runtime before execution.
+:::
+
 ## Going Further
 
 - **[Part 1: Expressions](./query-dsl-reified-optics.md)** -- Building query expressions with reified optics