From d67d541adf5ae31ab539abb257a09114aed3edfb Mon Sep 17 00:00:00 2001
From: Alexander Ioffe <deusaquilus@gmail.com>
Date: Sun, 3 Nov 2024 21:02:48 -0500
Subject: [PATCH] Add docs for diagnostics

---
 README.md | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/README.md b/README.md
index 6f4ce13f..1320e1ce 100644
--- a/README.md
+++ b/README.md
@@ -380,6 +380,34 @@ The way that this works is that in each `?` slot, the corresponding column is lo
 //   true
 ```
 
+## Getting SQL of the Last Executed Query (ZIO Only)
+
+In ZIO contexts, you can get the SQL of the last executed query by using the `getLastExecutedQuery()` method.
+
+```scala
+val people =
+   for {
+     people <- ctx.run(quote { query[Person] })
+     sql <- ctx.getLastExecutedQuery()
+     _ <- ZIO.log(s"Last Executed Query: ${sql}")
+   } yield people
+```
+
+For advanced debugging use-cases, you can even get the syntax tree of the last executed query by using the `getLastExecutedQueryTree()` method.
+Since this may incur additional performance overhead, make sure that your context extends `AstSplicing` in order to enable this behavior.
+
+```scala
+val people =
+   for {
+     // First create a quill-zio context. Be sure that it extends AstSplicing
+     ctx <- Quill.Postgres(Literal, connectionPool) with AstSplicing
+     // Then run a query and invoke getLastExecutionInfo 
+     people <- ctx.run(quote { query[Person] })
+     info <- ctx.getLastExecutionInfo()
+     _ <- ZIO.log(s"Last Executed Ast: ${info.ast}")
+   } yield people
+```
+
 ## Co-Product Rows
 
 Co-Product are supported using Enums and sealed traits. Keep in mind that for now, only static-global enums are supported and any sealed traits that are used must be sealed in a *separate object* in order to work. Otherwise a sum-type mirror of them will not be found. In ORM-terms, Quill uses a "Table Per Class-Hierarchy" model of co-product polymorhism in which data for all co-products must be encodeable within a simple row.