docs: add sample and update README

Author: olavloite

README.rst

@@ -293,29 +293,23 @@ This, however, may require to manually repeat a long list of operations, execute
 
 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.
 
-Auto-incremented IDs
-~~~~~~~~~~~~~~~~~~~~
-
-Cloud Spanner doesn't support autoincremented IDs mechanism due to
-performance reasons (`see for more
-details <https://cloud.google.com/spanner/docs/schema-design#primary-key-prevent-hotspots>`__).
-We recommend that you use the Python
-`uuid <https://docs.python.org/3/library/uuid.html>`__ module to
-generate primary key fields to avoid creating monotonically increasing
-keys.
-
-Though it's not encouraged to do so, in case you *need* the feature, you
-can simulate it manually as follows:
-
-.. code:: python
-
-   with engine.begin() as connection:
-       top_id = connection.execute(
-           select([user.c.user_id]).order_by(user.c.user_id.desc()).limit(1)
-       ).fetchone()
-       next_id = top_id[0] + 1 if top_id else 1
-
-       connection.execute(user.insert(), {"user_id": next_id})
+Auto-increment primary keys
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Spanner uses IDENTITY columns for auto-increment primary key values.
+IDENTITY columns use a backing bit-reversed sequence to generate unique
+values that are safe to use as primary values in Spanner. These values
+work the same as standard auto-increment values, except that they are
+not monotonically increasing. This prevents hot-spotting for tables that
+receive a large number of writes.
+
+`See this documentation page for more details <https://cloud.google.com/spanner/docs/schema-design#primary-key-prevent-hotspots>`__.
+
+Auto-generated primary keys must be returned by Spanner after each insert
+statement using a ``THEN RETURN`` clause. ``THEN RETURN`` clauses are not
+supported with `Batch DML <https://cloud.google.com/spanner/docs/dml-tasks#use-batch>`__.
+It is therefore recommended to use for example client-side generated UUIDs
+as primary key values instead.
 
 Query hints
 ~~~~~~~~~~~

samples/auto_generated_primary_key_sample.py

@@ -0,0 +1,59 @@
+# Copyright 2025 Google LLC All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import datetime
+import uuid
+
+from sqlalchemy import create_engine
+from sqlalchemy.orm import Session
+
+from sample_helper import run_sample
+from model import Singer, Concert, Venue, TicketSale
+
+
+# Shows how to use an IDENTITY column for primary key generation. IDENTITY
+# columns use a backing bit-reversed sequence to generate unique values that are
+# safe to use for primary keys in Spanner.
+#
+# IDENTITY columns are used by default by the Spanner SQLAlchemy dialect for
+# standard primary key columns.
+#
+# id: Mapped[int] = mapped_column(primary_key=True)
+#
+# This leads to the following table definition:
+#
+# CREATE TABLE ticket_sales (
+# 	id INT64 NOT NULL GENERATED BY DEFAULT AS IDENTITY (BIT_REVERSED_POSITIVE),
+#   ...
+# ) PRIMARY KEY (id)
+def auto_generated_primary_key_sample():
+    engine = create_engine(
+        "spanner:///projects/sample-project/"
+        "instances/sample-instance/"
+        "databases/sample-database",
+        echo=True,
+    )
+    with Session(engine) as session:
+        # Venue automatically generates a primary key value using an IDENTITY
+        # column. We therefore do not need to specify a primary key value when
+        # we create an instance of Venue.
+        venue = Venue(code="CH", name="Concert Hall", active=True)
+        session.add_all([venue])
+        session.commit()
+
+        print("Inserted a venue with ID %d" % venue.id)
+
+
+if __name__ == "__main__":
+    run_sample(auto_generated_primary_key_sample)

samples/model.py

@@ -31,8 +31,7 @@
     ForeignKeyConstraint,
     Sequence,
     TextClause,
-    func,
-    FetchedValue,
+    Index,
 )
 from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship
 
@@ -45,6 +44,10 @@ class Base(DeclarativeBase):
 # This allows inserts to use Batch DML, as the primary key value does not need
 # to be returned from Spanner using a THEN RETURN clause.
 #
+# The Venue model uses a standard auto-generated integer primary key. This uses
+# an IDENTITY column in Spanner. IDENTITY columns use a backing bit-reversed
+# sequence to generate unique values that are safe to use for primary keys.
+#
 # The TicketSale model uses a bit-reversed sequence for primary key generation.
 # This is achieved by creating a bit-reversed sequence and assigning the id
 # column of the model a server_default value that gets the next value from that
@@ -117,7 +120,11 @@ class Track(Base):
 
 class Venue(Base):
     __tablename__ = "venues"
-    code: Mapped[str] = mapped_column(String(10), primary_key=True)
+    __table_args__ = (Index("venues_code_unique", "code", unique=True),)
+    # Venue uses a standard auto-generated primary key.
+    # This translates to an IDENTITY column in Spanner.
+    id: Mapped[int] = mapped_column(primary_key=True)
+    code: Mapped[str] = mapped_column(String(10))
     name: Mapped[str] = mapped_column(String(200), nullable=False)
     description: Mapped[str] = mapped_column(JSON, nullable=True)
     active: Mapped[bool] = mapped_column(Boolean, nullable=False)

samples/noxfile.py

@@ -22,6 +22,11 @@ def hello_world(session):
     _sample(session)
 
 
+@nox.session()
+def auto_generated_primary_key(session):
+    _sample(session)
+
+
 @nox.session()
 def bit_reversed_sequence(session):
     _sample(session)

test/mockserver_tests/test_auto_increment.py

@@ -26,6 +26,7 @@
 from test.mockserver_tests.mock_server_test_base import (
     MockServerTestBase,
     add_result,
+    add_update_count,
 )
 from google.cloud.spanner_admin_database_v1 import UpdateDatabaseDdlRequest
 import google.cloud.spanner_v1.types.type as spanner_type
@@ -147,6 +148,26 @@ def test_insert_row(self):
         is_instance_of(requests[2], ExecuteSqlRequest)
         is_instance_of(requests[3], CommitRequest)
 
+    def test_insert_row_with_pk_value(self):
+        from test.mockserver_tests.auto_increment_model import Singer
+
+        # SQLAlchemy should not use a THEN RETURN clause when a value for the
+        # primary key has been set on the model.
+        add_update_count("INSERT INTO singers (id, name) VALUES (@a0, @a1)", 1)
+        engine = create_engine(
+            "spanner:///projects/p/instances/i/databases/d",
+            connect_args={"client": self.client, "pool": FixedSizePool(size=10)},
+        )
+
+        with Session(engine) as session:
+            # Manually specify a value for the primary key.
+            singer = Singer(id=1, name="Test")
+            session.add(singer)
+            # Flush the session to send the insert statement to the database.
+            session.flush()
+            eq_(1, singer.id)
+            session.commit()
+
     def add_insert_result(self, sql):
         result = result_set.ResultSet(
             dict(