google-cloud-spanner-v1 0.1.0

data/proto_docs/google/spanner/v1/transaction.rb

@@ -0,0 +1,457 @@
+# frozen_string_literal: true
+
+# Copyright 2020 Google LLC
+#
+# 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
+#
+#     https://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.
+
+# Auto-generated by gapic-generator-ruby. DO NOT EDIT!
+
+
+module Google
+  module Cloud
+    module Spanner
+      module V1
+        # # Transactions
+        #
+        #
+        # Each session can have at most one active transaction at a time. 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
+        # {::Google::Cloud::Spanner::V1::Spanner::Client#commit Commit} or
+        # {::Google::Cloud::Spanner::V1::Spanner::Client#rollback 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
+        # {::Google::Cloud::Spanner::V1::Spanner::Client#commit Commit}. At any time before
+        # {::Google::Cloud::Spanner::V1::Spanner::Client#commit Commit}, the client can send a
+        # {::Google::Cloud::Spanner::V1::Spanner::Client#rollback 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 (e.g., 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 wall 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. In that case, the commit will
+        # fail with error `ABORTED`.
+        #
+        # If this behavior is undesirable, periodically executing a simple
+        # SQL query in the transaction (e.g., `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
+        # {::Google::Cloud::Spanner::V1::Spanner::Client#commit Commit} or
+        # {::Google::Cloud::Spanner::V1::Spanner::Client#rollback 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 transaction, 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 {::Google::Cloud::Spanner::V1::TransactionOptions::ReadOnly#strong 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 <=
+        # 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 {::Google::Cloud::Spanner::V1::TransactionOptions::ReadOnly#read_timestamp TransactionOptions.ReadOnly.read_timestamp} and
+        # {::Google::Cloud::Spanner::V1::TransactionOptions::ReadOnly#exact_staleness 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 {::Google::Cloud::Spanner::V1::TransactionOptions::ReadOnly#max_staleness TransactionOptions.ReadOnly.max_staleness} and
+        # {::Google::Cloud::Spanner::V1::TransactionOptions::ReadOnly#min_read_timestamp 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`.
+        #
+        # ## 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 a very large
+        # table.
+        # @!attribute [rw] read_write
+        #   @return [::Google::Cloud::Spanner::V1::TransactionOptions::ReadWrite]
+        #     Transaction may write.
+        #
+        #     Authorization to begin a read-write transaction requires
+        #     `spanner.databases.beginOrRollbackReadWriteTransaction` permission
+        #     on the `session` resource.
+        # @!attribute [rw] partitioned_dml
+        #   @return [::Google::Cloud::Spanner::V1::TransactionOptions::PartitionedDml]
+        #     Partitioned DML transaction.
+        #
+        #     Authorization to begin a Partitioned DML transaction requires
+        #     `spanner.databases.beginPartitionedDmlTransaction` permission
+        #     on the `session` resource.
+        # @!attribute [rw] read_only
+        #   @return [::Google::Cloud::Spanner::V1::TransactionOptions::ReadOnly]
+        #     Transaction will not write.
+        #
+        #     Authorization to begin a read-only transaction requires
+        #     `spanner.databases.beginReadOnlyTransaction` permission
+        #     on the `session` resource.
+        class TransactionOptions
+          include ::Google::Protobuf::MessageExts
+          extend ::Google::Protobuf::MessageExts::ClassMethods
+
+          # Message type to initiate a read-write transaction. Currently this
+          # transaction type has no options.
+          class ReadWrite
+            include ::Google::Protobuf::MessageExts
+            extend ::Google::Protobuf::MessageExts::ClassMethods
+          end
+
+          # Message type to initiate a Partitioned DML transaction.
+          class PartitionedDml
+            include ::Google::Protobuf::MessageExts
+            extend ::Google::Protobuf::MessageExts::ClassMethods
+          end
+
+          # Message type to initiate a read-only transaction.
+          # @!attribute [rw] strong
+          #   @return [::Boolean]
+          #     Read at a timestamp where all previously committed transactions
+          #     are visible.
+          # @!attribute [rw] min_read_timestamp
+          #   @return [::Google::Protobuf::Timestamp]
+          #     Executes all reads at a timestamp >= `min_read_timestamp`.
+          #
+          #     This is useful for requesting fresher data than some previous
+          #     read, or data that is fresh enough to observe the effects of some
+          #     previously committed transaction whose timestamp is known.
+          #
+          #     Note that this option can only be used in single-use transactions.
+          #
+          #     A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+          #     Example: `"2014-10-02T15:01:23.045123456Z"`.
+          # @!attribute [rw] max_staleness
+          #   @return [::Google::Protobuf::Duration]
+          #     Read data at a timestamp >= `NOW - max_staleness`
+          #     seconds. Guarantees that all writes that have committed more
+          #     than the specified number of seconds ago are visible. Because
+          #     Cloud Spanner chooses the exact timestamp, this mode works even if
+          #     the client's local clock is substantially skewed from Cloud Spanner
+          #     commit timestamps.
+          #
+          #     Useful for reading the freshest data available at a nearby
+          #     replica, while bounding the possible staleness if the local
+          #     replica has fallen behind.
+          #
+          #     Note that this option can only be used in single-use
+          #     transactions.
+          # @!attribute [rw] read_timestamp
+          #   @return [::Google::Protobuf::Timestamp]
+          #     Executes all reads at the given timestamp. Unlike other modes,
+          #     reads at a specific timestamp are repeatable; the same read at
+          #     the same timestamp always returns the same data. If the
+          #     timestamp is in the future, the read will block until the
+          #     specified timestamp, modulo the read's deadline.
+          #
+          #     Useful for large scale consistent reads such as mapreduces, or
+          #     for coordinating many reads against a consistent snapshot of the
+          #     data.
+          #
+          #     A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+          #     Example: `"2014-10-02T15:01:23.045123456Z"`.
+          # @!attribute [rw] exact_staleness
+          #   @return [::Google::Protobuf::Duration]
+          #     Executes all reads at a timestamp that is `exact_staleness`
+          #     old. The timestamp is chosen soon after the read is started.
+          #
+          #     Guarantees that all writes that have committed more than the
+          #     specified number of seconds ago are visible. Because Cloud Spanner
+          #     chooses the exact timestamp, this mode works even if the client's
+          #     local clock is substantially skewed from Cloud Spanner commit
+          #     timestamps.
+          #
+          #     Useful for reading at nearby replicas without the distributed
+          #     timestamp negotiation overhead of `max_staleness`.
+          # @!attribute [rw] return_read_timestamp
+          #   @return [::Boolean]
+          #     If true, the Cloud Spanner-selected read timestamp is included in
+          #     the {::Google::Cloud::Spanner::V1::Transaction Transaction} message that describes the transaction.
+          class ReadOnly
+            include ::Google::Protobuf::MessageExts
+            extend ::Google::Protobuf::MessageExts::ClassMethods
+          end
+        end
+
+        # A transaction.
+        # @!attribute [rw] id
+        #   @return [::String]
+        #     `id` may be used to identify the transaction in subsequent
+        #     {::Google::Cloud::Spanner::V1::Spanner::Client#read Read},
+        #     {::Google::Cloud::Spanner::V1::Spanner::Client#execute_sql ExecuteSql},
+        #     {::Google::Cloud::Spanner::V1::Spanner::Client#commit Commit}, or
+        #     {::Google::Cloud::Spanner::V1::Spanner::Client#rollback Rollback} calls.
+        #
+        #     Single-use read-only transactions do not have IDs, because
+        #     single-use transactions do not support multiple requests.
+        # @!attribute [rw] read_timestamp
+        #   @return [::Google::Protobuf::Timestamp]
+        #     For snapshot read-only transactions, the read timestamp chosen
+        #     for the transaction. Not returned by default: see
+        #     {::Google::Cloud::Spanner::V1::TransactionOptions::ReadOnly#return_read_timestamp TransactionOptions.ReadOnly.return_read_timestamp}.
+        #
+        #     A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.
+        #     Example: `"2014-10-02T15:01:23.045123456Z"`.
+        class Transaction
+          include ::Google::Protobuf::MessageExts
+          extend ::Google::Protobuf::MessageExts::ClassMethods
+        end
+
+        # This message is used to select the transaction in which a
+        # {::Google::Cloud::Spanner::V1::Spanner::Client#read Read} or
+        # {::Google::Cloud::Spanner::V1::Spanner::Client#execute_sql ExecuteSql} call runs.
+        #
+        # See {::Google::Cloud::Spanner::V1::TransactionOptions TransactionOptions} for more information about transactions.
+        # @!attribute [rw] single_use
+        #   @return [::Google::Cloud::Spanner::V1::TransactionOptions]
+        #     Execute the read or SQL query in a temporary transaction.
+        #     This is the most efficient way to execute a transaction that
+        #     consists of a single SQL query.
+        # @!attribute [rw] id
+        #   @return [::String]
+        #     Execute the read or SQL query in a previously-started transaction.
+        # @!attribute [rw] begin
+        #   @return [::Google::Cloud::Spanner::V1::TransactionOptions]
+        #     Begin a new transaction and execute this read or SQL query in
+        #     it. The transaction ID of the new transaction is returned in
+        #     {::Google::Cloud::Spanner::V1::ResultSetMetadata#transaction ResultSetMetadata.transaction}, which is a {::Google::Cloud::Spanner::V1::Transaction Transaction}.
+        class TransactionSelector
+          include ::Google::Protobuf::MessageExts
+          extend ::Google::Protobuf::MessageExts::ClassMethods
+        end
+      end
+    end
+  end
+end