Docs for PreferRepeatableRead (#9065)

Ref #8832

Since this is a *virtual*, client side option, it has to be explained for
each client separately.

Author: aljazerzen

docs/reference/reference/edgeql/tx_start.rst

@@ -38,6 +38,7 @@ Start transaction
 
     # where <transaction-mode> is one of:
 
+    isolation repeatable read
     isolation serializable
     read write | read only
     deferrable | not deferrable
@@ -54,6 +55,7 @@ committed if the command was executed successfully, or automatically
 rollbacked if there was an error.  This behavior is often called
 "autocommit".
 
+When isolation is not specified, it defaults to ``serializable``.
 
 Parameters
 ----------
@@ -67,7 +69,44 @@ The :eql:synopsis:`<transaction-mode>` can be one of the following:
     If a pattern of reads and writes among concurrent serializable
     transactions creates a situation that could not have occurred
     in any serial (one-at-a-time) execution of those transactions,
-    one of them will be rolled back with a serialization_failure error.
+    one of them will be rolled back with a serialization failure.
+
+    This level is the default isolation level.
+
+    Note that, compared to ``repeatable read``, serializable level has a
+    significantly higher probability of resulting in serialization failures,
+    requires the whole transaction to be retried. If acceptable, consider using
+    ``repeatable read`` or
+    :ref:`prefer repeatable read <prefer_repeatable_read>`.
+
+:eql:synopsis:`isolation repeatable read`
+    All statements in the current transaction can only see data
+    changes that were committed before the first query or data
+    modification statement was executed within this transaction.
+
+    Compared to ``serializable``, this level is less likely to result in
+    serialization failures.
+
+    It is however possible for this level to allow serialization anomalies.
+    This constitutes a series of transactions that would not be allowed if they
+    were executed serially instead of concurrently.
+
+    For example, assume ``type X { is_selected: bool }`` and following query:
+
+    .. code-block:: edgeql
+
+        # transaction A: unselect all selected
+        update X filter .is_selected set { is_selected := false };
+
+        # transaction B: select all unselected
+        update X filter not .is_selected set { is_selected := true };
+
+    Running these two transactions serially would result in either all ``X``
+    being select or none being selected. But if executed concurrently, even with
+    the ``repeatable read`` isolation level, we can end up with some ``X`` being
+    selected and some not.
+
+    To avoid this, we can use the ``serializable`` isolation level.
 
 :eql:synopsis:`read write`
     Sets the transaction access mode to read/write.
@@ -109,6 +148,23 @@ Start a serializable deferrable transaction:
     start transaction isolation serializable, read only, deferrable;
 
 
+.. _prefer_repeatable_read:
+
+Prefer repeatable read
+----------------------
+
+In addition to the isolation levels above, some client libraries also support
+``PreferRepeatableRead`` as a transaction isolation level.
+In this mode, the server will analyze the query and use ``repeatable read``
+isolation level if it can. When it cannot, it will use ``serializable``
+isolation level.
+
+Client libraries that currently support this mode:
+
+* TypeScript/JS
+* Python
+* Go
+
 .. list-table::
   :class: seealso
 

docs/reference/using/js/client.rst

@@ -187,14 +187,14 @@ Both ``execute`` and the ``query*`` methods support scripts (queries containing
   });
   result; // { id: string }[]: the result of the `insert Person` statement
 
-For more fine grained control of atomic exectution of multiple statements, use the ``transaction()`` API.
+For more fine grained control of atomic execution of multiple statements, use the ``transaction()`` API.
 
 .. _gel-js-api-transaction:
 
 Transactions
 ------------
 
-For more fine grained control of atomic exectution of multiple statements, use the ``transaction()`` API.
+For more fine grained control of atomic execution of multiple statements, use the ``transaction()`` API.
 
 .. code-block:: typescript
 
@@ -213,6 +213,8 @@ The ``transaction()`` API guarantees that:
 
 The *transaction* object exposes ``query()``, ``execute()``, ``querySQL()``, ``executeSQL()``, and other ``query*()`` methods that *clients* expose, with the only difference that queries will run within the current transaction and can be retried automatically.
 
+Default isolation level is serializable. You can change it via ``Client.withTransactionOptions``.
+
 .. warning::
 
   In transactions, the entire nested code block can be re-run, including any non-querying JavaScript code. In general, the code inside the transaction block **should not have side effects or run for a significant amount of time**. Consider the following example:
@@ -628,6 +630,9 @@ Client Reference
               );
             });
 
+        By default, transactions will be executed in the strictest, serializable isolation level.
+        To change the isolation level, use the ``Client.withTransactionOptions``.
+
     .. js:method:: ensureConnected(): Promise<Client>
 
         If the client does not yet have any open connections in its pool, attempts to open a connection, else returns immediately.
@@ -743,6 +748,40 @@ Client Reference
               // ...
             });
 
+    .. js:method:: withTransactionOptions(opts: {
+          isolation?: IsolationLevel, \
+          readonly?: boolean, \
+          deferrable?: boolean, \
+        }): Client
+
+        Returns a clone of the ``Client`` instance with the specified transaction options.
+
+        Available isolation levels are ``Serializable``, ``RepeatableRead``, and ``PreferRepeatableRead``. ``PreferRepeatableRead`` uses repeatable read isolation level if server analysis concludes that it is supported for a given query. Otherwise, uses serializable isolation level.
+
+        When readonly is set, the transaction is now allowed to execute ``insert``, ``update``, or ``delete`` statements.
+
+        When deferrable is set, and isolation is serializable and readonly is set, the transaction only block when first acquiring its snapshot, after which it is able to run without the normal overhead of a serializable transaction and without any risk of contributing to or being canceled by a serialization failure. This mode is well suited for long-running reports or backups.
+
+        For more information, see :ref:`the transaction options reference <ref_eql_statements_start_tx>`.
+
+        :arg opts: An object mapping transaction options to values.
+
+        :returns: ``Client``
+
+        Example:
+
+        .. code-block:: javascript
+
+            const readonlyClient = client.withTransactionOptions({
+              isolation: IsolationLevel.PreferRepeatableRead,
+              readonly: true,
+            });
+
+            // This transaction is less likely to raise a serialization error
+            await readonlyClient.transaction(async (tx) => {
+              // ...
+            });
+
     .. js:method:: withWarningHandler(handler: (warnings: errors.GelError[]) => void): Client
 
         Returns a clone of the ``Client`` instance with the specified warning handler. Some queries may generate warnings while still returning a result. The ``handler`` function will be called with an array of ``GelError`` objects whenever the client encounters warnings during query execution.

docs/reference/using/python/api/advanced.rst

@@ -37,6 +37,11 @@ Transactions can be customized with different options:
 
         Repeatable read isolation level (supported in read-only transactions)
 
+    .. py:attribute:: PreferRepeatableRead
+
+        Uses repeatable read isolation level if server analysis concludes that it is supported for a given query.
+        Otherwise, uses serializable isolation level.
+
 :py:class:`TransactionOptions` can be set on :py:class:`~gel.Client` or :py:class:`~gel.AsyncIOClient` using one of these methods:
 
 * :py:meth:`gel.Client.with_transaction_options`