diff --git a/docs/references/auth.rst b/docs/references/auth.rst index 8bacf9140..58dc737ac 100644 --- a/docs/references/auth.rst +++ b/docs/references/auth.rst @@ -39,24 +39,6 @@ The picture below shows how the server handles authentication. If auth succeeds, This role switching mechanism is called **user impersonation**. In PostgreSQL it's done with the ``SET ROLE`` statement. -.. _impersonated_settings: - -Impersonated Role Settings --------------------------- - -The impersonated role has its settings applied. For example, if you do: - -.. code-block:: postgresql - - ALTER ROLE webuser SET statement_timeout TO '5s'; - -Every ``webuser`` :ref:`transaction ` gets its queries executed with a ``statement_timeout`` of 5 seconds. - -.. note:: - - Settings that have a high privilege context (like ``superuser``) won't be applied, only settings that have a ``user`` context will be. This is so we don't cause permission errors. - For more details see `Understanding Postgres Parameter Context `_. - .. _jwt_impersonation: JWT-Based User Impersonation diff --git a/docs/references/transactions.rst b/docs/references/transactions.rst index 868b069c9..ec84cb99a 100644 --- a/docs/references/transactions.rst +++ b/docs/references/transactions.rst @@ -91,6 +91,13 @@ Access Mode on Functions - 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. +.. _impersonated_settings: + +Impersonated Role Settings +-------------------------- + +The impersonated role has its settings applied. For example see :ref:`isolation_lvl` and :ref:`statement_timeout` below. + .. _isolation_lvl: Isolation Level @@ -98,12 +105,12 @@ Isolation Level Every transaction uses the PostgreSQL default isolation level: READ COMMITTED. Unless you modify `default_transaction_isolation `_ for an impersonated role or function. -Using :ref:`impersonated_settings`, change the isolation level for all the role's requests with: - .. code-block:: postgresql ALTER ROLE webuser SET default_transaction_isolation TO 'repeatable read'; +Every ``webuser`` gets its queries executed with ``default_transaction_isolation`` set to REPEATABLE READ. + Or to change the isolation level per function call. .. code-block:: postgresql @@ -115,6 +122,35 @@ Or to change the isolation level per function call. LANGUAGE SQL SET default_transaction_isolation TO 'serializable'; +.. _statement_timeout: + +Statement Timeout +----------------- + +It allows you to abort any statement that takes more than a specified time. It is disabled by default. You can set `statement_timeout `__ for an impersonated role or function. + +.. code-block:: postgresql + + ALTER ROLE webuser SET statement_timeout TO '5s'; + +Every ``webuser`` gets its queries executed with a ``statement_timeout`` of 5 seconds. + +Or to set the statement timeout per function call. + +.. code-block:: postgresql + + CREATE OR REPLACE FUNCTION myfunc() + RETURNS void as $$ + SELECT pg_sleep(3); + $$ + LANGUAGE SQL + SET statement_timeout TO '1s'; + +.. note:: + + Settings that have a high privilege context (like ``superuser``) won't be applied, only settings that have a ``user`` context will be. This is so we don't cause permission errors. + For more details see `Understanding Postgres Parameter Context `_. + .. _tx_settings: Transaction-Scoped Settings