From 0c8ea0e7b1a0a3816badd35243891fd5ff22fbae Mon Sep 17 00:00:00 2001 From: Ilya Gurov Date: Wed, 12 Oct 2022 01:25:51 -0700 Subject: [PATCH 1/2] docs: describe DB API and transactions retry mechanism --- README.rst | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/README.rst b/README.rst index bebfe1fd5d..eecc48d9b5 100644 --- a/README.rst +++ b/README.rst @@ -235,6 +235,31 @@ if any of the records does not already exist. ) +Connection API +----------- +Connection API represents a wrap-around for Python Spanner API, written in accordance with PEP-249, and provides a simple way of communication with a Spanner database through connection objects: + +.. code:: python + + from google.cloud.spanner_dbapi.connection import connect + + connection = connect("instance-id", "database-id") + connection.autocommit = True + + cursor = connection.cursor() + cursor.execute("SELECT * FROM table_name") + + result = cursor.fetchall() + + +Aborted Transactions Retry Mechanism +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In ``!autocommit`` mode, transactions can be aborted due to transient errors. In most cases retry of an aborted transaction solves the problem. To simplify it, connection tracks SQL statements, executed in the current transaction. In case the transaction aborted, the connection initiates a new one and re-executes all the statements. In the process, the connection checks that retried statements are returning the same results that the original statements did. If results are different, the transaction is dropped, as the underlying data changed, and auto retry is impossible. + +Auto-retry of aborted transactions is enabled only for ``!autocommit`` mode, as in ``autocommit`` mode transactions are never aborted. + + Next Steps ~~~~~~~~~~ From a1977dee30a3027ab4e13aa3b032021ed5ebd6ce Mon Sep 17 00:00:00 2001 From: Ilya Gurov Date: Thu, 13 Oct 2022 00:16:32 -0700 Subject: [PATCH 2/2] Update README.rst --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index eecc48d9b5..7e75685f2e 100644 --- a/README.rst +++ b/README.rst @@ -236,7 +236,7 @@ if any of the records does not already exist. Connection API ------------ +-------------- Connection API represents a wrap-around for Python Spanner API, written in accordance with PEP-249, and provides a simple way of communication with a Spanner database through connection objects: .. code:: python