Skip to content

Commit

Permalink
docs: cleanup the transaction section of README a bit (#545)
Browse files Browse the repository at this point in the history
Cleans up the Transaction section of the README file a bit.
  • Loading branch information
olavloite authored Dec 9, 2024
1 parent e4e8cd5 commit c3b5df5
Showing 1 changed file with 15 additions and 9 deletions.
24 changes: 15 additions & 9 deletions README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ on this step in a dialect prefix part:
# for SQLAlchemy 1.3:
spanner:///projects/project-id/instances/instance-id/databases/database-id
# for SQLAlchemy 1.4:
# for SQLAlchemy 1.4 and 2.0:
spanner+spanner:///projects/project-id/instances/instance-id/databases/database-id
To pass your custom client object directly to be be used, create engine as following:
Expand Down Expand Up @@ -237,7 +237,7 @@ Unique constraints
~~~~~~~~~~~~~~~~~~

Cloud Spanner doesn't support direct UNIQUE constraints creation. In
order to achieve column values uniqueness UNIQUE indexes should be used.
order to achieve column values uniqueness, UNIQUE indexes should be used.

Instead of direct UNIQUE constraint creation:

Expand Down Expand Up @@ -265,10 +265,16 @@ Autocommit mode
~~~~~~~~~~~~~~~

Spanner dialect supports both ``SERIALIZABLE`` and ``AUTOCOMMIT``
isolation levels. ``SERIALIZABLE`` is the default one, where
transactions need to be committed manually. ``AUTOCOMMIT`` mode
corresponds to automatically committing of a query right in its
execution time.
isolation levels. ``SERIALIZABLE`` is the default isolation level.

``AUTOCOMMIT`` mode corresponds to automatically committing each
insert/update/delete statement right after is has been executed.
Queries that are executed in ``AUTOCOMMIT`` mode use a single-use
read-only transaction. These do not take any locks and do not need
to be committed.

Workloads that only read data, should use either ``AUTOCOMMIT`` or
a read-only transaction.

Isolation level change example:

Expand All @@ -279,16 +285,16 @@ Isolation level change example:
eng = create_engine("spanner:///projects/project-id/instances/instance-id/databases/database-id")
autocommit_engine = eng.execution_options(isolation_level="AUTOCOMMIT")
Automatic transactions retry
Automatic transaction retry
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In the default ``SERIALIZABLE`` mode transactions may fail with ``Aborted`` exception. This is a transient kind of errors, which mostly happen to prevent data corruption by concurrent modifications. Though the original transaction becomes non operational, a simple retry of the queries solves the issue.

This, however, may require to manually repeat a long list of operations, executed in the failed transaction. To simplify it, Spanner Connection API tracks all the operations, executed inside current transaction, and their result checksums. If the transaction failed with ``Aborted`` exception, the Connection API will automatically start a new transaction and will re-run all the tracked operations, checking if their results are the same as they were in the original transaction. In case data changed, and results differ, the transaction is dropped, as there is no way to automatically retry it.

In ``AUTOCOMMIT`` mode automatic transactions retry mechanism is disabled, as every operation is committed just in time, and there is no way an ``Aborted`` exception can happen.

Autoincremented IDs
~~~~~~~~~~~~~~~~~~~
Auto-incremented IDs
~~~~~~~~~~~~~~~~~~~~

Cloud Spanner doesn't support autoincremented IDs mechanism due to
performance reasons (`see for more
Expand Down

0 comments on commit c3b5df5

Please sign in to comment.