sqlalchemy-spanner 1.7.0__tar.gz → 1.9.0__tar.gz

{sqlalchemy_spanner-1.7.0 → sqlalchemy_spanner-1.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: sqlalchemy-spanner
-Version: 1.7.0
+Version: 1.9.0
 Summary: SQLAlchemy dialect integrated into Cloud Spanner database
 Home-page: https://github.com/cloudspannerecosystem/python-spanner-sqlalchemy
 Author: Google LLC
@@ -75,6 +75,13 @@ Next install the package from the package ``setup.py`` file:
 
 During setup the dialect will be registered with entry points.
 
+Samples
+-------------
+
+The `samples directory <https://github.com/googleapis/python-spanner-sqlalchemy/blob/-/samples/README.md>`__
+contains multiple examples for how to configure and use common Spanner features.
+
+
 A Minimal App
 -------------
 
@@ -90,7 +97,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:
@@ -247,7 +254,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:
 
@@ -275,10 +282,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:
 
@@ -289,7 +302,7 @@ 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.
 
@@ -297,8 +310,8 @@ 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.
 
-Autoincremented IDs
-~~~~~~~~~~~~~~~~~~~
+Auto-incremented IDs
+~~~~~~~~~~~~~~~~~~~~
 
 Cloud Spanner doesn't support autoincremented IDs mechanism due to
 performance reasons (`see for more
@@ -354,8 +367,9 @@ ReadOnly transactions
 ~~~~~~~~~~~~~~~~~~~~~
 
 By default, transactions produced by a Spanner connection are in
-ReadWrite mode. However, some applications require an ability to grant
-ReadOnly access to users/methods; for these cases Spanner dialect
+ReadWrite mode. However, workloads that only read data perform better
+if they use read-only transactions, as Spanner does not need to take
+locks for the data that is read; for these cases, the Spanner dialect
 supports the ``read_only`` execution option, which switches a connection
 into ReadOnly mode:
 
@@ -364,11 +378,13 @@ into ReadOnly mode:
    with engine.connect().execution_options(read_only=True) as connection:
        connection.execute(select(["*"], from_obj=table)).fetchall()
 
-Note that execution options are applied lazily - on the ``execute()``
-method call, right before it.
+See the `Read-only transaction sample
+<https://github.com/googleapis/python-spanner-sqlalchemy/blob/-/samples/read_only_transaction_sample.py>`__
+for a concrete example.
 
 ReadOnly/ReadWrite mode of a connection can't be changed while a
-transaction is in progress - first you must commit or rollback it.
+transaction is in progress - you must commit or rollback the current
+transaction before changing the mode.
 
 Stale reads
 ~~~~~~~~~~~
@@ -525,7 +541,7 @@ run the tests the ``nox`` package commands can be used:
 Running tests on Spanner emulator
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The dialect test suite can be runned on `Spanner
+The dialect test suite can be run on `Spanner
 emulator <https://cloud.google.com/spanner/docs/emulator>`__. Several
 tests, relating to ``NULL`` values of data types, are skipped when
 executed on emulator.

{sqlalchemy_spanner-1.7.0 → sqlalchemy_spanner-1.9.0}/README.rst

@@ -58,6 +58,13 @@ Next install the package from the package ``setup.py`` file:
 
 During setup the dialect will be registered with entry points.
 
+Samples
+-------------
+
+The `samples directory <https://github.com/googleapis/python-spanner-sqlalchemy/blob/-/samples/README.md>`__
+contains multiple examples for how to configure and use common Spanner features.
+
+
 A Minimal App
 -------------
 
@@ -73,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:
@@ -230,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:
 
@@ -258,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:
 
@@ -272,7 +285,7 @@ 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.
 
@@ -280,8 +293,8 @@ 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.
 
-Autoincremented IDs
-~~~~~~~~~~~~~~~~~~~
+Auto-incremented IDs
+~~~~~~~~~~~~~~~~~~~~
 
 Cloud Spanner doesn't support autoincremented IDs mechanism due to
 performance reasons (`see for more
@@ -337,8 +350,9 @@ ReadOnly transactions
 ~~~~~~~~~~~~~~~~~~~~~
 
 By default, transactions produced by a Spanner connection are in
-ReadWrite mode. However, some applications require an ability to grant
-ReadOnly access to users/methods; for these cases Spanner dialect
+ReadWrite mode. However, workloads that only read data perform better
+if they use read-only transactions, as Spanner does not need to take
+locks for the data that is read; for these cases, the Spanner dialect
 supports the ``read_only`` execution option, which switches a connection
 into ReadOnly mode:
 
@@ -347,11 +361,13 @@ into ReadOnly mode:
    with engine.connect().execution_options(read_only=True) as connection:
        connection.execute(select(["*"], from_obj=table)).fetchall()
 
-Note that execution options are applied lazily - on the ``execute()``
-method call, right before it.
+See the `Read-only transaction sample
+<https://github.com/googleapis/python-spanner-sqlalchemy/blob/-/samples/read_only_transaction_sample.py>`__
+for a concrete example.
 
 ReadOnly/ReadWrite mode of a connection can't be changed while a
-transaction is in progress - first you must commit or rollback it.
+transaction is in progress - you must commit or rollback the current
+transaction before changing the mode.
 
 Stale reads
 ~~~~~~~~~~~
@@ -508,7 +524,7 @@ run the tests the ``nox`` package commands can be used:
 Running tests on Spanner emulator
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The dialect test suite can be runned on `Spanner
+The dialect test suite can be run on `Spanner
 emulator <https://cloud.google.com/spanner/docs/emulator>`__. Several
 tests, relating to ``NULL`` values of data types, are skipped when
 executed on emulator.

sqlalchemy_spanner-1.9.0/google/cloud/sqlalchemy_spanner/dml.py

@@ -0,0 +1,26 @@
+# Copyright 2024 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.
+
+from sqlalchemy import Insert, insert
+from sqlalchemy.sql._typing import _DMLTableArgument
+
+
+def insert_or_update(table: _DMLTableArgument) -> Insert:
+    """Construct a Spanner-specific insert-or-update statement."""
+    return insert(table).prefix_with("OR UPDATE")
+
+
+def insert_or_ignore(table: _DMLTableArgument) -> Insert:
+    """Construct a Spanner-specific insert-or-ignore statement."""
+    return insert(table).prefix_with("OR IGNORE")

{sqlalchemy_spanner-1.7.0 → sqlalchemy_spanner-1.9.0}/google/cloud/sqlalchemy_spanner/sqlalchemy_spanner.py

@@ -22,6 +22,9 @@ from alembic.ddl.base import (
     alter_table,
     format_type,
 )
+from google.api_core.client_options import ClientOptions
+from google.auth.credentials import AnonymousCredentials
+from google.cloud.spanner_v1 import Client
 from sqlalchemy.exc import NoSuchTableError
 from sqlalchemy.sql import elements
 from sqlalchemy import ForeignKeyConstraint, types
@@ -81,6 +84,7 @@ _type_map = {
     "BYTES": types.LargeBinary,
     "DATE": types.DATE,
     "DATETIME": types.DATETIME,
+    "FLOAT32": types.REAL,
     "FLOAT64": types.Float,
     "INT64": types.BIGINT,
     "NUMERIC": types.NUMERIC(precision=38, scale=9),
@@ -98,6 +102,7 @@ _type_map_inv = {
     types.LargeBinary: "BYTES(MAX)",
     types.DATE: "DATE",
     types.DATETIME: "DATETIME",
+    types.REAL: "FLOAT32",
     types.Float: "FLOAT64",
     types.BIGINT: "INT64",
     types.DECIMAL: "NUMERIC",
@@ -175,6 +180,14 @@ class SpannerExecutionContext(DefaultExecutionContext):
         if priority is not None:
             self._dbapi_connection.connection.request_priority = priority
 
+        transaction_tag = self.execution_options.get("transaction_tag")
+        if transaction_tag:
+            self._dbapi_connection.connection.transaction_tag = transaction_tag
+
+        request_tag = self.execution_options.get("request_tag")
+        if request_tag:
+            self.cursor.request_tag = request_tag
+
     def fire_sequence(self, seq, type_):
         """Builds a statement for fetching next value of the sequence."""
         return self._execute_scalar(
@@ -230,6 +243,9 @@ class SpannerSQLCompiler(SQLCompiler):
         """
         return text
 
+    def visit_now_func(self, func, **kwargs):
+        return "current_timestamp"
+
     def visit_empty_set_expr(self, type_, **kw):
         """Return an empty set expression of the given type.
 
@@ -489,6 +505,26 @@ class SpannerDDLCompiler(DDLCompiler):
 
         return post_cmds
 
+    def visit_create_index(
+        self, create, include_schema=False, include_table_schema=True, **kw
+    ):
+        text = super().visit_create_index(
+            create, include_schema, include_table_schema, **kw
+        )
+        index = create.element
+        if "spanner" in index.dialect_options:
+            options = index.dialect_options["spanner"]
+            if "storing" in options:
+                storing = options["storing"]
+                storing_columns = [
+                    index.table.c[col] if isinstance(col, str) else col
+                    for col in storing
+                ]
+                text += " STORING (%s)" % ", ".join(
+                    [self.preparer.quote(c.name) for c in storing_columns]
+                )
+        return text
+
     def get_identity_options(self, identity_options):
         text = ["sequence_kind = 'bit_reversed_positive'"]
         if identity_options.start is not None:
@@ -517,9 +553,18 @@ class SpannerTypeCompiler(GenericTypeCompiler):
     def visit_INTEGER(self, type_, **kw):
         return "INT64"
 
+    def visit_DOUBLE(self, type_, **kw):
+        return "FLOAT64"
+
     def visit_FLOAT(self, type_, **kw):
+        # Note: This was added before Spanner supported FLOAT32.
+        # Changing this now to generate a FLOAT32 would be a breaking change.
+        # Users therefore have to use REAL to generate a FLOAT32 column.
         return "FLOAT64"
 
+    def visit_REAL(self, type_, **kw):
+        return "FLOAT32"
+
     def visit_TEXT(self, type_, **kw):
         return "STRING({})".format(type_.length or "MAX")
 
@@ -588,6 +633,10 @@ class SpannerDialect(DefaultDialect):
     supports_native_decimal = True
     supports_statement_cache = True
 
+    insert_returning = True
+    update_returning = True
+    delete_returning = True
+
     ddl_compiler = SpannerDDLCompiler
     preparer = SpannerIdentifierPreparer
     statement_compiler = SpannerSQLCompiler
@@ -709,9 +758,29 @@ class SpannerDialect(DefaultDialect):
             url.database,
         )
         dist = pkg_resources.get_distribution("sqlalchemy-spanner")
+        options = {"user_agent": f"gl-{dist.project_name}/{dist.version}"}
+        connect_opts = url.translate_connect_args()
+        if (
+            "host" in connect_opts
+            and "port" in connect_opts
+            and "password" in connect_opts
+        ):
+            # Create a test client that connects to a local Spanner (mock) server.
+            if (
+                connect_opts["host"] == "localhost"
+                and connect_opts["password"] == "AnonymousCredentials"
+            ):
+                client = Client(
+                    project=match.group("project"),
+                    credentials=AnonymousCredentials(),
+                    client_options=ClientOptions(
+                        api_endpoint=f"{connect_opts['host']}:{connect_opts['port']}",
+                    ),
+                )
+                options["client"] = client
         return (
             [match.group("instance"), match.group("database"), match.group("project")],
-            {"user_agent": f"gl-{dist.project_name}/{dist.version}"},
+            options,
         )
 
     @engine_to_connection
@@ -974,15 +1043,35 @@ class SpannerDialect(DefaultDialect):
                i.table_schema,
                i.table_name,
                i.index_name,
-               ARRAY_AGG(ic.column_name),
+               (
+                   SELECT ARRAY_AGG(ic.column_name)
+                   FROM information_schema.index_columns ic
+                   WHERE ic.index_name = i.index_name
+                   AND ic.table_catalog = i.table_catalog
+                   AND ic.table_schema = i.table_schema
+                   AND ic.table_name = i.table_name
+                   AND ic.column_ordering is not null
+               ) as columns,
                i.is_unique,
-               ARRAY_AGG(ic.column_ordering)
+               (
+                   SELECT ARRAY_AGG(ic.column_ordering)
+                   FROM information_schema.index_columns ic
+                   WHERE ic.index_name = i.index_name
+                   AND ic.table_catalog = i.table_catalog
+                   AND ic.table_schema = i.table_schema
+                   AND ic.table_name = i.table_name
+                   AND ic.column_ordering is not null
+               ) as column_orderings,
+               (
+                   SELECT ARRAY_AGG(storing.column_name)
+                   FROM information_schema.index_columns storing
+                   WHERE storing.index_name = i.index_name
+                   AND storing.table_catalog = i.table_catalog
+                   AND storing.table_schema = i.table_schema
+                   AND storing.table_name = i.table_name
+                   AND storing.column_ordering is null
+               ) as storing_columns,
             FROM information_schema.indexes as i
-            JOIN information_schema.index_columns AS ic
-                ON  ic.index_name = i.index_name
-                AND ic.table_catalog = i.table_catalog
-                AND ic.table_schema = i.table_schema
-                AND ic.table_name = i.table_name
             JOIN information_schema.tables AS t
                 ON  i.table_catalog = t.table_catalog
                 AND i.table_schema = t.table_schema
@@ -993,7 +1082,8 @@ class SpannerDialect(DefaultDialect):
                 {schema_filter_query}
                 i.index_type != 'PRIMARY_KEY'
                 AND i.spanner_is_managed = FALSE
-            GROUP BY i.table_schema, i.table_name, i.index_name, i.is_unique
+            GROUP BY i.table_catalog, i.table_schema, i.table_name,
+                     i.index_name, i.is_unique
             ORDER BY i.index_name
         """.format(
             table_filter_query=table_filter_query,
@@ -1006,13 +1096,19 @@ class SpannerDialect(DefaultDialect):
             result_dict = {}
 
             for row in rows:
+                dialect_options = {}
+                include_columns = row[6]
+                if include_columns:
+                    dialect_options["spanner_storing"] = include_columns
                 index_info = {
                     "name": row[2],
                     "column_names": row[3],
                     "unique": row[4],
                     "column_sorting": {
-                        col: order for col, order in zip(row[3], row[5])
+                        col: order.lower() for col, order in zip(row[3], row[5])
                     },
+                    "include_columns": include_columns if include_columns else [],
+                    "dialect_options": dialect_options,
                 }
                 row[0] = row[0] or None
                 table_info = result_dict.get((row[0], row[1]), [])
@@ -1541,8 +1637,9 @@ def visit_column_nullable(
 def visit_column_type(
     element: "ColumnType", compiler: "SpannerDDLCompiler", **kw
 ) -> str:
-    return "%s %s %s" % (
+    return "%s %s %s %s" % (
         alter_table(compiler, element.table_name, element.schema),
         alter_column(compiler, element.column_name),
         "%s" % format_type(compiler, element.type_),
+        "" if element.existing_nullable else "NOT NULL",
     )

{sqlalchemy_spanner-1.7.0 → sqlalchemy_spanner-1.9.0}/setup.py

@@ -14,6 +14,8 @@
 
 import io
 import os
+import warnings
+
 import setuptools
 
 
@@ -59,24 +61,26 @@ namespaces = ["google"]
 if "google.cloud" in packages:
     namespaces.append("google.cloud")
 
-setuptools.setup(
-    author="Google LLC",
-    author_email="cloud-spanner-developers@googlegroups.com",
-    classifiers=["Intended Audience :: Developers"],
-    description=description,
-    long_description=readme,
-    entry_points={
-        "sqlalchemy.dialects": [
-            "spanner.spanner = google.cloud.sqlalchemy_spanner:SpannerDialect"
-        ]
-    },
-    install_requires=dependencies,
-    extras_require=extras,
-    name=name,
-    namespace_packages=namespaces,
-    packages=packages,
-    url="https://github.com/cloudspannerecosystem/python-spanner-sqlalchemy",
-    version=version,
-    include_package_data=True,
-    zip_safe=False,
-)
+with warnings.catch_warnings():
+    warnings.simplefilter("ignore")
+    setuptools.setup(
+        author="Google LLC",
+        author_email="cloud-spanner-developers@googlegroups.com",
+        classifiers=["Intended Audience :: Developers"],
+        description=description,
+        long_description=readme,
+        entry_points={
+            "sqlalchemy.dialects": [
+                "spanner.spanner = google.cloud.sqlalchemy_spanner:SpannerDialect"
+            ]
+        },
+        install_requires=dependencies,
+        extras_require=extras,
+        name=name,
+        namespace_packages=namespaces,
+        packages=packages,
+        url="https://github.com/cloudspannerecosystem/python-spanner-sqlalchemy",
+        version=version,
+        include_package_data=True,
+        zip_safe=False,
+    )

{sqlalchemy_spanner-1.7.0 → sqlalchemy_spanner-1.9.0}/sqlalchemy_spanner.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: sqlalchemy-spanner
-Version: 1.7.0
+Version: 1.9.0
 Summary: SQLAlchemy dialect integrated into Cloud Spanner database
 Home-page: https://github.com/cloudspannerecosystem/python-spanner-sqlalchemy
 Author: Google LLC
@@ -75,6 +75,13 @@ Next install the package from the package ``setup.py`` file:
 
 During setup the dialect will be registered with entry points.
 
+Samples
+-------------
+
+The `samples directory <https://github.com/googleapis/python-spanner-sqlalchemy/blob/-/samples/README.md>`__
+contains multiple examples for how to configure and use common Spanner features.
+
+
 A Minimal App
 -------------
 
@@ -90,7 +97,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:
@@ -247,7 +254,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:
 
@@ -275,10 +282,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:
 
@@ -289,7 +302,7 @@ 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.
 
@@ -297,8 +310,8 @@ 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.
 
-Autoincremented IDs
-~~~~~~~~~~~~~~~~~~~
+Auto-incremented IDs
+~~~~~~~~~~~~~~~~~~~~
 
 Cloud Spanner doesn't support autoincremented IDs mechanism due to
 performance reasons (`see for more
@@ -354,8 +367,9 @@ ReadOnly transactions
 ~~~~~~~~~~~~~~~~~~~~~
 
 By default, transactions produced by a Spanner connection are in
-ReadWrite mode. However, some applications require an ability to grant
-ReadOnly access to users/methods; for these cases Spanner dialect
+ReadWrite mode. However, workloads that only read data perform better
+if they use read-only transactions, as Spanner does not need to take
+locks for the data that is read; for these cases, the Spanner dialect
 supports the ``read_only`` execution option, which switches a connection
 into ReadOnly mode:
 
@@ -364,11 +378,13 @@ into ReadOnly mode:
    with engine.connect().execution_options(read_only=True) as connection:
        connection.execute(select(["*"], from_obj=table)).fetchall()
 
-Note that execution options are applied lazily - on the ``execute()``
-method call, right before it.
+See the `Read-only transaction sample
+<https://github.com/googleapis/python-spanner-sqlalchemy/blob/-/samples/read_only_transaction_sample.py>`__
+for a concrete example.
 
 ReadOnly/ReadWrite mode of a connection can't be changed while a
-transaction is in progress - first you must commit or rollback it.
+transaction is in progress - you must commit or rollback the current
+transaction before changing the mode.
 
 Stale reads
 ~~~~~~~~~~~
@@ -525,7 +541,7 @@ run the tests the ``nox`` package commands can be used:
 Running tests on Spanner emulator
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The dialect test suite can be runned on `Spanner
+The dialect test suite can be run on `Spanner
 emulator <https://cloud.google.com/spanner/docs/emulator>`__. Several
 tests, relating to ``NULL`` values of data types, are skipped when
 executed on emulator.

{sqlalchemy_spanner-1.7.0 → sqlalchemy_spanner-1.9.0}/sqlalchemy_spanner.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ google/__init__.py
 google/cloud/__init__.py
 google/cloud/sqlalchemy_spanner/__init__.py
 google/cloud/sqlalchemy_spanner/_opentelemetry_tracing.py
+google/cloud/sqlalchemy_spanner/dml.py
 google/cloud/sqlalchemy_spanner/provision.py
 google/cloud/sqlalchemy_spanner/requirements.py
 google/cloud/sqlalchemy_spanner/sqlalchemy_spanner.py

{sqlalchemy_spanner-1.7.0 → sqlalchemy_spanner-1.9.0}/test/test_suite_13.py

@@ -1300,6 +1300,9 @@ class NumericTest(_NumericTest):
             filter_=lambda n: n is not None and round(n, 5) or None,
         )
 
+    def test_float_coerce_round_trip(self, connection):
+        pass
+
     @requires.precision_numerics_general
     def test_precision_decimal(self):
         """
@@ -2065,6 +2068,49 @@ class CreateEngineWithoutDatabaseTest(fixtures.TestBase):
             assert connection.connection.database is None
 
 
+class ReturningTest(fixtures.TestBase):
+    def setUp(self):
+        self._engine = create_engine(get_db_url())
+        metadata = MetaData()
+
+        self._table = Table(
+            "returning_test",
+            metadata,
+            Column("id", Integer, primary_key=True),
+            Column("data", String(16), nullable=False),
+        )
+
+        metadata.create_all(self._engine)
+
+    def test_returning_for_insert_and_update(self):
+        random_id = random.randint(1, 1000)
+        with self._engine.begin() as connection:
+            stmt = (
+                self._table.insert()
+                .values(id=random_id, data="some % value")
+                .returning(self._table.c.id)
+            )
+            row = connection.execute(stmt).fetchall()
+            eq_(
+                row,
+                [(random_id,)],
+            )
+
+        with self._engine.begin() as connection:
+            update_text = "some + value"
+            stmt = (
+                self._table.update()
+                .values(data=update_text)
+                .where(self._table.c.id == random_id)
+                .returning(self._table.c.data)
+            )
+            row = connection.execute(stmt).fetchall()
+            eq_(
+                row,
+                [(update_text,)],
+            )
+
+
 @pytest.mark.skipif(
     bool(os.environ.get("SPANNER_EMULATOR_HOST")), reason="Skipped on emulator"
 )

{sqlalchemy_spanner-1.7.0 → sqlalchemy_spanner-1.9.0}/test/test_suite_14.py

@@ -27,7 +27,7 @@ from unittest import mock
 from google.cloud.spanner_v1 import RequestOptions, Client
 
 import sqlalchemy
-from sqlalchemy import create_engine
+from sqlalchemy import create_engine, literal, FLOAT
 from sqlalchemy import inspect
 from sqlalchemy import testing
 from sqlalchemy import ForeignKey
@@ -53,6 +53,7 @@ from sqlalchemy import Boolean
 from sqlalchemy import Float
 from sqlalchemy import LargeBinary
 from sqlalchemy import String
+from sqlalchemy.sql.expression import cast
 from sqlalchemy.ext.declarative import declarative_base
 from sqlalchemy.orm import relation
 from sqlalchemy.orm import Session
@@ -1650,6 +1651,13 @@ class NumericTest(_NumericTest):
             filter_=lambda n: n is not None and round(n, 5) or None,
         )
 
+    @testing.requires.literal_float_coercion
+    def test_float_coerce_round_trip(self, connection):
+        expr = 15.7563
+
+        val = connection.scalar(select(cast(literal(expr), FLOAT)))
+        eq_(val, expr)
+
     @requires.precision_numerics_general
     def test_precision_decimal(self, do_numeric_test):
         """
@@ -2399,6 +2407,49 @@ class CreateEngineWithoutDatabaseTest(fixtures.TestBase):
             assert connection.connection.database is None
 
 
+class ReturningTest(fixtures.TestBase):
+    def setUp(self):
+        self._engine = create_engine(get_db_url())
+        metadata = MetaData()
+
+        self._table = Table(
+            "returning_test",
+            metadata,
+            Column("id", Integer, primary_key=True),
+            Column("data", String(16), nullable=False),
+        )
+
+        metadata.create_all(self._engine)
+
+    def test_returning_for_insert_and_update(self):
+        random_id = random.randint(1, 1000)
+        with self._engine.begin() as connection:
+            stmt = (
+                self._table.insert()
+                .values(id=random_id, data="some % value")
+                .returning(self._table.c.id)
+            )
+            row = connection.execute(stmt).fetchall()
+            eq_(
+                row,
+                [(random_id,)],
+            )
+
+        with self._engine.begin() as connection:
+            update_text = "some + value"
+            stmt = (
+                self._table.update()
+                .values(data=update_text)
+                .where(self._table.c.id == random_id)
+                .returning(self._table.c.data)
+            )
+            row = connection.execute(stmt).fetchall()
+            eq_(
+                row,
+                [(update_text,)],
+            )
+
+
 @pytest.mark.skipif(
     bool(os.environ.get("SPANNER_EMULATOR_HOST")), reason="Skipped on emulator"
 )

{sqlalchemy_spanner-1.7.0 → sqlalchemy_spanner-1.9.0}/test/test_suite_20.py

@@ -26,7 +26,7 @@ from unittest import mock
 
 from google.cloud.spanner_v1 import RequestOptions, Client
 import sqlalchemy
-from sqlalchemy import create_engine
+from sqlalchemy import create_engine, literal, FLOAT
 from sqlalchemy.engine import Inspector
 from sqlalchemy import inspect
 from sqlalchemy import testing
@@ -55,6 +55,7 @@ from sqlalchemy import Boolean
 from sqlalchemy import Float
 from sqlalchemy import LargeBinary
 from sqlalchemy import String
+from sqlalchemy.sql.expression import cast
 from sqlalchemy.ext.declarative import declarative_base
 from sqlalchemy.orm import relationship
 from sqlalchemy.orm import Session
@@ -80,7 +81,9 @@ from sqlalchemy.testing.suite.test_insert import *  # noqa: F401, F403
 from sqlalchemy.testing.suite.test_reflection import *  # noqa: F401, F403
 from sqlalchemy.testing.suite.test_deprecations import *  # noqa: F401, F403
 from sqlalchemy.testing.suite.test_results import *  # noqa: F401, F403
-from sqlalchemy.testing.suite.test_select import *  # noqa: F401, F403
+from sqlalchemy.testing.suite.test_select import (
+    BitwiseTest as _BitwiseTest,
+)  # noqa: F401, F403
 from sqlalchemy.testing.suite.test_sequence import (
     SequenceTest as _SequenceTest,
     HasSequenceTest as _HasSequenceTest,
@@ -192,6 +195,12 @@ class BooleanTest(_BooleanTest):
         pass
 
 
+class BitwiseTest(_BitwiseTest):
+    @pytest.mark.skip("Causes too many problems with other tests")
+    def test_bitwise(self, case, expected, connection):
+        pass
+
+
 class ComponentReflectionTestExtra(_ComponentReflectionTestExtra):
     @testing.requires.table_reflection
     def test_nullable_reflection(self, connection, metadata):
@@ -1018,6 +1027,10 @@ class ComponentReflectionTest(_ComponentReflectionTest):
         tables to be read, and in Spanner all the tables are real,
         expected results override is required.
         """
+        _ignore_tables = [
+            "bitwise",
+        ]
+
         insp, kws, exp = get_multi_exp(
             schema,
             scope,
@@ -1030,6 +1043,8 @@ class ComponentReflectionTest(_ComponentReflectionTest):
         for kw in kws:
             insp.clear_cache()
             result = insp.get_multi_columns(**kw)
+            for t in _ignore_tables:
+                result.pop((schema, t), None)
             self._check_table_dict(result, exp, self._required_column_keys)
 
     @pytest.mark.skip(
@@ -1097,6 +1112,7 @@ class ComponentReflectionTest(_ComponentReflectionTest):
         _ignore_tables = [
             "account",
             "alembic_version",
+            "bitwise",
             "bytes_table",
             "comment_test",
             "date_table",
@@ -1306,6 +1322,7 @@ class ComponentReflectionTest(_ComponentReflectionTest):
         expected results override is required.
         """
         _ignore_tables = [
+            "bitwise",
             "comment_test",
             "noncol_idx_test_pk",
             "noncol_idx_test_nopk",
@@ -1398,7 +1415,7 @@ class ComponentReflectionTest(_ComponentReflectionTest):
                 "include_columns": [],
             }
             if column_sorting:
-                res["column_sorting"] = {"q": "DESC"}
+                res["column_sorting"] = {"q": "desc"}
             if duplicates:
                 res["duplicates_constraint"] = name
             return [res]
@@ -1442,11 +1459,11 @@ class ComponentReflectionTest(_ComponentReflectionTest):
                 *idx(
                     "q",
                     name="noncol_idx_nopk",
-                    column_sorting={"q": "DESC"},
+                    column_sorting={"q": "desc"},
                 )
             ],
             (schema, "noncol_idx_test_pk"): [
-                *idx("q", name="noncol_idx_pk", column_sorting={"q": "DESC"})
+                *idx("q", name="noncol_idx_pk", column_sorting={"q": "desc"})
             ],
             (schema, self.temp_table_name()): [
                 *idx("foo", name="user_tmp_ix"),
@@ -1688,7 +1705,7 @@ class DateTimeMicrosecondsTest(_DateTimeMicrosecondsTest, DateTest):
             connection.execute(date_table.insert(), {"date_data": self.data, "id": 250})
             row = connection.execute(select(date_table.c.date_data)).first()
 
-        compare = self.compare or self.data
+        compare = self.compare or self.data.astimezone(timezone.utc)
         compare = compare.strftime("%Y-%m-%dT%H:%M:%S.%fZ")
         eq_(row[0].rfc3339(), compare)
         assert isinstance(row[0], DatetimeWithNanoseconds)
@@ -1708,7 +1725,7 @@ class DateTimeMicrosecondsTest(_DateTimeMicrosecondsTest, DateTest):
 
         row = connection.execute(select(date_table.c.decorated_date_data)).first()
 
-        compare = self.compare or self.data
+        compare = self.compare or self.data.astimezone(timezone.utc)
         compare = compare.strftime("%Y-%m-%dT%H:%M:%S.%fZ")
         eq_(row[0].rfc3339(), compare)
         assert isinstance(row[0], DatetimeWithNanoseconds)
@@ -2105,7 +2122,7 @@ class RowFetchTest(_RowFetchTest):
 
         eq_(
             row.somelabel,
-            DatetimeWithNanoseconds(2006, 5, 12, 12, 0, 0, tzinfo=timezone.utc),
+            DatetimeWithNanoseconds(2006, 5, 12, 12, 0, 0).astimezone(timezone.utc),
         )
 
 
@@ -2155,6 +2172,32 @@ class InsertBehaviorTest(_InsertBehaviorTest):
         assert r.is_insert
         assert not r.returns_rows
 
+    def test_autoclose_on_insert_implicit_returning(self, connection):
+        """
+        SPANNER OVERRIDE:
+
+        Cloud Spanner doesn't support tables with an auto increment primary key,
+        following insertions will fail with `400 id must not be NULL in table
+        autoinc_pk`.
+
+        Overriding the tests and adding a manual primary key value to avoid the same
+        failures.
+        """
+        r = connection.execute(
+            # return_defaults() ensures RETURNING will be used,
+            # new in 2.0 as sqlite/mariadb offer both RETURNING and
+            # cursor.lastrowid
+            self.tables.autoinc_pk.insert().return_defaults(),
+            dict(id=2, data="some data"),
+        )
+        assert r._soft_closed
+        assert not r.closed
+        assert r.is_insert
+
+        # Spanner does not return any rows in this case, because the primary key
+        # is not auto-generated.
+        assert not r.returns_rows
+
 
 class BytesTest(_LiteralRoundTripFixture, fixtures.TestBase):
     __backend__ = True
@@ -2413,6 +2456,13 @@ class NumericTest(_NumericTest):
             filter_=lambda n: n is not None and round(n, 5) or None,
         )
 
+    @testing.requires.literal_float_coercion
+    def test_float_coerce_round_trip(self, connection):
+        expr = 15.7563
+
+        val = connection.scalar(select(cast(literal(expr), FLOAT)))
+        eq_(val, expr)
+
     @requires.precision_numerics_general
     def test_precision_decimal(self, do_numeric_test):
         """
@@ -3097,6 +3147,49 @@ class CreateEngineWithoutDatabaseTest(fixtures.TestBase):
             assert connection.connection.database is None
 
 
+class ReturningTest(fixtures.TestBase):
+    def setUp(self):
+        self._engine = create_engine(get_db_url())
+        metadata = MetaData()
+
+        self._table = Table(
+            "returning_test",
+            metadata,
+            Column("id", Integer, primary_key=True),
+            Column("data", String(16), nullable=False),
+        )
+
+        metadata.create_all(self._engine)
+
+    def test_returning_for_insert_and_update(self):
+        random_id = random.randint(1, 1000)
+        with self._engine.begin() as connection:
+            stmt = (
+                self._table.insert()
+                .values(id=random_id, data="some % value")
+                .returning(self._table.c.id)
+            )
+            row = connection.execute(stmt).fetchall()
+            eq_(
+                row,
+                [(random_id,)],
+            )
+
+        with self._engine.begin() as connection:
+            update_text = "some + value"
+            stmt = (
+                self._table.update()
+                .values(data=update_text)
+                .where(self._table.c.id == random_id)
+                .returning(self._table.c.data)
+            )
+            row = connection.execute(stmt).fetchall()
+            eq_(
+                row,
+                [(update_text,)],
+            )
+
+
 @pytest.mark.skipif(
     bool(os.environ.get("SPANNER_EMULATOR_HOST")), reason="Skipped on emulator"
 )