From 1e4efafd9ec60aa0189491988a0ae1f215902470 Mon Sep 17 00:00:00 2001
From: steve-chavez <stevechavezast@gmail.com>
Date: Wed, 3 Jan 2024 23:20:42 -0500
Subject: [PATCH] docs: add tx preference

---
 docs/references/api/preferences.rst | 33 +++++++++++++++++++++++++++++
 docs/references/transactions.rst    |  4 +++-
 2 files changed, 36 insertions(+), 1 deletion(-)

diff --git a/docs/references/api/preferences.rst b/docs/references/api/preferences.rst
index 012025d22..89cc412f4 100644
--- a/docs/references/api/preferences.rst
+++ b/docs/references/api/preferences.rst
@@ -13,6 +13,7 @@ The following preferences are supported.
 - ``Prefer: count``. See :ref:`prefer_count`.
 - ``Prefer: resolution``. See :ref:`prefer_resolution`.
 - ``Prefer: missing``. See :ref:`bulk_insert_default`.
+- ``Prefer: tx``. See :ref:`prefer_tx`.
 - ``Prefer: max-affected``, See :ref:`prefer_max_affected`.
 
 .. _prefer_handling:
@@ -227,6 +228,38 @@ On the other end of the spectrum you can get the full created object back in the
       }
   ]
 
+.. _prefer_tx:
+
+Transaction End Preference
+==========================
+
+The ``tx`` preference can be set to specify if the :ref:`transaction <transactions>` will end in a COMMIT or ROLLBACK. This preference is not enabled by default but can be activated with :ref:`db-tx-end`.
+
+.. tabs::
+
+  .. code-tab:: http
+
+    POST /projects HTTP/1.1
+    Content-Type: application/json
+    Prefer: tx=rollback, return=representation
+
+    {"name": "Project X"}
+
+  .. code-tab:: bash Curl
+
+    curl -i "http://localhost:3000/projects" -X POST \
+      -H "Content-Type: application/json" \
+      -H "Prefer: tx=rollback, return=representation" \
+      -d '{"name": "Project X"}'
+
+.. code-block:: http
+
+  HTTP/1.1 200 OK
+  Preference-Applied: tx=rollback, return=representation
+
+  {"id": 35, "name": "Project X"}
+
+
 .. _prefer_max_affected:
 
 Max Affected
diff --git a/docs/references/transactions.rst b/docs/references/transactions.rst
index dee915a59..a9ab527bf 100644
--- a/docs/references/transactions.rst
+++ b/docs/references/transactions.rst
@@ -324,10 +324,12 @@ Main query
 
 The main query is generated by requesting :ref:`tables_views` or :ref:`s_procs`. All generated queries use prepared statements (:ref:`db-prepared-statements`).
 
+.. _tx_end:
+
 Transaction End
 ---------------
 
-If the transaction doesn't fail, it will always end in a COMMIT. Unless :ref:`db-tx-end` is configured to ROLLBACK in any case or conditionally with ``Prefer: tx=rollback``. This can be used for testing purposes.
+If the transaction doesn't fail, it will always end in a COMMIT. Unless :ref:`db-tx-end` is configured to ROLLBACK in any case or conditionally with the :ref:`prefer_tx`. This is useful for testing purposes.
 
 Aborting transactions
 ---------------------