docs: add clarification about transaction characteristics attributes

They don't affect autocommit connections as they used to in psycopg2, so
note it as a difference from psycopg2. Add more explicit warning about
this limitation.

https://www.postgresql.org/message-id/DB7PR07MB39163E0AFB907413EE5C10F68738A%40DB7PR07MB3916.eurprd07.prod.outlook.com

diff --git a/docs/basic/from_pg2.rst b/docs/basic/from_pg2.rst
index 08f45faee699e86d4707f5fb587fc757060b0dd0..59b6201ffb6bef148e0588e20efa62b4a2b58987 100644 (file)
--- a/docs/basic/from_pg2.rst
+++ b/docs/basic/from_pg2.rst
@@ -354,6 +354,25 @@ connection by running a :sql:`SET client_encoding` statement... But why would
 you?
 
 
+.. _transaction-characteristics-and-autocommit:
+
+Transaction characteristics attributes don't affect autocommit sessions
+-----------------------------------------------------------------------
+
+:ref:`Transactions characteristics attributes <transaction-characteristics>`
+such as `~Connection.read_only` don't affect automatically autocommit
+sessions: they only affect the implicit transactions started by non-autocommit
+sessions and the transactions created by the `~Connection.transaction()`
+block (for both autocommit and non-autocommit connections).
+
+If you want to put an autocommit transaction in read-only mode, please use the
+default_transaction_read_only__ GUC, for instance executing the statement
+:sql:`SET default_transaction_read_only TO true`.
+
+.. __: https://www.postgresql.org/docs/current/runtime-config-client.html
+       #GUC-DEFAULT-TRANSACTION-READ-ONLY
+
+
 .. _infinity-datetime:
 
 No default infinity dates handling

diff --git a/docs/basic/transactions.rst b/docs/basic/transactions.rst
index 91c304aecb77878baae41b4972d3693a5869fdad..fe05f9f3ef65b02684991bea43fe40186dab3501 100644 (file)
--- a/docs/basic/transactions.rst
+++ b/docs/basic/transactions.rst
@@ -305,9 +305,17 @@ Transaction characteristics
 You can set `transaction parameters`__ for the transactions that Psycopg
 handles. They affect the transactions started implicitly by non-autocommit
 transactions and the ones started explicitly by `Connection.transaction()` for
-both autocommit and non-autocommit transactions. Leaving these parameters as
-`!None` will use the server's default behaviour (which is controlled
-by server settings such as default_transaction_isolation__).
+both autocommit and non-autocommit transactions.
+
+.. Warning::
+
+    Transaction parameters :ref:`don't affect autocommit connections
+    <transaction-characteristics-and-autocommit>`, unless a `!transaction()`
+    block is explicitly used.
+
+Leaving these parameters as `!None` will use the server's default behaviour
+(which is controlled by server settings such as
+default_transaction_isolation__).
 
 .. __: https://www.postgresql.org/docs/current/sql-set-transaction.html
 .. __: https://www.postgresql.org/docs/current/runtime-config-client.html