google-apis-spanner_v1 0.28.0 → 0.29.0

data/lib/google/apis/spanner_v1/classes.rb

@@ -228,165 +228,45 @@ module Google
       class BeginTransactionRequest
         include Google::Apis::Core::Hashable
       
-        # Transactions: Each session can have at most one active transaction at a time (
-        # note that standalone reads and queries use a transaction internally and do
-        # count towards the one transaction limit). After the active transaction is
-        # completed, the session can immediately be re-used for the next transaction. It
-        # is not necessary to create a new session for each transaction. Transaction
-        # modes: Cloud Spanner supports three transaction modes: 1. Locking read-write.
-        # This type of transaction is the only way to write data into Cloud Spanner.
-        # These transactions rely on pessimistic locking and, if necessary, two-phase
-        # commit. Locking read-write transactions may abort, requiring the application
-        # to retry. 2. Snapshot read-only. This transaction type provides guaranteed
-        # consistency across several reads, but does not allow writes. Snapshot read-
-        # only transactions can be configured to read at timestamps in the past.
-        # Snapshot read-only transactions do not need to be committed. 3. Partitioned
-        # DML. This type of transaction is used to execute a single Partitioned DML
-        # statement. Partitioned DML partitions the key space and runs the DML statement
-        # over each partition in parallel using separate, internal transactions that
-        # commit independently. Partitioned DML transactions do not need to be committed.
-        # For transactions that only read, snapshot read-only transactions provide
-        # simpler semantics and are almost always faster. In particular, read-only
-        # transactions do not take locks, so they do not conflict with read-write
-        # transactions. As a consequence of not taking locks, they also do not abort, so
-        # retry loops are not needed. Transactions may only read-write data in a single
-        # database. They may, however, read-write data in different tables within that
-        # database. Locking read-write transactions: Locking transactions may be used to
-        # atomically read-modify-write data anywhere in a database. This type of
-        # transaction is externally consistent. Clients should attempt to minimize the
-        # amount of time a transaction is active. Faster transactions commit with higher
-        # probability and cause less contention. Cloud Spanner attempts to keep read
-        # locks active as long as the transaction continues to do reads, and the
-        # transaction has not been terminated by Commit or Rollback. Long periods of
-        # inactivity at the client may cause Cloud Spanner to release a transaction's
-        # locks and abort it. Conceptually, a read-write transaction consists of zero or
-        # more reads or SQL statements followed by Commit. At any time before Commit,
-        # the client can send a Rollback request to abort the transaction. Semantics:
-        # Cloud Spanner can commit the transaction if all read locks it acquired are
-        # still valid at commit time, and it is able to acquire write locks for all
-        # writes. Cloud Spanner can abort the transaction for any reason. If a commit
-        # attempt returns `ABORTED`, Cloud Spanner guarantees that the transaction has
-        # not modified any user data in Cloud Spanner. Unless the transaction commits,
-        # Cloud Spanner makes no guarantees about how long the transaction's locks were
-        # held for. It is an error to use Cloud Spanner locks for any sort of mutual
-        # exclusion other than between Cloud Spanner transactions themselves. Retrying
-        # aborted transactions: When a transaction aborts, the application can choose to
-        # retry the whole transaction again. To maximize the chances of successfully
-        # committing the retry, the client should execute the retry in the same session
-        # as the original attempt. The original session's lock priority increases with
-        # each consecutive abort, meaning that each attempt has a slightly better chance
-        # of success than the previous. Under some circumstances (for example, many
-        # transactions attempting to modify the same row(s)), a transaction can abort
-        # many times in a short period before successfully committing. Thus, it is not a
-        # good idea to cap the number of retries a transaction can attempt; instead, it
-        # is better to limit the total amount of time spent retrying. Idle transactions:
-        # A transaction is considered idle if it has no outstanding reads or SQL queries
-        # and has not started a read or SQL query within the last 10 seconds. Idle
-        # transactions can be aborted by Cloud Spanner so that they don't hold on to
-        # locks indefinitely. If an idle transaction is aborted, the commit will fail
-        # with error `ABORTED`. If this behavior is undesirable, periodically executing
-        # a simple SQL query in the transaction (for example, `SELECT 1`) prevents the
-        # transaction from becoming idle. Snapshot read-only transactions: Snapshot read-
-        # only transactions provides a simpler method than locking read-write
-        # transactions for doing several consistent reads. However, this type of
-        # transaction does not support writes. Snapshot transactions do not take locks.
-        # Instead, they work by choosing a Cloud Spanner timestamp, then executing all
-        # reads at that timestamp. Since they do not acquire locks, they do not block
-        # concurrent read-write transactions. Unlike locking read-write transactions,
-        # snapshot read-only transactions never abort. They can fail if the chosen read
-        # timestamp is garbage collected; however, the default garbage collection policy
-        # is generous enough that most applications do not need to worry about this in
-        # practice. Snapshot read-only transactions do not need to call Commit or
-        # Rollback (and in fact are not permitted to do so). To execute a snapshot
-        # transaction, the client specifies a timestamp bound, which tells Cloud Spanner
-        # how to choose a read timestamp. The types of timestamp bound are: - Strong (
-        # the default). - Bounded staleness. - Exact staleness. If the Cloud Spanner
-        # database to be read is geographically distributed, stale read-only
-        # transactions can execute more quickly than strong or read-write transactions,
-        # because they are able to execute far from the leader replica. Each type of
-        # timestamp bound is discussed in detail below. Strong: Strong reads are
-        # guaranteed to see the effects of all transactions that have committed before
-        # the start of the read. Furthermore, all rows yielded by a single read are
-        # consistent with each other -- if any part of the read observes a transaction,
-        # all parts of the read see the transaction. Strong reads are not repeatable:
-        # two consecutive strong read-only transactions might return inconsistent
-        # results if there are concurrent writes. If consistency across reads is
-        # required, the reads should be executed within a transaction or at an exact
-        # read timestamp. See TransactionOptions.ReadOnly.strong. Exact staleness: These
-        # timestamp bounds execute reads at a user-specified timestamp. Reads at a
-        # timestamp are guaranteed to see a consistent prefix of the global transaction
-        # history: they observe modifications done by all transactions with a commit
-        # timestamp less than or equal to the read timestamp, and observe none of the
-        # modifications done by transactions with a larger commit timestamp. They will
-        # block until all conflicting transactions that may be assigned commit
-        # timestamps <= the read timestamp have finished. The timestamp can either be
-        # expressed as an absolute Cloud Spanner commit timestamp or a staleness
-        # relative to the current time. These modes do not require a "negotiation phase"
-        # to pick a timestamp. As a result, they execute slightly faster than the
-        # equivalent boundedly stale concurrency modes. On the other hand, boundedly
-        # stale reads usually return fresher results. See TransactionOptions.ReadOnly.
-        # read_timestamp and TransactionOptions.ReadOnly.exact_staleness. Bounded
-        # staleness: Bounded staleness modes allow Cloud Spanner to pick the read
-        # timestamp, subject to a user-provided staleness bound. Cloud Spanner chooses
-        # the newest timestamp within the staleness bound that allows execution of the
-        # reads at the closest available replica without blocking. All rows yielded are
-        # consistent with each other -- if any part of the read observes a transaction,
-        # all parts of the read see the transaction. Boundedly stale reads are not
-        # repeatable: two stale reads, even if they use the same staleness bound, can
-        # execute at different timestamps and thus return inconsistent results.
-        # Boundedly stale reads execute in two phases: the first phase negotiates a
-        # timestamp among all replicas needed to serve the read. In the second phase,
-        # reads are executed at the negotiated timestamp. As a result of the two phase
-        # execution, bounded staleness reads are usually a little slower than comparable
-        # exact staleness reads. However, they are typically able to return fresher
-        # results, and are more likely to execute at the closest replica. Because the
-        # timestamp negotiation requires up-front knowledge of which rows will be read,
-        # it can only be used with single-use read-only transactions. See
-        # TransactionOptions.ReadOnly.max_staleness and TransactionOptions.ReadOnly.
-        # min_read_timestamp. Old read timestamps and garbage collection: Cloud Spanner
-        # continuously garbage collects deleted and overwritten data in the background
-        # to reclaim storage space. This process is known as "version GC". By default,
-        # version GC reclaims versions after they are one hour old. Because of this,
-        # Cloud Spanner cannot perform reads at read timestamps more than one hour in
-        # the past. This restriction also applies to in-progress reads and/or SQL
-        # queries whose timestamp become too old while executing. Reads and SQL queries
-        # with too-old read timestamps fail with the error `FAILED_PRECONDITION`. You
-        # can configure and extend the `VERSION_RETENTION_PERIOD` of a database up to a
-        # period as long as one week, which allows Cloud Spanner to perform reads up to
-        # one week in the past. Partitioned DML transactions: Partitioned DML
-        # transactions are used to execute DML statements with a different execution
-        # strategy that provides different, and often better, scalability properties for
-        # large, table-wide operations than DML in a ReadWrite transaction. Smaller
-        # scoped statements, such as an OLTP workload, should prefer using ReadWrite
-        # transactions. Partitioned DML partitions the keyspace and runs the DML
-        # statement on each partition in separate, internal transactions. These
-        # transactions commit automatically when complete, and run independently from
-        # one another. To reduce lock contention, this execution strategy only acquires
-        # read locks on rows that match the WHERE clause of the statement. Additionally,
-        # the smaller per-partition transactions hold locks for less time. That said,
-        # Partitioned DML is not a drop-in replacement for standard DML used in
-        # ReadWrite transactions. - The DML statement must be fully-partitionable.
-        # Specifically, the statement must be expressible as the union of many
-        # statements which each access only a single row of the table. - The statement
-        # is not applied atomically to all rows of the table. Rather, the statement is
-        # applied atomically to partitions of the table, in independent transactions.
-        # Secondary index rows are updated atomically with the base table rows. -
-        # Partitioned DML does not guarantee exactly-once execution semantics against a
-        # partition. The statement will be applied at least once to each partition. It
-        # is strongly recommended that the DML statement should be idempotent to avoid
-        # unexpected results. For instance, it is potentially dangerous to run a
-        # statement such as `UPDATE table SET column = column + 1` as it could be run
-        # multiple times against some rows. - The partitions are committed automatically
-        # - there is no support for Commit or Rollback. If the call returns an error, or
-        # if the client issuing the ExecuteSql call dies, it is possible that some rows
-        # had the statement executed on them successfully. It is also possible that
-        # statement was never executed against other rows. - Partitioned DML
-        # transactions may only contain the execution of a single DML statement via
-        # ExecuteSql or ExecuteStreamingSql. - If any error is encountered during the
-        # execution of the partitioned DML operation (for instance, a UNIQUE INDEX
-        # violation, division by zero, or a value that cannot be stored due to schema
-        # constraints), then the operation is stopped at that point and an error is
-        # returned. It is possible that at this point, some partitions have been
+        # In addition, if TransactionOptions.read_only.return_read_timestamp is set to
+        # true, a special value of 2^63 - 2 will be returned in the Transaction message
+        # that describes the transaction, instead of a valid read timestamp. This
+        # special value should be discarded and not used for any subsequent queries.
+        # Please see https://cloud.google.com/spanner/docs/change-streams for more
+        # details on how to query the change stream TVFs. Partitioned DML transactions:
+        # Partitioned DML transactions are used to execute DML statements with a
+        # different execution strategy that provides different, and often better,
+        # scalability properties for large, table-wide operations than DML in a
+        # ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,
+        # should prefer using ReadWrite transactions. Partitioned DML partitions the
+        # keyspace and runs the DML statement on each partition in separate, internal
+        # transactions. These transactions commit automatically when complete, and run
+        # independently from one another. To reduce lock contention, this execution
+        # strategy only acquires read locks on rows that match the WHERE clause of the
+        # statement. Additionally, the smaller per-partition transactions hold locks for
+        # less time. That said, Partitioned DML is not a drop-in replacement for
+        # standard DML used in ReadWrite transactions. - The DML statement must be fully-
+        # partitionable. Specifically, the statement must be expressible as the union of
+        # many statements which each access only a single row of the table. - The
+        # statement is not applied atomically to all rows of the table. Rather, the
+        # statement is applied atomically to partitions of the table, in independent
+        # transactions. Secondary index rows are updated atomically with the base table
+        # rows. - Partitioned DML does not guarantee exactly-once execution semantics
+        # against a partition. The statement will be applied at least once to each
+        # partition. It is strongly recommended that the DML statement should be
+        # idempotent to avoid unexpected results. For instance, it is potentially
+        # dangerous to run a statement such as `UPDATE table SET column = column + 1` as
+        # it could be run multiple times against some rows. - The partitions are
+        # committed automatically - there is no support for Commit or Rollback. If the
+        # call returns an error, or if the client issuing the ExecuteSql call dies, it
+        # is possible that some rows had the statement executed on them successfully. It
+        # is also possible that statement was never executed against other rows. -
+        # Partitioned DML transactions may only contain the execution of a single DML
+        # statement via ExecuteSql or ExecuteStreamingSql. - If any error is encountered
+        # during the execution of the partitioned DML operation (for instance, a UNIQUE
+        # INDEX violation, division by zero, or a value that cannot be stored due to
+        # schema constraints), then the operation is stopped at that point and an error
+        # is returned. It is possible that at this point, some partitions have been
         # committed (or even committed multiple times), and other partitions have not
         # been run at all. Given the above, Partitioned DML is good fit for large,
         # database-wide, operations that are idempotent, such as deleting old rows from
@@ -543,165 +423,45 @@ module Google
         attr_accessor :return_commit_stats
         alias_method :return_commit_stats?, :return_commit_stats
       
-        # Transactions: Each session can have at most one active transaction at a time (
-        # note that standalone reads and queries use a transaction internally and do
-        # count towards the one transaction limit). After the active transaction is
-        # completed, the session can immediately be re-used for the next transaction. It
-        # is not necessary to create a new session for each transaction. Transaction
-        # modes: Cloud Spanner supports three transaction modes: 1. Locking read-write.
-        # This type of transaction is the only way to write data into Cloud Spanner.
-        # These transactions rely on pessimistic locking and, if necessary, two-phase
-        # commit. Locking read-write transactions may abort, requiring the application
-        # to retry. 2. Snapshot read-only. This transaction type provides guaranteed
-        # consistency across several reads, but does not allow writes. Snapshot read-
-        # only transactions can be configured to read at timestamps in the past.
-        # Snapshot read-only transactions do not need to be committed. 3. Partitioned
-        # DML. This type of transaction is used to execute a single Partitioned DML
-        # statement. Partitioned DML partitions the key space and runs the DML statement
-        # over each partition in parallel using separate, internal transactions that
-        # commit independently. Partitioned DML transactions do not need to be committed.
-        # For transactions that only read, snapshot read-only transactions provide
-        # simpler semantics and are almost always faster. In particular, read-only
-        # transactions do not take locks, so they do not conflict with read-write
-        # transactions. As a consequence of not taking locks, they also do not abort, so
-        # retry loops are not needed. Transactions may only read-write data in a single
-        # database. They may, however, read-write data in different tables within that
-        # database. Locking read-write transactions: Locking transactions may be used to
-        # atomically read-modify-write data anywhere in a database. This type of
-        # transaction is externally consistent. Clients should attempt to minimize the
-        # amount of time a transaction is active. Faster transactions commit with higher
-        # probability and cause less contention. Cloud Spanner attempts to keep read
-        # locks active as long as the transaction continues to do reads, and the
-        # transaction has not been terminated by Commit or Rollback. Long periods of
-        # inactivity at the client may cause Cloud Spanner to release a transaction's
-        # locks and abort it. Conceptually, a read-write transaction consists of zero or
-        # more reads or SQL statements followed by Commit. At any time before Commit,
-        # the client can send a Rollback request to abort the transaction. Semantics:
-        # Cloud Spanner can commit the transaction if all read locks it acquired are
-        # still valid at commit time, and it is able to acquire write locks for all
-        # writes. Cloud Spanner can abort the transaction for any reason. If a commit
-        # attempt returns `ABORTED`, Cloud Spanner guarantees that the transaction has
-        # not modified any user data in Cloud Spanner. Unless the transaction commits,
-        # Cloud Spanner makes no guarantees about how long the transaction's locks were
-        # held for. It is an error to use Cloud Spanner locks for any sort of mutual
-        # exclusion other than between Cloud Spanner transactions themselves. Retrying
-        # aborted transactions: When a transaction aborts, the application can choose to
-        # retry the whole transaction again. To maximize the chances of successfully
-        # committing the retry, the client should execute the retry in the same session
-        # as the original attempt. The original session's lock priority increases with
-        # each consecutive abort, meaning that each attempt has a slightly better chance
-        # of success than the previous. Under some circumstances (for example, many
-        # transactions attempting to modify the same row(s)), a transaction can abort
-        # many times in a short period before successfully committing. Thus, it is not a
-        # good idea to cap the number of retries a transaction can attempt; instead, it
-        # is better to limit the total amount of time spent retrying. Idle transactions:
-        # A transaction is considered idle if it has no outstanding reads or SQL queries
-        # and has not started a read or SQL query within the last 10 seconds. Idle
-        # transactions can be aborted by Cloud Spanner so that they don't hold on to
-        # locks indefinitely. If an idle transaction is aborted, the commit will fail
-        # with error `ABORTED`. If this behavior is undesirable, periodically executing
-        # a simple SQL query in the transaction (for example, `SELECT 1`) prevents the
-        # transaction from becoming idle. Snapshot read-only transactions: Snapshot read-
-        # only transactions provides a simpler method than locking read-write
-        # transactions for doing several consistent reads. However, this type of
-        # transaction does not support writes. Snapshot transactions do not take locks.
-        # Instead, they work by choosing a Cloud Spanner timestamp, then executing all
-        # reads at that timestamp. Since they do not acquire locks, they do not block
-        # concurrent read-write transactions. Unlike locking read-write transactions,
-        # snapshot read-only transactions never abort. They can fail if the chosen read
-        # timestamp is garbage collected; however, the default garbage collection policy
-        # is generous enough that most applications do not need to worry about this in
-        # practice. Snapshot read-only transactions do not need to call Commit or
-        # Rollback (and in fact are not permitted to do so). To execute a snapshot
-        # transaction, the client specifies a timestamp bound, which tells Cloud Spanner
-        # how to choose a read timestamp. The types of timestamp bound are: - Strong (
-        # the default). - Bounded staleness. - Exact staleness. If the Cloud Spanner
-        # database to be read is geographically distributed, stale read-only
-        # transactions can execute more quickly than strong or read-write transactions,
-        # because they are able to execute far from the leader replica. Each type of
-        # timestamp bound is discussed in detail below. Strong: Strong reads are
-        # guaranteed to see the effects of all transactions that have committed before
-        # the start of the read. Furthermore, all rows yielded by a single read are
-        # consistent with each other -- if any part of the read observes a transaction,
-        # all parts of the read see the transaction. Strong reads are not repeatable:
-        # two consecutive strong read-only transactions might return inconsistent
-        # results if there are concurrent writes. If consistency across reads is
-        # required, the reads should be executed within a transaction or at an exact
-        # read timestamp. See TransactionOptions.ReadOnly.strong. Exact staleness: These
-        # timestamp bounds execute reads at a user-specified timestamp. Reads at a
-        # timestamp are guaranteed to see a consistent prefix of the global transaction
-        # history: they observe modifications done by all transactions with a commit
-        # timestamp less than or equal to the read timestamp, and observe none of the
-        # modifications done by transactions with a larger commit timestamp. They will
-        # block until all conflicting transactions that may be assigned commit
-        # timestamps <= the read timestamp have finished. The timestamp can either be
-        # expressed as an absolute Cloud Spanner commit timestamp or a staleness
-        # relative to the current time. These modes do not require a "negotiation phase"
-        # to pick a timestamp. As a result, they execute slightly faster than the
-        # equivalent boundedly stale concurrency modes. On the other hand, boundedly
-        # stale reads usually return fresher results. See TransactionOptions.ReadOnly.
-        # read_timestamp and TransactionOptions.ReadOnly.exact_staleness. Bounded
-        # staleness: Bounded staleness modes allow Cloud Spanner to pick the read
-        # timestamp, subject to a user-provided staleness bound. Cloud Spanner chooses
-        # the newest timestamp within the staleness bound that allows execution of the
-        # reads at the closest available replica without blocking. All rows yielded are
-        # consistent with each other -- if any part of the read observes a transaction,
-        # all parts of the read see the transaction. Boundedly stale reads are not
-        # repeatable: two stale reads, even if they use the same staleness bound, can
-        # execute at different timestamps and thus return inconsistent results.
-        # Boundedly stale reads execute in two phases: the first phase negotiates a
-        # timestamp among all replicas needed to serve the read. In the second phase,
-        # reads are executed at the negotiated timestamp. As a result of the two phase
-        # execution, bounded staleness reads are usually a little slower than comparable
-        # exact staleness reads. However, they are typically able to return fresher
-        # results, and are more likely to execute at the closest replica. Because the
-        # timestamp negotiation requires up-front knowledge of which rows will be read,
-        # it can only be used with single-use read-only transactions. See
-        # TransactionOptions.ReadOnly.max_staleness and TransactionOptions.ReadOnly.
-        # min_read_timestamp. Old read timestamps and garbage collection: Cloud Spanner
-        # continuously garbage collects deleted and overwritten data in the background
-        # to reclaim storage space. This process is known as "version GC". By default,
-        # version GC reclaims versions after they are one hour old. Because of this,
-        # Cloud Spanner cannot perform reads at read timestamps more than one hour in
-        # the past. This restriction also applies to in-progress reads and/or SQL
-        # queries whose timestamp become too old while executing. Reads and SQL queries
-        # with too-old read timestamps fail with the error `FAILED_PRECONDITION`. You
-        # can configure and extend the `VERSION_RETENTION_PERIOD` of a database up to a
-        # period as long as one week, which allows Cloud Spanner to perform reads up to
-        # one week in the past. Partitioned DML transactions: Partitioned DML
-        # transactions are used to execute DML statements with a different execution
-        # strategy that provides different, and often better, scalability properties for
-        # large, table-wide operations than DML in a ReadWrite transaction. Smaller
-        # scoped statements, such as an OLTP workload, should prefer using ReadWrite
-        # transactions. Partitioned DML partitions the keyspace and runs the DML
-        # statement on each partition in separate, internal transactions. These
-        # transactions commit automatically when complete, and run independently from
-        # one another. To reduce lock contention, this execution strategy only acquires
-        # read locks on rows that match the WHERE clause of the statement. Additionally,
-        # the smaller per-partition transactions hold locks for less time. That said,
-        # Partitioned DML is not a drop-in replacement for standard DML used in
-        # ReadWrite transactions. - The DML statement must be fully-partitionable.
-        # Specifically, the statement must be expressible as the union of many
-        # statements which each access only a single row of the table. - The statement
-        # is not applied atomically to all rows of the table. Rather, the statement is
-        # applied atomically to partitions of the table, in independent transactions.
-        # Secondary index rows are updated atomically with the base table rows. -
-        # Partitioned DML does not guarantee exactly-once execution semantics against a
-        # partition. The statement will be applied at least once to each partition. It
-        # is strongly recommended that the DML statement should be idempotent to avoid
-        # unexpected results. For instance, it is potentially dangerous to run a
-        # statement such as `UPDATE table SET column = column + 1` as it could be run
-        # multiple times against some rows. - The partitions are committed automatically
-        # - there is no support for Commit or Rollback. If the call returns an error, or
-        # if the client issuing the ExecuteSql call dies, it is possible that some rows
-        # had the statement executed on them successfully. It is also possible that
-        # statement was never executed against other rows. - Partitioned DML
-        # transactions may only contain the execution of a single DML statement via
-        # ExecuteSql or ExecuteStreamingSql. - If any error is encountered during the
-        # execution of the partitioned DML operation (for instance, a UNIQUE INDEX
-        # violation, division by zero, or a value that cannot be stored due to schema
-        # constraints), then the operation is stopped at that point and an error is
-        # returned. It is possible that at this point, some partitions have been
+        # In addition, if TransactionOptions.read_only.return_read_timestamp is set to
+        # true, a special value of 2^63 - 2 will be returned in the Transaction message
+        # that describes the transaction, instead of a valid read timestamp. This
+        # special value should be discarded and not used for any subsequent queries.
+        # Please see https://cloud.google.com/spanner/docs/change-streams for more
+        # details on how to query the change stream TVFs. Partitioned DML transactions:
+        # Partitioned DML transactions are used to execute DML statements with a
+        # different execution strategy that provides different, and often better,
+        # scalability properties for large, table-wide operations than DML in a
+        # ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,
+        # should prefer using ReadWrite transactions. Partitioned DML partitions the
+        # keyspace and runs the DML statement on each partition in separate, internal
+        # transactions. These transactions commit automatically when complete, and run
+        # independently from one another. To reduce lock contention, this execution
+        # strategy only acquires read locks on rows that match the WHERE clause of the
+        # statement. Additionally, the smaller per-partition transactions hold locks for
+        # less time. That said, Partitioned DML is not a drop-in replacement for
+        # standard DML used in ReadWrite transactions. - The DML statement must be fully-
+        # partitionable. Specifically, the statement must be expressible as the union of
+        # many statements which each access only a single row of the table. - The
+        # statement is not applied atomically to all rows of the table. Rather, the
+        # statement is applied atomically to partitions of the table, in independent
+        # transactions. Secondary index rows are updated atomically with the base table
+        # rows. - Partitioned DML does not guarantee exactly-once execution semantics
+        # against a partition. The statement will be applied at least once to each
+        # partition. It is strongly recommended that the DML statement should be
+        # idempotent to avoid unexpected results. For instance, it is potentially
+        # dangerous to run a statement such as `UPDATE table SET column = column + 1` as
+        # it could be run multiple times against some rows. - The partitions are
+        # committed automatically - there is no support for Commit or Rollback. If the
+        # call returns an error, or if the client issuing the ExecuteSql call dies, it
+        # is possible that some rows had the statement executed on them successfully. It
+        # is also possible that statement was never executed against other rows. -
+        # Partitioned DML transactions may only contain the execution of a single DML
+        # statement via ExecuteSql or ExecuteStreamingSql. - If any error is encountered
+        # during the execution of the partitioned DML operation (for instance, a UNIQUE
+        # INDEX violation, division by zero, or a value that cannot be stored due to
+        # schema constraints), then the operation is stopped at that point and an error
+        # is returned. It is possible that at this point, some partitions have been
         # committed (or even committed multiple times), and other partitions have not
         # been run at all. Given the above, Partitioned DML is good fit for large,
         # database-wide, operations that are idempotent, such as deleting old rows from
@@ -1221,6 +981,28 @@ module Google
         end
       end
       
+      # A Cloud Spanner database role.
+      class DatabaseRole
+        include Google::Apis::Core::Hashable
+      
+        # Required. The name of the database role. Values are of the form `projects//
+        # instances//databases//databaseRoles/ `role``, where `` is as specified in the `
+        # CREATE ROLE` DDL statement. This name can be passed to Get/Set IAMPolicy
+        # methods to identify the database role.
+        # Corresponds to the JSON property `name`
+        # @return [String]
+        attr_accessor :name
+      
+        def initialize(**args)
+           update!(**args)
+        end
+      
+        # Update properties of this object
+        def update!(**args)
+          @name = args[:name] if args.key?(:name)
+        end
+      end
+      
       # Arguments to delete operations.
       class Delete
         include Google::Apis::Core::Hashable
@@ -2235,6 +2017,32 @@ module Google
         end
       end
       
+      # The response for ListDatabaseRoles.
+      class ListDatabaseRolesResponse
+        include Google::Apis::Core::Hashable
+      
+        # Database roles that matched the request.
+        # Corresponds to the JSON property `databaseRoles`
+        # @return [Array<Google::Apis::SpannerV1::DatabaseRole>]
+        attr_accessor :database_roles
+      
+        # `next_page_token` can be sent in a subsequent ListDatabaseRoles call to fetch
+        # more of the matching roles.
+        # Corresponds to the JSON property `nextPageToken`
+        # @return [String]
+        attr_accessor :next_page_token
+      
+        def initialize(**args)
+           update!(**args)
+        end
+      
+        # Update properties of this object
+        def update!(**args)
+          @database_roles = args[:database_roles] if args.key?(:database_roles)
+          @next_page_token = args[:next_page_token] if args.key?(:next_page_token)
+        end
+      end
+      
       # The response for ListDatabases.
       class ListDatabasesResponse
         include Google::Apis::Core::Hashable
@@ -3921,6 +3729,11 @@ module Google
         # @return [String]
         attr_accessor :create_time
       
+        # The database role which created this session.
+        # Corresponds to the JSON property `creatorRole`
+        # @return [String]
+        attr_accessor :creator_role
+      
         # The labels for the session. * Label keys must be between 1 and 63 characters
         # long and must conform to the following regular expression: `[a-z]([-a-z0-9]*[a-
         # z0-9])?`. * Label values must be between 0 and 63 characters long and must
@@ -3944,6 +3757,7 @@ module Google
         def update!(**args)
           @approximate_last_use_time = args[:approximate_last_use_time] if args.key?(:approximate_last_use_time)
           @create_time = args[:create_time] if args.key?(:create_time)
+          @creator_role = args[:creator_role] if args.key?(:creator_role)
           @labels = args[:labels] if args.key?(:labels)
           @name = args[:name] if args.key?(:name)
         end
@@ -4196,165 +4010,45 @@ module Google
         end
       end
       
-      # Transactions: Each session can have at most one active transaction at a time (
-      # note that standalone reads and queries use a transaction internally and do
-      # count towards the one transaction limit). After the active transaction is
-      # completed, the session can immediately be re-used for the next transaction. It
-      # is not necessary to create a new session for each transaction. Transaction
-      # modes: Cloud Spanner supports three transaction modes: 1. Locking read-write.
-      # This type of transaction is the only way to write data into Cloud Spanner.
-      # These transactions rely on pessimistic locking and, if necessary, two-phase
-      # commit. Locking read-write transactions may abort, requiring the application
-      # to retry. 2. Snapshot read-only. This transaction type provides guaranteed
-      # consistency across several reads, but does not allow writes. Snapshot read-
-      # only transactions can be configured to read at timestamps in the past.
-      # Snapshot read-only transactions do not need to be committed. 3. Partitioned
-      # DML. This type of transaction is used to execute a single Partitioned DML
-      # statement. Partitioned DML partitions the key space and runs the DML statement
-      # over each partition in parallel using separate, internal transactions that
-      # commit independently. Partitioned DML transactions do not need to be committed.
-      # For transactions that only read, snapshot read-only transactions provide
-      # simpler semantics and are almost always faster. In particular, read-only
-      # transactions do not take locks, so they do not conflict with read-write
-      # transactions. As a consequence of not taking locks, they also do not abort, so
-      # retry loops are not needed. Transactions may only read-write data in a single
-      # database. They may, however, read-write data in different tables within that
-      # database. Locking read-write transactions: Locking transactions may be used to
-      # atomically read-modify-write data anywhere in a database. This type of
-      # transaction is externally consistent. Clients should attempt to minimize the
-      # amount of time a transaction is active. Faster transactions commit with higher
-      # probability and cause less contention. Cloud Spanner attempts to keep read
-      # locks active as long as the transaction continues to do reads, and the
-      # transaction has not been terminated by Commit or Rollback. Long periods of
-      # inactivity at the client may cause Cloud Spanner to release a transaction's
-      # locks and abort it. Conceptually, a read-write transaction consists of zero or
-      # more reads or SQL statements followed by Commit. At any time before Commit,
-      # the client can send a Rollback request to abort the transaction. Semantics:
-      # Cloud Spanner can commit the transaction if all read locks it acquired are
-      # still valid at commit time, and it is able to acquire write locks for all
-      # writes. Cloud Spanner can abort the transaction for any reason. If a commit
-      # attempt returns `ABORTED`, Cloud Spanner guarantees that the transaction has
-      # not modified any user data in Cloud Spanner. Unless the transaction commits,
-      # Cloud Spanner makes no guarantees about how long the transaction's locks were
-      # held for. It is an error to use Cloud Spanner locks for any sort of mutual
-      # exclusion other than between Cloud Spanner transactions themselves. Retrying
-      # aborted transactions: When a transaction aborts, the application can choose to
-      # retry the whole transaction again. To maximize the chances of successfully
-      # committing the retry, the client should execute the retry in the same session
-      # as the original attempt. The original session's lock priority increases with
-      # each consecutive abort, meaning that each attempt has a slightly better chance
-      # of success than the previous. Under some circumstances (for example, many
-      # transactions attempting to modify the same row(s)), a transaction can abort
-      # many times in a short period before successfully committing. Thus, it is not a
-      # good idea to cap the number of retries a transaction can attempt; instead, it
-      # is better to limit the total amount of time spent retrying. Idle transactions:
-      # A transaction is considered idle if it has no outstanding reads or SQL queries
-      # and has not started a read or SQL query within the last 10 seconds. Idle
-      # transactions can be aborted by Cloud Spanner so that they don't hold on to
-      # locks indefinitely. If an idle transaction is aborted, the commit will fail
-      # with error `ABORTED`. If this behavior is undesirable, periodically executing
-      # a simple SQL query in the transaction (for example, `SELECT 1`) prevents the
-      # transaction from becoming idle. Snapshot read-only transactions: Snapshot read-
-      # only transactions provides a simpler method than locking read-write
-      # transactions for doing several consistent reads. However, this type of
-      # transaction does not support writes. Snapshot transactions do not take locks.
-      # Instead, they work by choosing a Cloud Spanner timestamp, then executing all
-      # reads at that timestamp. Since they do not acquire locks, they do not block
-      # concurrent read-write transactions. Unlike locking read-write transactions,
-      # snapshot read-only transactions never abort. They can fail if the chosen read
-      # timestamp is garbage collected; however, the default garbage collection policy
-      # is generous enough that most applications do not need to worry about this in
-      # practice. Snapshot read-only transactions do not need to call Commit or
-      # Rollback (and in fact are not permitted to do so). To execute a snapshot
-      # transaction, the client specifies a timestamp bound, which tells Cloud Spanner
-      # how to choose a read timestamp. The types of timestamp bound are: - Strong (
-      # the default). - Bounded staleness. - Exact staleness. If the Cloud Spanner
-      # database to be read is geographically distributed, stale read-only
-      # transactions can execute more quickly than strong or read-write transactions,
-      # because they are able to execute far from the leader replica. Each type of
-      # timestamp bound is discussed in detail below. Strong: Strong reads are
-      # guaranteed to see the effects of all transactions that have committed before
-      # the start of the read. Furthermore, all rows yielded by a single read are
-      # consistent with each other -- if any part of the read observes a transaction,
-      # all parts of the read see the transaction. Strong reads are not repeatable:
-      # two consecutive strong read-only transactions might return inconsistent
-      # results if there are concurrent writes. If consistency across reads is
-      # required, the reads should be executed within a transaction or at an exact
-      # read timestamp. See TransactionOptions.ReadOnly.strong. Exact staleness: These
-      # timestamp bounds execute reads at a user-specified timestamp. Reads at a
-      # timestamp are guaranteed to see a consistent prefix of the global transaction
-      # history: they observe modifications done by all transactions with a commit
-      # timestamp less than or equal to the read timestamp, and observe none of the
-      # modifications done by transactions with a larger commit timestamp. They will
-      # block until all conflicting transactions that may be assigned commit
-      # timestamps <= the read timestamp have finished. The timestamp can either be
-      # expressed as an absolute Cloud Spanner commit timestamp or a staleness
-      # relative to the current time. These modes do not require a "negotiation phase"
-      # to pick a timestamp. As a result, they execute slightly faster than the
-      # equivalent boundedly stale concurrency modes. On the other hand, boundedly
-      # stale reads usually return fresher results. See TransactionOptions.ReadOnly.
-      # read_timestamp and TransactionOptions.ReadOnly.exact_staleness. Bounded
-      # staleness: Bounded staleness modes allow Cloud Spanner to pick the read
-      # timestamp, subject to a user-provided staleness bound. Cloud Spanner chooses
-      # the newest timestamp within the staleness bound that allows execution of the
-      # reads at the closest available replica without blocking. All rows yielded are
-      # consistent with each other -- if any part of the read observes a transaction,
-      # all parts of the read see the transaction. Boundedly stale reads are not
-      # repeatable: two stale reads, even if they use the same staleness bound, can
-      # execute at different timestamps and thus return inconsistent results.
-      # Boundedly stale reads execute in two phases: the first phase negotiates a
-      # timestamp among all replicas needed to serve the read. In the second phase,
-      # reads are executed at the negotiated timestamp. As a result of the two phase
-      # execution, bounded staleness reads are usually a little slower than comparable
-      # exact staleness reads. However, they are typically able to return fresher
-      # results, and are more likely to execute at the closest replica. Because the
-      # timestamp negotiation requires up-front knowledge of which rows will be read,
-      # it can only be used with single-use read-only transactions. See
-      # TransactionOptions.ReadOnly.max_staleness and TransactionOptions.ReadOnly.
-      # min_read_timestamp. Old read timestamps and garbage collection: Cloud Spanner
-      # continuously garbage collects deleted and overwritten data in the background
-      # to reclaim storage space. This process is known as "version GC". By default,
-      # version GC reclaims versions after they are one hour old. Because of this,
-      # Cloud Spanner cannot perform reads at read timestamps more than one hour in
-      # the past. This restriction also applies to in-progress reads and/or SQL
-      # queries whose timestamp become too old while executing. Reads and SQL queries
-      # with too-old read timestamps fail with the error `FAILED_PRECONDITION`. You
-      # can configure and extend the `VERSION_RETENTION_PERIOD` of a database up to a
-      # period as long as one week, which allows Cloud Spanner to perform reads up to
-      # one week in the past. Partitioned DML transactions: Partitioned DML
-      # transactions are used to execute DML statements with a different execution
-      # strategy that provides different, and often better, scalability properties for
-      # large, table-wide operations than DML in a ReadWrite transaction. Smaller
-      # scoped statements, such as an OLTP workload, should prefer using ReadWrite
-      # transactions. Partitioned DML partitions the keyspace and runs the DML
-      # statement on each partition in separate, internal transactions. These
-      # transactions commit automatically when complete, and run independently from
-      # one another. To reduce lock contention, this execution strategy only acquires
-      # read locks on rows that match the WHERE clause of the statement. Additionally,
-      # the smaller per-partition transactions hold locks for less time. That said,
-      # Partitioned DML is not a drop-in replacement for standard DML used in
-      # ReadWrite transactions. - The DML statement must be fully-partitionable.
-      # Specifically, the statement must be expressible as the union of many
-      # statements which each access only a single row of the table. - The statement
-      # is not applied atomically to all rows of the table. Rather, the statement is
-      # applied atomically to partitions of the table, in independent transactions.
-      # Secondary index rows are updated atomically with the base table rows. -
-      # Partitioned DML does not guarantee exactly-once execution semantics against a
-      # partition. The statement will be applied at least once to each partition. It
-      # is strongly recommended that the DML statement should be idempotent to avoid
-      # unexpected results. For instance, it is potentially dangerous to run a
-      # statement such as `UPDATE table SET column = column + 1` as it could be run
-      # multiple times against some rows. - The partitions are committed automatically
-      # - there is no support for Commit or Rollback. If the call returns an error, or
-      # if the client issuing the ExecuteSql call dies, it is possible that some rows
-      # had the statement executed on them successfully. It is also possible that
-      # statement was never executed against other rows. - Partitioned DML
-      # transactions may only contain the execution of a single DML statement via
-      # ExecuteSql or ExecuteStreamingSql. - If any error is encountered during the
-      # execution of the partitioned DML operation (for instance, a UNIQUE INDEX
-      # violation, division by zero, or a value that cannot be stored due to schema
-      # constraints), then the operation is stopped at that point and an error is
-      # returned. It is possible that at this point, some partitions have been
+      # In addition, if TransactionOptions.read_only.return_read_timestamp is set to
+      # true, a special value of 2^63 - 2 will be returned in the Transaction message
+      # that describes the transaction, instead of a valid read timestamp. This
+      # special value should be discarded and not used for any subsequent queries.
+      # Please see https://cloud.google.com/spanner/docs/change-streams for more
+      # details on how to query the change stream TVFs. Partitioned DML transactions:
+      # Partitioned DML transactions are used to execute DML statements with a
+      # different execution strategy that provides different, and often better,
+      # scalability properties for large, table-wide operations than DML in a
+      # ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,
+      # should prefer using ReadWrite transactions. Partitioned DML partitions the
+      # keyspace and runs the DML statement on each partition in separate, internal
+      # transactions. These transactions commit automatically when complete, and run
+      # independently from one another. To reduce lock contention, this execution
+      # strategy only acquires read locks on rows that match the WHERE clause of the
+      # statement. Additionally, the smaller per-partition transactions hold locks for
+      # less time. That said, Partitioned DML is not a drop-in replacement for
+      # standard DML used in ReadWrite transactions. - The DML statement must be fully-
+      # partitionable. Specifically, the statement must be expressible as the union of
+      # many statements which each access only a single row of the table. - The
+      # statement is not applied atomically to all rows of the table. Rather, the
+      # statement is applied atomically to partitions of the table, in independent
+      # transactions. Secondary index rows are updated atomically with the base table
+      # rows. - Partitioned DML does not guarantee exactly-once execution semantics
+      # against a partition. The statement will be applied at least once to each
+      # partition. It is strongly recommended that the DML statement should be
+      # idempotent to avoid unexpected results. For instance, it is potentially
+      # dangerous to run a statement such as `UPDATE table SET column = column + 1` as
+      # it could be run multiple times against some rows. - The partitions are
+      # committed automatically - there is no support for Commit or Rollback. If the
+      # call returns an error, or if the client issuing the ExecuteSql call dies, it
+      # is possible that some rows had the statement executed on them successfully. It
+      # is also possible that statement was never executed against other rows. -
+      # Partitioned DML transactions may only contain the execution of a single DML
+      # statement via ExecuteSql or ExecuteStreamingSql. - If any error is encountered
+      # during the execution of the partitioned DML operation (for instance, a UNIQUE
+      # INDEX violation, division by zero, or a value that cannot be stored due to
+      # schema constraints), then the operation is stopped at that point and an error
+      # is returned. It is possible that at this point, some partitions have been
       # committed (or even committed multiple times), and other partitions have not
       # been run at all. Given the above, Partitioned DML is good fit for large,
       # database-wide, operations that are idempotent, such as deleting old rows from
@@ -4395,165 +4089,45 @@ module Google
       class TransactionSelector
         include Google::Apis::Core::Hashable
       
-        # Transactions: Each session can have at most one active transaction at a time (
-        # note that standalone reads and queries use a transaction internally and do
-        # count towards the one transaction limit). After the active transaction is
-        # completed, the session can immediately be re-used for the next transaction. It
-        # is not necessary to create a new session for each transaction. Transaction
-        # modes: Cloud Spanner supports three transaction modes: 1. Locking read-write.
-        # This type of transaction is the only way to write data into Cloud Spanner.
-        # These transactions rely on pessimistic locking and, if necessary, two-phase
-        # commit. Locking read-write transactions may abort, requiring the application
-        # to retry. 2. Snapshot read-only. This transaction type provides guaranteed
-        # consistency across several reads, but does not allow writes. Snapshot read-
-        # only transactions can be configured to read at timestamps in the past.
-        # Snapshot read-only transactions do not need to be committed. 3. Partitioned
-        # DML. This type of transaction is used to execute a single Partitioned DML
-        # statement. Partitioned DML partitions the key space and runs the DML statement
-        # over each partition in parallel using separate, internal transactions that
-        # commit independently. Partitioned DML transactions do not need to be committed.
-        # For transactions that only read, snapshot read-only transactions provide
-        # simpler semantics and are almost always faster. In particular, read-only
-        # transactions do not take locks, so they do not conflict with read-write
-        # transactions. As a consequence of not taking locks, they also do not abort, so
-        # retry loops are not needed. Transactions may only read-write data in a single
-        # database. They may, however, read-write data in different tables within that
-        # database. Locking read-write transactions: Locking transactions may be used to
-        # atomically read-modify-write data anywhere in a database. This type of
-        # transaction is externally consistent. Clients should attempt to minimize the
-        # amount of time a transaction is active. Faster transactions commit with higher
-        # probability and cause less contention. Cloud Spanner attempts to keep read
-        # locks active as long as the transaction continues to do reads, and the
-        # transaction has not been terminated by Commit or Rollback. Long periods of
-        # inactivity at the client may cause Cloud Spanner to release a transaction's
-        # locks and abort it. Conceptually, a read-write transaction consists of zero or
-        # more reads or SQL statements followed by Commit. At any time before Commit,
-        # the client can send a Rollback request to abort the transaction. Semantics:
-        # Cloud Spanner can commit the transaction if all read locks it acquired are
-        # still valid at commit time, and it is able to acquire write locks for all
-        # writes. Cloud Spanner can abort the transaction for any reason. If a commit
-        # attempt returns `ABORTED`, Cloud Spanner guarantees that the transaction has
-        # not modified any user data in Cloud Spanner. Unless the transaction commits,
-        # Cloud Spanner makes no guarantees about how long the transaction's locks were
-        # held for. It is an error to use Cloud Spanner locks for any sort of mutual
-        # exclusion other than between Cloud Spanner transactions themselves. Retrying
-        # aborted transactions: When a transaction aborts, the application can choose to
-        # retry the whole transaction again. To maximize the chances of successfully
-        # committing the retry, the client should execute the retry in the same session
-        # as the original attempt. The original session's lock priority increases with
-        # each consecutive abort, meaning that each attempt has a slightly better chance
-        # of success than the previous. Under some circumstances (for example, many
-        # transactions attempting to modify the same row(s)), a transaction can abort
-        # many times in a short period before successfully committing. Thus, it is not a
-        # good idea to cap the number of retries a transaction can attempt; instead, it
-        # is better to limit the total amount of time spent retrying. Idle transactions:
-        # A transaction is considered idle if it has no outstanding reads or SQL queries
-        # and has not started a read or SQL query within the last 10 seconds. Idle
-        # transactions can be aborted by Cloud Spanner so that they don't hold on to
-        # locks indefinitely. If an idle transaction is aborted, the commit will fail
-        # with error `ABORTED`. If this behavior is undesirable, periodically executing
-        # a simple SQL query in the transaction (for example, `SELECT 1`) prevents the
-        # transaction from becoming idle. Snapshot read-only transactions: Snapshot read-
-        # only transactions provides a simpler method than locking read-write
-        # transactions for doing several consistent reads. However, this type of
-        # transaction does not support writes. Snapshot transactions do not take locks.
-        # Instead, they work by choosing a Cloud Spanner timestamp, then executing all
-        # reads at that timestamp. Since they do not acquire locks, they do not block
-        # concurrent read-write transactions. Unlike locking read-write transactions,
-        # snapshot read-only transactions never abort. They can fail if the chosen read
-        # timestamp is garbage collected; however, the default garbage collection policy
-        # is generous enough that most applications do not need to worry about this in
-        # practice. Snapshot read-only transactions do not need to call Commit or
-        # Rollback (and in fact are not permitted to do so). To execute a snapshot
-        # transaction, the client specifies a timestamp bound, which tells Cloud Spanner
-        # how to choose a read timestamp. The types of timestamp bound are: - Strong (
-        # the default). - Bounded staleness. - Exact staleness. If the Cloud Spanner
-        # database to be read is geographically distributed, stale read-only
-        # transactions can execute more quickly than strong or read-write transactions,
-        # because they are able to execute far from the leader replica. Each type of
-        # timestamp bound is discussed in detail below. Strong: Strong reads are
-        # guaranteed to see the effects of all transactions that have committed before
-        # the start of the read. Furthermore, all rows yielded by a single read are
-        # consistent with each other -- if any part of the read observes a transaction,
-        # all parts of the read see the transaction. Strong reads are not repeatable:
-        # two consecutive strong read-only transactions might return inconsistent
-        # results if there are concurrent writes. If consistency across reads is
-        # required, the reads should be executed within a transaction or at an exact
-        # read timestamp. See TransactionOptions.ReadOnly.strong. Exact staleness: These
-        # timestamp bounds execute reads at a user-specified timestamp. Reads at a
-        # timestamp are guaranteed to see a consistent prefix of the global transaction
-        # history: they observe modifications done by all transactions with a commit
-        # timestamp less than or equal to the read timestamp, and observe none of the
-        # modifications done by transactions with a larger commit timestamp. They will
-        # block until all conflicting transactions that may be assigned commit
-        # timestamps <= the read timestamp have finished. The timestamp can either be
-        # expressed as an absolute Cloud Spanner commit timestamp or a staleness
-        # relative to the current time. These modes do not require a "negotiation phase"
-        # to pick a timestamp. As a result, they execute slightly faster than the
-        # equivalent boundedly stale concurrency modes. On the other hand, boundedly
-        # stale reads usually return fresher results. See TransactionOptions.ReadOnly.
-        # read_timestamp and TransactionOptions.ReadOnly.exact_staleness. Bounded
-        # staleness: Bounded staleness modes allow Cloud Spanner to pick the read
-        # timestamp, subject to a user-provided staleness bound. Cloud Spanner chooses
-        # the newest timestamp within the staleness bound that allows execution of the
-        # reads at the closest available replica without blocking. All rows yielded are
-        # consistent with each other -- if any part of the read observes a transaction,
-        # all parts of the read see the transaction. Boundedly stale reads are not
-        # repeatable: two stale reads, even if they use the same staleness bound, can
-        # execute at different timestamps and thus return inconsistent results.
-        # Boundedly stale reads execute in two phases: the first phase negotiates a
-        # timestamp among all replicas needed to serve the read. In the second phase,
-        # reads are executed at the negotiated timestamp. As a result of the two phase
-        # execution, bounded staleness reads are usually a little slower than comparable
-        # exact staleness reads. However, they are typically able to return fresher
-        # results, and are more likely to execute at the closest replica. Because the
-        # timestamp negotiation requires up-front knowledge of which rows will be read,
-        # it can only be used with single-use read-only transactions. See
-        # TransactionOptions.ReadOnly.max_staleness and TransactionOptions.ReadOnly.
-        # min_read_timestamp. Old read timestamps and garbage collection: Cloud Spanner
-        # continuously garbage collects deleted and overwritten data in the background
-        # to reclaim storage space. This process is known as "version GC". By default,
-        # version GC reclaims versions after they are one hour old. Because of this,
-        # Cloud Spanner cannot perform reads at read timestamps more than one hour in
-        # the past. This restriction also applies to in-progress reads and/or SQL
-        # queries whose timestamp become too old while executing. Reads and SQL queries
-        # with too-old read timestamps fail with the error `FAILED_PRECONDITION`. You
-        # can configure and extend the `VERSION_RETENTION_PERIOD` of a database up to a
-        # period as long as one week, which allows Cloud Spanner to perform reads up to
-        # one week in the past. Partitioned DML transactions: Partitioned DML
-        # transactions are used to execute DML statements with a different execution
-        # strategy that provides different, and often better, scalability properties for
-        # large, table-wide operations than DML in a ReadWrite transaction. Smaller
-        # scoped statements, such as an OLTP workload, should prefer using ReadWrite
-        # transactions. Partitioned DML partitions the keyspace and runs the DML
-        # statement on each partition in separate, internal transactions. These
-        # transactions commit automatically when complete, and run independently from
-        # one another. To reduce lock contention, this execution strategy only acquires
-        # read locks on rows that match the WHERE clause of the statement. Additionally,
-        # the smaller per-partition transactions hold locks for less time. That said,
-        # Partitioned DML is not a drop-in replacement for standard DML used in
-        # ReadWrite transactions. - The DML statement must be fully-partitionable.
-        # Specifically, the statement must be expressible as the union of many
-        # statements which each access only a single row of the table. - The statement
-        # is not applied atomically to all rows of the table. Rather, the statement is
-        # applied atomically to partitions of the table, in independent transactions.
-        # Secondary index rows are updated atomically with the base table rows. -
-        # Partitioned DML does not guarantee exactly-once execution semantics against a
-        # partition. The statement will be applied at least once to each partition. It
-        # is strongly recommended that the DML statement should be idempotent to avoid
-        # unexpected results. For instance, it is potentially dangerous to run a
-        # statement such as `UPDATE table SET column = column + 1` as it could be run
-        # multiple times against some rows. - The partitions are committed automatically
-        # - there is no support for Commit or Rollback. If the call returns an error, or
-        # if the client issuing the ExecuteSql call dies, it is possible that some rows
-        # had the statement executed on them successfully. It is also possible that
-        # statement was never executed against other rows. - Partitioned DML
-        # transactions may only contain the execution of a single DML statement via
-        # ExecuteSql or ExecuteStreamingSql. - If any error is encountered during the
-        # execution of the partitioned DML operation (for instance, a UNIQUE INDEX
-        # violation, division by zero, or a value that cannot be stored due to schema
-        # constraints), then the operation is stopped at that point and an error is
-        # returned. It is possible that at this point, some partitions have been
+        # In addition, if TransactionOptions.read_only.return_read_timestamp is set to
+        # true, a special value of 2^63 - 2 will be returned in the Transaction message
+        # that describes the transaction, instead of a valid read timestamp. This
+        # special value should be discarded and not used for any subsequent queries.
+        # Please see https://cloud.google.com/spanner/docs/change-streams for more
+        # details on how to query the change stream TVFs. Partitioned DML transactions:
+        # Partitioned DML transactions are used to execute DML statements with a
+        # different execution strategy that provides different, and often better,
+        # scalability properties for large, table-wide operations than DML in a
+        # ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,
+        # should prefer using ReadWrite transactions. Partitioned DML partitions the
+        # keyspace and runs the DML statement on each partition in separate, internal
+        # transactions. These transactions commit automatically when complete, and run
+        # independently from one another. To reduce lock contention, this execution
+        # strategy only acquires read locks on rows that match the WHERE clause of the
+        # statement. Additionally, the smaller per-partition transactions hold locks for
+        # less time. That said, Partitioned DML is not a drop-in replacement for
+        # standard DML used in ReadWrite transactions. - The DML statement must be fully-
+        # partitionable. Specifically, the statement must be expressible as the union of
+        # many statements which each access only a single row of the table. - The
+        # statement is not applied atomically to all rows of the table. Rather, the
+        # statement is applied atomically to partitions of the table, in independent
+        # transactions. Secondary index rows are updated atomically with the base table
+        # rows. - Partitioned DML does not guarantee exactly-once execution semantics
+        # against a partition. The statement will be applied at least once to each
+        # partition. It is strongly recommended that the DML statement should be
+        # idempotent to avoid unexpected results. For instance, it is potentially
+        # dangerous to run a statement such as `UPDATE table SET column = column + 1` as
+        # it could be run multiple times against some rows. - The partitions are
+        # committed automatically - there is no support for Commit or Rollback. If the
+        # call returns an error, or if the client issuing the ExecuteSql call dies, it
+        # is possible that some rows had the statement executed on them successfully. It
+        # is also possible that statement was never executed against other rows. -
+        # Partitioned DML transactions may only contain the execution of a single DML
+        # statement via ExecuteSql or ExecuteStreamingSql. - If any error is encountered
+        # during the execution of the partitioned DML operation (for instance, a UNIQUE
+        # INDEX violation, division by zero, or a value that cannot be stored due to
+        # schema constraints), then the operation is stopped at that point and an error
+        # is returned. It is possible that at this point, some partitions have been
         # committed (or even committed multiple times), and other partitions have not
         # been run at all. Given the above, Partitioned DML is good fit for large,
         # database-wide, operations that are idempotent, such as deleting old rows from
@@ -4568,165 +4142,45 @@ module Google
         # @return [String]
         attr_accessor :id
       
-        # Transactions: Each session can have at most one active transaction at a time (
-        # note that standalone reads and queries use a transaction internally and do
-        # count towards the one transaction limit). After the active transaction is
-        # completed, the session can immediately be re-used for the next transaction. It
-        # is not necessary to create a new session for each transaction. Transaction
-        # modes: Cloud Spanner supports three transaction modes: 1. Locking read-write.
-        # This type of transaction is the only way to write data into Cloud Spanner.
-        # These transactions rely on pessimistic locking and, if necessary, two-phase
-        # commit. Locking read-write transactions may abort, requiring the application
-        # to retry. 2. Snapshot read-only. This transaction type provides guaranteed
-        # consistency across several reads, but does not allow writes. Snapshot read-
-        # only transactions can be configured to read at timestamps in the past.
-        # Snapshot read-only transactions do not need to be committed. 3. Partitioned
-        # DML. This type of transaction is used to execute a single Partitioned DML
-        # statement. Partitioned DML partitions the key space and runs the DML statement
-        # over each partition in parallel using separate, internal transactions that
-        # commit independently. Partitioned DML transactions do not need to be committed.
-        # For transactions that only read, snapshot read-only transactions provide
-        # simpler semantics and are almost always faster. In particular, read-only
-        # transactions do not take locks, so they do not conflict with read-write
-        # transactions. As a consequence of not taking locks, they also do not abort, so
-        # retry loops are not needed. Transactions may only read-write data in a single
-        # database. They may, however, read-write data in different tables within that
-        # database. Locking read-write transactions: Locking transactions may be used to
-        # atomically read-modify-write data anywhere in a database. This type of
-        # transaction is externally consistent. Clients should attempt to minimize the
-        # amount of time a transaction is active. Faster transactions commit with higher
-        # probability and cause less contention. Cloud Spanner attempts to keep read
-        # locks active as long as the transaction continues to do reads, and the
-        # transaction has not been terminated by Commit or Rollback. Long periods of
-        # inactivity at the client may cause Cloud Spanner to release a transaction's
-        # locks and abort it. Conceptually, a read-write transaction consists of zero or
-        # more reads or SQL statements followed by Commit. At any time before Commit,
-        # the client can send a Rollback request to abort the transaction. Semantics:
-        # Cloud Spanner can commit the transaction if all read locks it acquired are
-        # still valid at commit time, and it is able to acquire write locks for all
-        # writes. Cloud Spanner can abort the transaction for any reason. If a commit
-        # attempt returns `ABORTED`, Cloud Spanner guarantees that the transaction has
-        # not modified any user data in Cloud Spanner. Unless the transaction commits,
-        # Cloud Spanner makes no guarantees about how long the transaction's locks were
-        # held for. It is an error to use Cloud Spanner locks for any sort of mutual
-        # exclusion other than between Cloud Spanner transactions themselves. Retrying
-        # aborted transactions: When a transaction aborts, the application can choose to
-        # retry the whole transaction again. To maximize the chances of successfully
-        # committing the retry, the client should execute the retry in the same session
-        # as the original attempt. The original session's lock priority increases with
-        # each consecutive abort, meaning that each attempt has a slightly better chance
-        # of success than the previous. Under some circumstances (for example, many
-        # transactions attempting to modify the same row(s)), a transaction can abort
-        # many times in a short period before successfully committing. Thus, it is not a
-        # good idea to cap the number of retries a transaction can attempt; instead, it
-        # is better to limit the total amount of time spent retrying. Idle transactions:
-        # A transaction is considered idle if it has no outstanding reads or SQL queries
-        # and has not started a read or SQL query within the last 10 seconds. Idle
-        # transactions can be aborted by Cloud Spanner so that they don't hold on to
-        # locks indefinitely. If an idle transaction is aborted, the commit will fail
-        # with error `ABORTED`. If this behavior is undesirable, periodically executing
-        # a simple SQL query in the transaction (for example, `SELECT 1`) prevents the
-        # transaction from becoming idle. Snapshot read-only transactions: Snapshot read-
-        # only transactions provides a simpler method than locking read-write
-        # transactions for doing several consistent reads. However, this type of
-        # transaction does not support writes. Snapshot transactions do not take locks.
-        # Instead, they work by choosing a Cloud Spanner timestamp, then executing all
-        # reads at that timestamp. Since they do not acquire locks, they do not block
-        # concurrent read-write transactions. Unlike locking read-write transactions,
-        # snapshot read-only transactions never abort. They can fail if the chosen read
-        # timestamp is garbage collected; however, the default garbage collection policy
-        # is generous enough that most applications do not need to worry about this in
-        # practice. Snapshot read-only transactions do not need to call Commit or
-        # Rollback (and in fact are not permitted to do so). To execute a snapshot
-        # transaction, the client specifies a timestamp bound, which tells Cloud Spanner
-        # how to choose a read timestamp. The types of timestamp bound are: - Strong (
-        # the default). - Bounded staleness. - Exact staleness. If the Cloud Spanner
-        # database to be read is geographically distributed, stale read-only
-        # transactions can execute more quickly than strong or read-write transactions,
-        # because they are able to execute far from the leader replica. Each type of
-        # timestamp bound is discussed in detail below. Strong: Strong reads are
-        # guaranteed to see the effects of all transactions that have committed before
-        # the start of the read. Furthermore, all rows yielded by a single read are
-        # consistent with each other -- if any part of the read observes a transaction,
-        # all parts of the read see the transaction. Strong reads are not repeatable:
-        # two consecutive strong read-only transactions might return inconsistent
-        # results if there are concurrent writes. If consistency across reads is
-        # required, the reads should be executed within a transaction or at an exact
-        # read timestamp. See TransactionOptions.ReadOnly.strong. Exact staleness: These
-        # timestamp bounds execute reads at a user-specified timestamp. Reads at a
-        # timestamp are guaranteed to see a consistent prefix of the global transaction
-        # history: they observe modifications done by all transactions with a commit
-        # timestamp less than or equal to the read timestamp, and observe none of the
-        # modifications done by transactions with a larger commit timestamp. They will
-        # block until all conflicting transactions that may be assigned commit
-        # timestamps <= the read timestamp have finished. The timestamp can either be
-        # expressed as an absolute Cloud Spanner commit timestamp or a staleness
-        # relative to the current time. These modes do not require a "negotiation phase"
-        # to pick a timestamp. As a result, they execute slightly faster than the
-        # equivalent boundedly stale concurrency modes. On the other hand, boundedly
-        # stale reads usually return fresher results. See TransactionOptions.ReadOnly.
-        # read_timestamp and TransactionOptions.ReadOnly.exact_staleness. Bounded
-        # staleness: Bounded staleness modes allow Cloud Spanner to pick the read
-        # timestamp, subject to a user-provided staleness bound. Cloud Spanner chooses
-        # the newest timestamp within the staleness bound that allows execution of the
-        # reads at the closest available replica without blocking. All rows yielded are
-        # consistent with each other -- if any part of the read observes a transaction,
-        # all parts of the read see the transaction. Boundedly stale reads are not
-        # repeatable: two stale reads, even if they use the same staleness bound, can
-        # execute at different timestamps and thus return inconsistent results.
-        # Boundedly stale reads execute in two phases: the first phase negotiates a
-        # timestamp among all replicas needed to serve the read. In the second phase,
-        # reads are executed at the negotiated timestamp. As a result of the two phase
-        # execution, bounded staleness reads are usually a little slower than comparable
-        # exact staleness reads. However, they are typically able to return fresher
-        # results, and are more likely to execute at the closest replica. Because the
-        # timestamp negotiation requires up-front knowledge of which rows will be read,
-        # it can only be used with single-use read-only transactions. See
-        # TransactionOptions.ReadOnly.max_staleness and TransactionOptions.ReadOnly.
-        # min_read_timestamp. Old read timestamps and garbage collection: Cloud Spanner
-        # continuously garbage collects deleted and overwritten data in the background
-        # to reclaim storage space. This process is known as "version GC". By default,
-        # version GC reclaims versions after they are one hour old. Because of this,
-        # Cloud Spanner cannot perform reads at read timestamps more than one hour in
-        # the past. This restriction also applies to in-progress reads and/or SQL
-        # queries whose timestamp become too old while executing. Reads and SQL queries
-        # with too-old read timestamps fail with the error `FAILED_PRECONDITION`. You
-        # can configure and extend the `VERSION_RETENTION_PERIOD` of a database up to a
-        # period as long as one week, which allows Cloud Spanner to perform reads up to
-        # one week in the past. Partitioned DML transactions: Partitioned DML
-        # transactions are used to execute DML statements with a different execution
-        # strategy that provides different, and often better, scalability properties for
-        # large, table-wide operations than DML in a ReadWrite transaction. Smaller
-        # scoped statements, such as an OLTP workload, should prefer using ReadWrite
-        # transactions. Partitioned DML partitions the keyspace and runs the DML
-        # statement on each partition in separate, internal transactions. These
-        # transactions commit automatically when complete, and run independently from
-        # one another. To reduce lock contention, this execution strategy only acquires
-        # read locks on rows that match the WHERE clause of the statement. Additionally,
-        # the smaller per-partition transactions hold locks for less time. That said,
-        # Partitioned DML is not a drop-in replacement for standard DML used in
-        # ReadWrite transactions. - The DML statement must be fully-partitionable.
-        # Specifically, the statement must be expressible as the union of many
-        # statements which each access only a single row of the table. - The statement
-        # is not applied atomically to all rows of the table. Rather, the statement is
-        # applied atomically to partitions of the table, in independent transactions.
-        # Secondary index rows are updated atomically with the base table rows. -
-        # Partitioned DML does not guarantee exactly-once execution semantics against a
-        # partition. The statement will be applied at least once to each partition. It
-        # is strongly recommended that the DML statement should be idempotent to avoid
-        # unexpected results. For instance, it is potentially dangerous to run a
-        # statement such as `UPDATE table SET column = column + 1` as it could be run
-        # multiple times against some rows. - The partitions are committed automatically
-        # - there is no support for Commit or Rollback. If the call returns an error, or
-        # if the client issuing the ExecuteSql call dies, it is possible that some rows
-        # had the statement executed on them successfully. It is also possible that
-        # statement was never executed against other rows. - Partitioned DML
-        # transactions may only contain the execution of a single DML statement via
-        # ExecuteSql or ExecuteStreamingSql. - If any error is encountered during the
-        # execution of the partitioned DML operation (for instance, a UNIQUE INDEX
-        # violation, division by zero, or a value that cannot be stored due to schema
-        # constraints), then the operation is stopped at that point and an error is
-        # returned. It is possible that at this point, some partitions have been
+        # In addition, if TransactionOptions.read_only.return_read_timestamp is set to
+        # true, a special value of 2^63 - 2 will be returned in the Transaction message
+        # that describes the transaction, instead of a valid read timestamp. This
+        # special value should be discarded and not used for any subsequent queries.
+        # Please see https://cloud.google.com/spanner/docs/change-streams for more
+        # details on how to query the change stream TVFs. Partitioned DML transactions:
+        # Partitioned DML transactions are used to execute DML statements with a
+        # different execution strategy that provides different, and often better,
+        # scalability properties for large, table-wide operations than DML in a
+        # ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,
+        # should prefer using ReadWrite transactions. Partitioned DML partitions the
+        # keyspace and runs the DML statement on each partition in separate, internal
+        # transactions. These transactions commit automatically when complete, and run
+        # independently from one another. To reduce lock contention, this execution
+        # strategy only acquires read locks on rows that match the WHERE clause of the
+        # statement. Additionally, the smaller per-partition transactions hold locks for
+        # less time. That said, Partitioned DML is not a drop-in replacement for
+        # standard DML used in ReadWrite transactions. - The DML statement must be fully-
+        # partitionable. Specifically, the statement must be expressible as the union of
+        # many statements which each access only a single row of the table. - The
+        # statement is not applied atomically to all rows of the table. Rather, the
+        # statement is applied atomically to partitions of the table, in independent
+        # transactions. Secondary index rows are updated atomically with the base table
+        # rows. - Partitioned DML does not guarantee exactly-once execution semantics
+        # against a partition. The statement will be applied at least once to each
+        # partition. It is strongly recommended that the DML statement should be
+        # idempotent to avoid unexpected results. For instance, it is potentially
+        # dangerous to run a statement such as `UPDATE table SET column = column + 1` as
+        # it could be run multiple times against some rows. - The partitions are
+        # committed automatically - there is no support for Commit or Rollback. If the
+        # call returns an error, or if the client issuing the ExecuteSql call dies, it
+        # is possible that some rows had the statement executed on them successfully. It
+        # is also possible that statement was never executed against other rows. -
+        # Partitioned DML transactions may only contain the execution of a single DML
+        # statement via ExecuteSql or ExecuteStreamingSql. - If any error is encountered
+        # during the execution of the partitioned DML operation (for instance, a UNIQUE
+        # INDEX violation, division by zero, or a value that cannot be stored due to
+        # schema constraints), then the operation is stopped at that point and an error
+        # is returned. It is possible that at this point, some partitions have been
         # committed (or even committed multiple times), and other partitions have not
         # been run at all. Given the above, Partitioned DML is good fit for large,
         # database-wide, operations that are idempotent, such as deleting old rows from