From 3dead2ac8b4d476f292b874da2cd4f2c1d7eaccf Mon Sep 17 00:00:00 2001
From: steve-chavez <stevechavezast@gmail.com>
Date: Mon, 4 Sep 2023 18:53:53 -0300
Subject: [PATCH] clarify access mode

---
 docs/references/transactions.rst | 51 +++++++++++++++++++++++++-------
 1 file changed, 40 insertions(+), 11 deletions(-)

diff --git a/docs/references/transactions.rst b/docs/references/transactions.rst
index ee81e9d1c..868b069c9 100644
--- a/docs/references/transactions.rst
+++ b/docs/references/transactions.rst
@@ -9,14 +9,46 @@ After :ref:`user_impersonation`, every request to an :doc:`API resource <api>` r
 
   BEGIN; -- <Access Mode> <Isolation Level>
   -- <Transaction-scoped settings>
-  -- <Main Query>;
-  END;
+  -- <Main Query>
+  END; -- <Transaction End>
 
 .. _access_mode:
 
 Access Mode
 -----------
 
+The access mode determines whether the transaction can modify the database or not. There are 2 possible values: READ ONLY and READ WRITE.
+
+Modifying the database inside READ ONLY transactions is not possible. PostgREST uses this fact to enforce HTTP semantics in GET and HEAD requests. Consider the following:
+
+.. code-block:: postgresql
+
+  CREATE SEQUENCE callcounter_count START 1;
+
+  CREATE VIEW callcounter AS
+  SELECT nextval('callcounter_count');
+
+Since the ``callcounter`` view modifies the sequence, calling it with GET or HEAD will result in an error:
+
+.. tabs::
+
+  .. code-tab:: http
+
+    GET /callounter HTTP/1.1
+
+  .. code-tab:: bash Curl
+
+    curl "http://localhost:3000/callcounter"
+
+.. code-block:: http
+
+  HTTP/1.1 405 Method Not Allowed
+
+  {"code":"25006","details":null,"hint":null,"message":"cannot execute nextval() in a read-only transaction"}
+
+Access Mode on Tables and Views
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 The access mode on :ref:`tables_views` is determined by the HTTP method.
 
 .. list-table::
@@ -29,6 +61,9 @@ The access mode on :ref:`tables_views` is determined by the HTTP method.
    * - POST, PATCH, PUT, DELETE
      - READ WRITE
 
+Access Mode on Functions
+~~~~~~~~~~~~~~~~~~~~~~~~
+
 :ref:`s_procs` additionally depend on the function `volatility <https://www.postgresql.org/docs/current/xfunc-volatility.html>`_.
 
 .. list-table::
@@ -51,13 +86,10 @@ The access mode on :ref:`tables_views` is determined by the HTTP method.
      - READ ONLY
      - READ ONLY
 
-Modifying the database inside READ ONLY transactions is not possible. PostgREST uses this fact to enforce HTTP semantics in GET and HEAD requests.
-
 .. note::
 
-  The volatility marker is a promise about the behavior of the function.  PostgreSQL will let you mark a function that modifies the database as ``IMMUTABLE`` or ``STABLE`` without failure.  But, because of the READ ONLY transaction the function will fail under PostgREST.
-
-The :ref:`options_requests` method doesn't start a transaction, so it's not relevant here.
+  - The volatility marker is a promise about the behavior of the function.  PostgreSQL will let you mark a function that modifies the database as ``IMMUTABLE`` or ``STABLE`` without failure.  But, because of the READ ONLY transaction the function will fail under PostgREST.
+  - The :ref:`options_requests` method doesn't start a transaction, so it's not relevant here.
 
 .. _isolation_lvl:
 
@@ -113,9 +145,6 @@ Request Headers, Cookies and JWT claims
 
 PostgREST stores the headers, cookies and headers as JSON. To get them:
 
-.. important::
-
-
 .. code-block:: postgresql
 
   -- To get all the headers sent in the request
@@ -250,7 +279,7 @@ If the status code is standard, PostgREST will complete the status message(**I'm
 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`).
+The main query is generated by requesting :ref:`tables_views` or :ref:`s_procs`. All generated queries use prepared statements (:ref:`db-prepared-statements`).
 
 Transaction End
 ---------------