Transaktionen

Auf dieser Seite werden Transaktionen in Cloud Spanner erläutert. Außerdem enthält sie Beispielcode zum Ausführen von Transaktionen.

Hinweis zur PostgreSQL-Schnittstelle: Die Beispiele in diesem Thema beziehen sich auf Datenbanken mit GoogleSQL-Dialekten.

Einführung

Eine Transaktion in Spanner besteht aus einer Reihe von Lese- und Schreibvorgängen, die für Spalten, Zeilen und Tabellen in einer Datenbank zu einem einzigen logischen Zeitpunkt atomar ausgeführt werden.

Spanner unterstützt die folgenden Transaktionsmodi:

• Lese-/Schreibtransaktionen sperren. Diese Transaktionen beruhen auf einer pessimistischen Sperrung und gegebenenfalls einem zweiphasigen Commit. Sperrende Lese-Schreib-Transaktionen können abgebrochen werden. Die Anwendung muss es dann noch einmal versuchen.

• Schreibgeschützt. Dieser Transaktionstyp bietet garantierte Konsistenz über mehrere Lesevorgänge, unterstützt jedoch keine Schreibvorgänge. Standardmäßig werden schreibgeschützte Transaktionen mit einem vom System gewählten Zeitstempel ausgeführt, der externe Konsistenz garantiert. Sie können aber auch so konfiguriert werden, dass sie an einem Zeitstempel in der Vergangenheit gelesen werden. Schreibgeschützte Transaktionen müssen nicht mit Commit bestätigt werden und können nicht gesperrt werden. Außerdem werden schreibgeschützte Transaktionen möglicherweise erst ausgeführt, wenn laufende Schreibvorgänge abgeschlossen sind.

• Partitionierte DML Dieser Transaktionstyp führt eine DML-Anweisung (Data Manipulation Language) als partitionierte DML aus. Partitionierte DML ist für Bulk-Aktualisierungen und -Löschvorgänge vorgesehen, insbesondere für regelmäßiges Bereinigen und Backfilling. Wenn Sie für eine große Anzahl von Blind-Schreibvorgängen einen Commit durchführen müssen, aber keine atomare Transaktion benötigen, können Sie die Spanner-Tabellen im Bulk mit Batchschreib ändern. Weitere Informationen finden Sie unter Daten mit Batch-Schreibvorgängen ändern.

Auf dieser Seite werden die allgemeinen Attribute und die Semantik von Transaktionen in Spanner beschrieben. Außerdem werden die nicht schreibgeschützten, schreibgeschützten und partitionierten DML-Transaktionsschnittstellen in Spanner vorgestellt.

Hinweis: Da schreibgeschützte Transaktionen für jedes beliebige Replikat ausgeführt werden können, wird empfohlen, möglichst alle Lesetransaktionen als schreibgeschützte Transaktionen auszuführen. Verwenden Sie sperrende Lese-Schreib-Transaktionen nur in den im nächsten Abschnitt beschriebenen Szenarien.

Lese-Schreib-Transaktionen

In den folgenden Szenarien sollten Sie Lese-Schreib-Transaktionen sperren:

• Wenn Sie einen Schreibvorgang ausführen, der vom Ergebnis eines oder mehrerer Lesevorgänge abhängt, sollten Sie diesen Schreibvorgang und die Lesevorgänge in derselben Lese-Schreib-Transaktion ausführen.
  
  • Beispiel: Verdoppeln Sie den Kontostand von Bankkonto A. Das Lesen des Kontostands von A sollte in der gleichen Transaktion wie der Schreibvorgang erfolgen, um den Kontostand durch den verdoppelten Wert zu ersetzen.
  
  
• Wenn Sie einen oder mehrere Schreibvorgänge ausführen, an denen ein atomarer Commit erforderlich ist, sollten Sie diese Schreibvorgänge in derselben Lese-Schreib-Transaktion ausführen.
  • Beispiel: 200 € von Konto A auf Konto B überweisen Beide Schreibvorgänge (einer, um A um 200 $zu senken und einer, um B um 200 $zu erhöhen) und das Lesen der ursprünglichen Kontostände sollten in derselben Transaktion erfolgen.
  
  
• Wenn Sie einen oder mehrere Schreibvorgänge ausführen könnten, je nachdem, wie die Ergebnisse eines oder mehrerer Lesevorgänge ausfallen, sollten Sie diese Schreib- und Lesevorgänge in derselben Lese-Schreib-Transaktion ausführen, auch wenn die Schreibvorgänge letztendlich nicht ausgeführt werden.
  
  • Beispiel: Sie überweisen 200 $ vom Bankkonto A zu Bankkonto B, wenn der aktuelle Kontostand von A mehr als 500 $ beträgt. Ihre Transaktion sollte einen Lesevorgang des Kontostands von A und eine bedingte Anweisung enthalten, die die Schreibvorgänge enthält.

Im Folgenden wird ein Szenario beschrieben, in dem Sie keine sperrende Lese-Schreib-Transaktion verwenden sollten:

• Wenn Sie nur Lesevorgänge ausführen und Ihren Lesevorgang mithilfe einer einzelnen Lesemethode ausdrücken können, sollten Sie diese einzelne Lesemethode oder eine schreibgeschützte Transaktion verwenden. Einzelne Lesevorgänge können im Gegensatz zu Lese-Schreib-Transaktionen nicht gesperrt werden.

Attribute

Eine Lese-Schreib-Transaktion in Spanner führt eine Reihe von Lese- und Schreibvorgängen atomar zu einem einzelnen logischen Zeitpunkt aus. Darüber hinaus entspricht die durch den Zeitstempel angegebene Zeit, zu der Lese-Schreib-Transaktionen ausgeführt werden, der Ortszeit, wobei die Reihenfolge der Serialisierung der Reihenfolge der Zeitstempel entspricht.

Warum sollten Sie eine Lese-Schreib-Transaktion verwenden? Lese-/Schreibtransaktionen bieten die ACID-Attribute von relationalen Datenbanken. Tatsächlich bieten Lese-Schreib-Transaktionen von Spanner noch stärkere Garantien als herkömmliche ACID-Transaktionen, siehe Abschnitt Semantik unten.

Isolation

Im Folgenden finden Sie Isolationsattribute für nicht schreibgeschützte und schreibgeschützte Transaktionen.

Transaktionen, die Lese- und Schreibvorgänge ausführen

Hier sind die Isolationsattribute, die Sie erhalten, nachdem Sie eine Transaktion mit einer Reihe von Lese- (oder Abfragen) und Schreibvorgängen erfolgreich mit Commit gespeichert haben:

• Alle Lesevorgänge innerhalb der Transaktion haben Werte zurückgegeben, die einen konsistenten Snapshot widerspiegeln, der beim Commit-Zeitstempel der Transaktion erstellt wurde.
• Leere Zeilen oder Bereiche blieben so zum Zeitpunkt des Commits erhalten.
• Alle Schreibvorgänge innerhalb der Transaktion wurden zum Commit-Zeitstempel der Transaktion mit Commit durchgeführt.
• Schreibvorgänge waren für eine Transaktion erst sichtbar, nachdem der Commit der Transaktion durchgeführt wurde.

Bestimmte Spanner-Clienttreiber enthalten Logik für Transaktionswiederholungen, um vorübergehende Fehler zu maskieren. Dazu führen sie die Transaktion noch einmal aus und validieren die vom Client beobachteten Daten.

Der Effekt besteht darin, dass alle Lese- und Schreibvorgänge zu einem einzigen Zeitpunkt stattgefunden haben, sowohl aus der Perspektive der Transaktion selbst als auch aus der Perspektive anderer Leser und Autoren in der Spanner-Datenbank. Anders ausgedrückt: Die Lese- und Schreibvorgänge werden letztendlich zum selben Zeitpunkt ausgeführt (eine Illustration dazu finden Sie im Abschnitt Serialisierbarkeit und externe Konsistenz weiter unten).

Transaktionen, die nur Lesevorgänge ausführen

Die Garantien für eine Lese-Schreib-Transaktion, die nur Lesevorgänge ausführt, sind ähnlich: Alle Lesevorgänge innerhalb dieser Transaktion liefern Daten aus dem gleichen Zeitstempel, auch für Zeilen, die nicht vorhanden sind. Ein Unterschied besteht darin, dass es, wenn Sie Ihre Daten lesen und später einen Commit an der Lese-Schreib-Transaktion ausführen, keine Garantie gibt, dass die Daten innerhalb der Datenbank nach dem Lesen und vor dem Commit modifiziert wurden. Wenn Sie wissen möchten, ob die Daten seit dem letzten Lesevorgang geändert wurden, sollten Sie am besten noch einen Lesevorgang ausführen (entweder in einer Lese-Schreib-Transaktion oder mit einem starken Lesevorgang). Für mehr Effizienz sollten Sie außerdem eine schreibgeschützte Transaktion anstelle einer Lese-Schreib-Transaktion verwenden, wenn Sie bereits im Vorhinein wissen, dass Sie nur Lese- und keine Schreibvorgänge ausführen werden.

Atomarität, Konsistenz, Langlebigkeit

Zusätzlich zum Isolationsattribut bietet Spanner auch Atomarität (wenn für alle Schreibvorgänge im Transaktions-Commit ein Commit durchgeführt wird), Consistency (die Datenbank bleibt nach der Transaktion in einem konsistenten Zustand) und Langlebigkeit (für Daten mit Commits wird ein Commit durchgeführt).

Vorteile dieser Attribute

Aufgrund dieser Attribute können Sie sich als Anwendungsentwickler auf die Genauigkeit jeder einzelnen Transaktion konzentrieren, ohne sich um den Schutz der ausgeführten Transaktion vor anderen Transaktionen, die möglicherweise zur gleichen Zeit ausgeführt werden könnten, kümmern zu müssen.

Schnittstelle

Die Spanner-Clientbibliotheken bieten eine Schnittstelle zum Ausführen eines Arbeitsablaufs im Kontext einer Lese-Schreib-Transaktion mit Wiederholungsversuchen für Transaktionsabbrüche. Im Folgenden finden Sie einige Kontextinformationen, die diesen Punkt erklären: Eine Spanner-Transaktion muss möglicherweise mehrmals getestet werden, bevor sie übergeben wird. Wenn beispielsweise zwei Transaktionen versuchen, gleichzeitig in einer Weise an Daten zu arbeiten, die zu einem Deadlock führen kann, bricht Spanner eine der Transaktionen ab, damit die andere Transaktion vorankommen kann. In seltenen Fällen können vorübergehende Ereignisse in Spanner dazu führen, dass einige Transaktionen abgebrochen werden. Da Transaktionen atomar sind, hat eine abgebrochene Transaktion keine Auswirkung auf die Datenbank. Daher sollten Transaktionen so ausgeführt werden, dass sie so lange wiederholt werden, bis sie erfolgreich sind.

Wenn Sie eine Transaktion in einer Spanner-Clientbibliothek verwenden, definieren Sie den Text einer Transaktion (d.h. die Lese- und Schreibvorgänge, die für eine oder mehrere Tabellen in einer Datenbank ausgeführt werden sollen) in Form eines Funktionsobjekts. Intern führt die Spanner-Clientbibliothek die Funktion wiederholt aus, bis der Commit der Transaktion durchgeführt wird oder ein nicht wiederholbarer Fehler auftritt.

Beispiel

Beispiel: Sie haben auf der Seite "Schema und Datenmodell" der Tabelle Albums die Spalte MarketingBudget hinzugefügt:

CREATE TABLE Albums (
  SingerId        INT64 NOT NULL,
  AlbumId         INT64 NOT NULL,
  AlbumTitle      STRING(MAX),
  MarketingBudget INT64
) PRIMARY KEY (SingerId, AlbumId);

Ihre Marketing-Abteilung beschließt, eine Marketing-Offensive für das Album mit der Kennung Albums (1, 1) zu starten, und hat Sie gebeten, 200.000 $ aus dem Budget von Albums (2, 2) zu übertragen, wenn das Geld im Budget dieses Albums verfügbar ist. Sie sollten für diesen Vorgang eine sperrende Lese-Schreib-Transaktion verwenden, da die Transaktion je nach Ergebnis eines Lesevorgangs Schreibvorgänge ausführen könnte.

Das folgende Beispiel zeigt, wie Sie eine Lese-Schreib-Transaktion ausführen:

C++

Auf GitHub ansehen

void ReadWriteTransaction(google::cloud::spanner::Client client) {
  namespace spanner = ::google::cloud::spanner;
  using ::google::cloud::StatusOr;

  // A helper to read a single album MarketingBudget.
  auto get_current_budget =
      [](spanner::Client client, spanner::Transaction txn,
         std::int64_t singer_id,
         std::int64_t album_id) -> StatusOr<std::int64_t> {
    auto key = spanner::KeySet().AddKey(spanner::MakeKey(singer_id, album_id));
    auto rows = client.Read(std::move(txn), "Albums", std::move(key),
                            {"MarketingBudget"});
    using RowType = std::tuple<std::int64_t>;
    auto row = spanner::GetSingularRow(spanner::StreamOf<RowType>(rows));
    if (!row) return std::move(row).status();
    return std::get<0>(*std::move(row));
  };

  auto commit = client.Commit(
      [&client, &get_current_budget](
          spanner::Transaction const& txn) -> StatusOr<spanner::Mutations> {
        auto b1 = get_current_budget(client, txn, 1, 1);
        if (!b1) return std::move(b1).status();
        auto b2 = get_current_budget(client, txn, 2, 2);
        if (!b2) return std::move(b2).status();
        std::int64_t transfer_amount = 200000;

        return spanner::Mutations{
            spanner::UpdateMutationBuilder(
                "Albums", {"SingerId", "AlbumId", "MarketingBudget"})
                .EmplaceRow(1, 1, *b1 + transfer_amount)
                .EmplaceRow(2, 2, *b2 - transfer_amount)
                .Build()};
      });

  if (!commit) throw std::move(commit).status();
  std::cout << "Transfer was successful [spanner_read_write_transaction]\n";
}

C#

Auf GitHub ansehen

using Google.Cloud.Spanner.Data;
using System;
using System.Threading.Tasks;
using System.Transactions;

public class ReadWriteWithTransactionAsyncSample
{
    public async Task<int> ReadWriteWithTransactionAsync(string projectId, string instanceId, string databaseId)
    {
        // This sample transfers 200,000 from the MarketingBudget
        // field of the second Album to the first Album. Make sure to run
        // the Add Column and Write Data To New Column samples first,
        // in that order.

        string connectionString = $"Data Source=projects/{projectId}/instances/{instanceId}/databases/{databaseId}";

        using TransactionScope scope = new TransactionScope(TransactionScopeAsyncFlowOption.Enabled);
        decimal transferAmount = 200000;
        decimal secondBudget = 0;
        decimal firstBudget = 0;

        using var connection = new SpannerConnection(connectionString);
        using var cmdLookup1 = connection.CreateSelectCommand("SELECT * FROM Albums WHERE SingerId = 2 AND AlbumId = 2");

        using (var reader = await cmdLookup1.ExecuteReaderAsync())
        {
            while (await reader.ReadAsync())
            {
                // Read the second album's budget.
                secondBudget = reader.GetFieldValue<decimal>("MarketingBudget");
                // Confirm second Album's budget is sufficient and
                // if not raise an exception. Raising an exception
                // will automatically roll back the transaction.
                if (secondBudget < transferAmount)
                {
                    throw new Exception($"The second album's budget {secondBudget} is less than the amount to transfer.");
                }
            }
        }

        // Read the first album's budget.
        using var cmdLookup2 = connection.CreateSelectCommand("SELECT * FROM Albums WHERE SingerId = 1 and AlbumId = 1");
        using (var reader = await cmdLookup2.ExecuteReaderAsync())
        {
            while (await reader.ReadAsync())
            {
                firstBudget = reader.GetFieldValue<decimal>("MarketingBudget");
            }
        }

        // Specify update command parameters.
        using var cmdUpdate = connection.CreateUpdateCommand("Albums", new SpannerParameterCollection
        {
            { "SingerId", SpannerDbType.Int64 },
            { "AlbumId", SpannerDbType.Int64 },
            { "MarketingBudget", SpannerDbType.Int64 },
        });

        // Update second album to remove the transfer amount.
        secondBudget -= transferAmount;
        cmdUpdate.Parameters["SingerId"].Value = 2;
        cmdUpdate.Parameters["AlbumId"].Value = 2;
        cmdUpdate.Parameters["MarketingBudget"].Value = secondBudget;
        var rowCount = await cmdUpdate.ExecuteNonQueryAsync();

        // Update first album to add the transfer amount.
        firstBudget += transferAmount;
        cmdUpdate.Parameters["SingerId"].Value = 1;
        cmdUpdate.Parameters["AlbumId"].Value = 1;
        cmdUpdate.Parameters["MarketingBudget"].Value = firstBudget;
        rowCount += await cmdUpdate.ExecuteNonQueryAsync();
        scope.Complete();
        Console.WriteLine("Transaction complete.");
        return rowCount;
    }
}

Einfach loslegen (Go)

Auf GitHub ansehen

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/spanner"
)

func writeWithTransaction(w io.Writer, db string) error {
	ctx := context.Background()
	client, err := spanner.NewClient(ctx, db)
	if err != nil {
		return err
	}
	defer client.Close()

	_, err = client.ReadWriteTransaction(ctx, func(ctx context.Context, txn *spanner.ReadWriteTransaction) error {
		getBudget := func(key spanner.Key) (int64, error) {
			row, err := txn.ReadRow(ctx, "Albums", key, []string{"MarketingBudget"})
			if err != nil {
				return 0, err
			}
			var budget int64
			if err := row.Column(0, &budget); err != nil {
				return 0, err
			}
			return budget, nil
		}
		album2Budget, err := getBudget(spanner.Key{2, 2})
		if err != nil {
			return err
		}
		const transferAmt = 200000
		if album2Budget >= transferAmt {
			album1Budget, err := getBudget(spanner.Key{1, 1})
			if err != nil {
				return err
			}
			album1Budget += transferAmt
			album2Budget -= transferAmt
			cols := []string{"SingerId", "AlbumId", "MarketingBudget"}
			txn.BufferWrite([]*spanner.Mutation{
				spanner.Update("Albums", cols, []interface{}{1, 1, album1Budget}),
				spanner.Update("Albums", cols, []interface{}{2, 2, album2Budget}),
			})
			fmt.Fprintf(w, "Moved %d from Album2's MarketingBudget to Album1's.", transferAmt)
		}
		return nil
	})
	return err
}

Java

Auf GitHub ansehen

static void writeWithTransaction(DatabaseClient dbClient) {
  dbClient
      .readWriteTransaction()
      .run(transaction -> {
        // Transfer marketing budget from one album to another. We do it in a transaction to
        // ensure that the transfer is atomic.
        Struct row =
            transaction.readRow("Albums", Key.of(2, 2), Arrays.asList("MarketingBudget"));
        long album2Budget = row.getLong(0);
        // Transaction will only be committed if this condition still holds at the time of
        // commit. Otherwise it will be aborted and the callable will be rerun by the
        // client library.
        long transfer = 200000;
        if (album2Budget >= transfer) {
          long album1Budget =
              transaction
                  .readRow("Albums", Key.of(1, 1), Arrays.asList("MarketingBudget"))
                  .getLong(0);
          album1Budget += transfer;
          album2Budget -= transfer;
          transaction.buffer(
              Mutation.newUpdateBuilder("Albums")
                  .set("SingerId")
                  .to(1)
                  .set("AlbumId")
                  .to(1)
                  .set("MarketingBudget")
                  .to(album1Budget)
                  .build());
          transaction.buffer(
              Mutation.newUpdateBuilder("Albums")
                  .set("SingerId")
                  .to(2)
                  .set("AlbumId")
                  .to(2)
                  .set("MarketingBudget")
                  .to(album2Budget)
                  .build());
        }
        return null;
      });
}

Node.js

Auf GitHub ansehen

// This sample transfers 200,000 from the MarketingBudget field
// of the second Album to the first Album, as long as the second
// Album has enough money in its budget. Make sure to run the
// addColumn and updateData samples first (in that order).

// Imports the Google Cloud client library
const {Spanner} = require('@google-cloud/spanner');

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const projectId = 'my-project-id';
// const instanceId = 'my-instance';
// const databaseId = 'my-database';

// Creates a client
const spanner = new Spanner({
  projectId: projectId,
});

// Gets a reference to a Cloud Spanner instance and database
const instance = spanner.instance(instanceId);
const database = instance.database(databaseId);

const transferAmount = 200000;

database.runTransaction(async (err, transaction) => {
  if (err) {
    console.error(err);
    return;
  }
  let firstBudget, secondBudget;
  const queryOne = {
    columns: ['MarketingBudget'],
    keys: [[2, 2]], // SingerId: 2, AlbumId: 2
  };

  const queryTwo = {
    columns: ['MarketingBudget'],
    keys: [[1, 1]], // SingerId: 1, AlbumId: 1
  };

  Promise.all([
    // Reads the second album's budget
    transaction.read('Albums', queryOne).then(results => {
      // Gets second album's budget
      const rows = results[0].map(row => row.toJSON());
      secondBudget = rows[0].MarketingBudget;
      console.log(`The second album's marketing budget: ${secondBudget}`);

      // Makes sure the second album's budget is large enough
      if (secondBudget < transferAmount) {
        throw new Error(
          `The second album's budget (${secondBudget}) is less than the transfer amount (${transferAmount}).`
        );
      }
    }),

    // Reads the first album's budget
    transaction.read('Albums', queryTwo).then(results => {
      // Gets first album's budget
      const rows = results[0].map(row => row.toJSON());
      firstBudget = rows[0].MarketingBudget;
      console.log(`The first album's marketing budget: ${firstBudget}`);
    }),
  ])
    .then(() => {
      console.log(firstBudget, secondBudget);
      // Transfers the budgets between the albums
      firstBudget += transferAmount;
      secondBudget -= transferAmount;

      console.log(firstBudget, secondBudget);

      // Updates the database
      // Note: Cloud Spanner interprets Node.js numbers as FLOAT64s, so they
      // must be converted (back) to strings before being inserted as INT64s.
      transaction.update('Albums', [
        {
          SingerId: '1',
          AlbumId: '1',
          MarketingBudget: firstBudget.toString(),
        },
        {
          SingerId: '2',
          AlbumId: '2',
          MarketingBudget: secondBudget.toString(),
        },
      ]);
    })
    .then(() => {
      // Commits the transaction and send the changes to the database
      return transaction.commit();
    })
    .then(() => {
      console.log(
        `Successfully executed read-write transaction to transfer ${transferAmount} from Album 2 to Album 1.`
      );
    })
    .catch(err => {
      console.error('ERROR:', err);
    })
    .then(() => {
      transaction.end();
      // Closes the database when finished
      return database.close();
    });
});

PHP

Auf GitHub ansehen

use Google\Cloud\Spanner\SpannerClient;
use Google\Cloud\Spanner\Transaction;
use UnexpectedValueException;

/**
 * Performs a read-write transaction to update two sample records in the
 * database.
 *
 * This will transfer 200,000 from the `MarketingBudget` field for the second
 * Album to the first Album. If the `MarketingBudget` for the second Album is
 * too low, it will raise an exception.
 *
 * Before running this sample, you will need to run the `update_data` sample
 * to populate the fields.
 * Example:
 * ```
 * read_write_transaction($instanceId, $databaseId);
 * ```
 *
 * @param string $instanceId The Spanner instance ID.
 * @param string $databaseId The Spanner database ID.
 */
function read_write_transaction(string $instanceId, string $databaseId): void
{
    $spanner = new SpannerClient();
    $instance = $spanner->instance($instanceId);
    $database = $instance->database($databaseId);

    $database->runTransaction(function (Transaction $t) use ($spanner) {
        $transferAmount = 200000;

        // Read the second album's budget.
        $secondAlbumKey = [2, 2];
        $secondAlbumKeySet = $spanner->keySet(['keys' => [$secondAlbumKey]]);
        $secondAlbumResult = $t->read(
            'Albums',
            $secondAlbumKeySet,
            ['MarketingBudget'],
            ['limit' => 1]
        );

        $firstRow = $secondAlbumResult->rows()->current();
        $secondAlbumBudget = $firstRow['MarketingBudget'];
        if ($secondAlbumBudget < $transferAmount) {
            // Throwing an exception will automatically roll back the transaction.
            throw new UnexpectedValueException(
                'The second album\'s budget is lower than the transfer amount: ' . $transferAmount
            );
        }

        $firstAlbumKey = [1, 1];
        $firstAlbumKeySet = $spanner->keySet(['keys' => [$firstAlbumKey]]);
        $firstAlbumResult = $t->read(
            'Albums',
            $firstAlbumKeySet,
            ['MarketingBudget'],
            ['limit' => 1]
        );

        // Read the first album's budget.
        $firstRow = $firstAlbumResult->rows()->current();
        $firstAlbumBudget = $firstRow['MarketingBudget'];

        // Update the budgets.
        $secondAlbumBudget -= $transferAmount;
        $firstAlbumBudget += $transferAmount;
        printf('Setting first album\'s budget to %s and the second album\'s ' .
            'budget to %s.' . PHP_EOL, $firstAlbumBudget, $secondAlbumBudget);

        // Update the rows.
        $t->updateBatch('Albums', [
            ['SingerId' => 1, 'AlbumId' => 1, 'MarketingBudget' => $firstAlbumBudget],
            ['SingerId' => 2, 'AlbumId' => 2, 'MarketingBudget' => $secondAlbumBudget],
        ]);

        // Commit the transaction!
        $t->commit();

        print('Transaction complete.' . PHP_EOL);
    });
}

Python

Auf GitHub ansehen

def read_write_transaction(instance_id, database_id):
    """Performs a read-write transaction to update two sample records in the
    database.

    This will transfer 200,000 from the `MarketingBudget` field for the second
    Album to the first Album. If the `MarketingBudget` is too low, it will
    raise an exception.

    Before running this sample, you will need to run the `update_data` sample
    to populate the fields.
    """
    spanner_client = spanner.Client()
    instance = spanner_client.instance(instance_id)
    database = instance.database(database_id)

    def update_albums(transaction):
        # Read the second album budget.
        second_album_keyset = spanner.KeySet(keys=[(2, 2)])
        second_album_result = transaction.read(
            table="Albums",
            columns=("MarketingBudget",),
            keyset=second_album_keyset,
            limit=1,
        )
        second_album_row = list(second_album_result)[0]
        second_album_budget = second_album_row[0]

        transfer_amount = 200000

        if second_album_budget < transfer_amount:
            # Raising an exception will automatically roll back the
            # transaction.
            raise ValueError("The second album doesn't have enough funds to transfer")

        # Read the first album's budget.
        first_album_keyset = spanner.KeySet(keys=[(1, 1)])
        first_album_result = transaction.read(
            table="Albums",
            columns=("MarketingBudget",),
            keyset=first_album_keyset,
            limit=1,
        )
        first_album_row = list(first_album_result)[0]
        first_album_budget = first_album_row[0]

        # Update the budgets.
        second_album_budget -= transfer_amount
        first_album_budget += transfer_amount
        print(
            "Setting first album's budget to {} and the second album's "
            "budget to {}.".format(first_album_budget, second_album_budget)
        )

        # Update the rows.
        transaction.update(
            table="Albums",
            columns=("SingerId", "AlbumId", "MarketingBudget"),
            values=[(1, 1, first_album_budget), (2, 2, second_album_budget)],
        )

    database.run_in_transaction(update_albums)

    print("Transaction complete.")

Ruby

Auf GitHub ansehen

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"

spanner         = Google::Cloud::Spanner.new project: project_id
client          = spanner.client instance_id, database_id
transfer_amount = 200_000

client.transaction do |transaction|
  first_album  = transaction.read("Albums", [:MarketingBudget], keys: [[1, 1]]).rows.first
  second_album = transaction.read("Albums", [:MarketingBudget], keys: [[2, 2]]).rows.first

  raise "The second album does not have enough funds to transfer" if second_album[:MarketingBudget] < transfer_amount

  new_first_album_budget  = first_album[:MarketingBudget] + transfer_amount
  new_second_album_budget = second_album[:MarketingBudget] - transfer_amount

  transaction.update "Albums", [
    { SingerId: 1, AlbumId: 1, MarketingBudget: new_first_album_budget  },
    { SingerId: 2, AlbumId: 2, MarketingBudget: new_second_album_budget }
  ]
end

puts "Transaction complete"

Semantik

Serialisierbarkeit und externe Konsistenz

Spanner bietet Serialisierbarkeit. Das bedeutet, dass alle Transaktionen so aussehen, als wären sie in einer seriellen Reihenfolge ausgeführt worden, auch wenn einige der Lese-, Schreib- und anderen Vorgänge unterschiedlicher Transaktionen tatsächlich parallel ausgeführt wurden. Spanner weist zur Implementierung dieses Attributs Commit-Zeitstempel zu, die der Reihenfolge der übergebenen Transaktionen entsprechen. Tatsächlich bietet Spanner eine bessere Garantie als Serialisierbarkeit, nämlich externe Konsistenz: Transaktionen werden in einer Reihenfolge übernommen, die sich in ihren Commit-Zeitstempeln widerspiegelt. Diese Commit-Zeitstempel spiegeln Echtzeit wider, sodass Sie sie mit Ihrer Smartwatch vergleichen können. Lesevorgänge in einer Transaktion erkennen alles, was vor dem Commit der Transaktion übergeben wurde, und Schreibvorgänge werden von allem erkannt, was nach dem Commit der Transaktion gestartet wird.

Angenommen, zwei Transaktionen werden so wie im folgenden Diagramm ausgeführt:

Transaktion Txn1 in Blau liest einige der Daten A, puffert einen Schreibvorgang in A und wird erfolgreich übergeben. Transaktion Txn2 in Grün startet nach Txn1, liest einige der Daten B und liest dann die Daten A. Da Txn2 den Wert von A liest, nachdem Txn1 den Schreibvorgang an A übergeben hat, erkennt Txn2 die Auswirkung des Schreibvorgangs von Txn1 an A, obwohl Txn2 gestartet wurde, bevor Txn1 abgeschlossen war.

Auch wenn es zeitliche Überlappungen gibt, in denen Txn1 und Txn2 gleichzeitig ausgeführt werden, gilt für ihre Commit-Zeitstempel c1 und c2 eine lineare Transaktionsreihenfolge. Das heißt, dass alle Auswirkungen der Lese- und Schreibvorgänge von Txn1 scheinbar zu einem einzigen Zeitpunkt (c1) und alle Auswirkungen der Lese- und Schreibvorgänge von Txn2 scheinbar zu einem einzigen Zeitpunkt (c2) stattgefunden haben. Darüber hinaus gilt c1 < c2 (dadurch wird garantiert, dass Txn1 und Txn2 Schreibvorgänge übergeben haben; das gilt auch, wenn die Schreibvorgänge auf verschiedenen Geräten ausgeführt wurden), wobei die Reihenfolge Txn1 vor Txn2 berücksichtigt wird. (Wenn allerdings Txn2 nur Lesevorgänge in der Transaktion ausgeführt hat, gilt c1 <= c2.)

Lesevorgänge erkennen ein Präfix des Commit-Verlaufs. Wenn ein Lesevorgang die Auswirkung von Txn2 erkennt, erkennt er auch die Auswirkung von Txn1. Alle Transaktionen, die erfolgreich Commits ausführen, haben dieses Attribut.

Hinweis: Änderungen, die Sie mit DML-Anweisungen vornehmen, sind für nachfolgende Leseanweisungen in derselben Transaktion sichtbar. Dies unterscheidet sich von Mutationen, bei deren Verwendung Änderungen erst sichtbar werden, wenn der Commit der Transaktion durchgeführt wird. Dies liegt daran, dass Mutationen in einer Transaktion lokal zwischengespeichert und erst zum Commit-Zeitpunkt an den Server gesendet werden.

Lese- und Schreibgarantien

Wenn ein Aufruf zum Ausführen einer Transaktion fehlschlägt, hängen Ihre Lese- und Schreibgarantien davon ab, welcher Fehler beim zugrunde liegenden Commit-Aufruf für das Fehlschlagen verantwortlich war.

Zum Beispiel bedeutet das Auftreten eines Fehlers der Art "Zeile nicht gefunden" oder "Zeile existiert bereits", dass beim Schreiben der gepufferten Mutationen ein Fehler aufgetreten ist, z. B. dass eine Zeile, die der Client zu aktualisieren versucht, nicht vorhanden ist. In diesem Fall sind die Lesevorgänge garantiert konsistent, die Schreibvorgänge werden nicht angewendet und das Nicht-Vorhandensein einer Zeile ist ebenfalls mit den Lesevorgängen garantiert konsistent.

Hinweis: Spanner versucht möglicherweise, den Text der Transaktion mehrmals intern auszuführen. Wenn ein Ausführungsversuch fehlschlägt, zeigt der Fehler, den er zurückgibt, die aufgetretenen Bedingungen an und damit, welche Garantien Sie erhalten. Beachten Sie jedoch, dass Nebenwirkungen des Transaktionstexts (z. B. Änderungen am Nicht-Spanner-Status in Ihrem Programm oder anderen Systemen) mehrmals auftreten können, wenn Spanner die Transaktion mehrmals wiederholen muss.

Transaktionen abbrechen

Asynchrone Leseoperationen können jederzeit vom Nutzer abgebrochen werden (z. B., wenn eine Operation auf höherer Ebene abgebrochen wird oder Sie entscheiden, einen Lesevorgang basierend auf den ersten Ergebnissen zu stoppen, die vom Lesevorgang empfangen wurden), ohne andere existierende Operationen innerhalb der Transaktion zu beeinflussen.

Aber selbst wenn Sie versucht haben, den Lesevorgang abzubrechen, garantiert Spanner nicht, dass der Lesevorgang tatsächlich abgebrochen wird. Nachdem Sie den Abbruch eines Lesevorgangs angefordert haben, kann dieser Lesevorgang immer noch erfolgreich abgeschlossen werden oder aus einem anderen Grund fehlschlagen (z. B. Abbruch). Darüber hinaus kann der abgebrochene Lesevorgang noch einige Ergebnisse liefern. Diese möglicherweise unvollständigen Ergebnisse werden als Teil des Transaktions-Commits validiert.

Beachten Sie, dass im Gegensatz zu Lesevorgängen das Abbrechen eines Transaktion-Commit-Vorgangs zum Abbruch der Transaktion führt (es sei denn, die Transaktion wurde bereits übergeben oder ist aus einem anderen Grund fehlgeschlagen).

Leistung

Sperren

Spanner ermöglicht mehreren Clients die gleichzeitige Interaktion mit derselben Datenbank. Spanner verwendet eine Kombination aus gemeinsamen Sperren und exklusiven Sperren, um den Zugriff auf die Daten zu steuern, um die Konsistenz mehrerer gleichzeitiger Transaktionen zu gewährleisten. Wenn Sie einen Lesevorgang als Teil einer Transaktion ausführen, übernimmt Spanner gemeinsame Lesesperren, wodurch andere Lesevorgänge weiterhin auf die Daten zugreifen können, bis die Transaktion zum Commit bereit ist. Wenn sich Ihre Transaktion im Commit befindet und Schreibvorgänge angewendet werden, versucht die Transaktion, ein Upgrade auf eine exklusive Sperre auszuführen. Sie blockiert neue gemeinsam genutzte Lesesperren für die Daten, wartet darauf, dass vorhandene gemeinsam genutzte Lesesperren bereinigt werden, und setzt eine exklusive Sperre für den exklusiven Zugriff auf die Daten ein.

Hinweise zu Sperren:

• Sperren werden mit der Granularität von Zeile und Spalte vorgenommen. Wenn mit der Transaktion T1 die Spalte "A" der Zeile "foo" gesperrt wurde und mit Transaktion T2 die Spalte "B" der Zeile "foo" geschrieben werden soll, besteht kein Konflikt.
• Schreibvorgänge in einem Datenelement, das nicht auch die Daten liest, die gerade geschrieben werden (auch "blind writes" genannt) stehen in keinem Konflikt zu anderen Blind Writers desselben Elements (der Commit-Zeitstempel der einzelnen Schreibvorgänge bestimmt die Reihenfolge, in der er auf die Datenbank angewendet wird). Dies hat zur Folge, dass Spanner nur dann auf eine exklusive Sperre aktualisiert werden muss, wenn Sie die Daten, die Sie schreiben, gelesen haben. Andernfalls verwendet Spanner eine freigegebene Sperre, die als vom Autor freigegebene Sperre bezeichnet wird.
• Wenn Sie einzelne Suchvorgänge innerhalb einer Lese-Schreib-Transaktion ausführen, begrenzen Sie die Anzahl der durchsuchten Zeilen mit sekundären Indexen. Dadurch sperrt Spanner weniger Zeilen in der Tabelle, sodass Zeilen außerhalb des Bereichs gleichzeitig geändert werden können.

• Sperren sollten nicht verwendet werden, um den exklusiven Zugriff auf eine Ressource außerhalb von Spanner sicherzustellen. Transaktionen können von Spanner aus verschiedenen Gründen abgebrochen werden, z. B. weil das Verschieben von Daten in den Rechenressourcen der Instanz zugelassen wird. Wenn eine Transaktion wiederholt wird, sei es explizit durch Anwendungscode oder implizit mit Clientcode wie dem Spanner-JDBC-Treiber, werden die Sperren nur während des Versuchs beibehalten, für den tatsächlich ein Commit durchgeführt wurde.

• Mit dem Introspektionstool zum Sperren von Statistiken können Sie Sperrkonflikte in Ihrer Datenbank untersuchen.

Deadlock-Erkennung

Spanner erkennt, wenn mehrere Transaktionen blockiert werden, und zwingt alle Transaktionen bis auf eine zum Abbrechen. Betrachten Sie zum Beispiel das folgende Szenario: Transaktion Txn1 enthält eine Sperre für Datensatz A und wartet auf eine Sperre für Datensatz B. Txn2 enthält eine Sperre für Datensatz B und wartet auf eine Sperre für Datensatz A. Die einzige Möglichkeit, in dieser Situation voranzukommen, besteht darin, eine der Transaktionen abzubrechen, damit die Sperre freigegeben wird und die andere Transaktion fortgesetzt werden kann.

Spanner verwendet den Standardalgorithmus „wound-wait“ für die Deadlock-Erkennung. Intern verfolgt Spanner das Alter jeder Transaktion, die in Konflikt stehende Sperren anfordert. Es ermöglicht älteren Transaktionen, jüngere Transaktionen abzubrechen (wobei "älter" heißt, dass die frühesten Lese-, Abfrage- oder Commit-Vorgänge der Transaktion früher begonnen haben).

Dadurch, dass ältere Transaktionen Priorität erhalten, sorgt Spanner dafür, dass jede Transaktion die Möglichkeit hat, Sperren zu erhalten, sobald sie alt genug ist, um eine höhere Priorität als andere Transaktionen zu erhalten. Zum Beispiel kann eine Transaktion, die eine vom Leser freigegebene Sperre erhält, von einer älteren Transaktion abgebrochen werden, die eine vom Autor freigegebene Sperre benötigt.

Verteilte Ausführung

Spanner kann Transaktionen für Daten ausführen, die sich über mehrere Server erstrecken. Diese Leistung führt zu Leistungskosten, die mit denen von Transaktionen auf nur einem Server zu vergleichen sind.

Welche Arten von Transaktionen können verteilt sein? Intern kann Spanner die Verantwortung für Zeilen in der Datenbank auf viele Server aufteilen. Eine Zeile und die entsprechenden Zeilen in verschränkten Tabellen werden in der Regel von denselben Transaktionen über mehrere Zeilen auf verschiedenen Servern bereitgestellt. Als Faustregel gilt jedoch, dass Transaktionen, die viele Zeilen an einem Standort betreffen, schneller und günstiger sind als Transaktionen, die viele in der Datenbank oder in einer großen Tabelle verteilte Zeilen betreffen.

Die effizientesten Transaktionen in Spanner umfassen nur die Lese- und Schreibvorgänge, die atomar angewendet werden sollen. Transaktionen sind am schnellsten, wenn alle Lese- und Schreibzugriffe auf Daten im selben Teil des Schlüsselbereichs erfolgen.

Schreibgeschützte Transaktionen

Zusätzlich zum Sperren von Lese-Schreib-Transaktionen bietet Spanner schreibgeschützte Transaktionen.

Verwenden Sie eine schreibgeschützte Transaktion, wenn Sie mehr als einen Lesevorgang mit demselben Zeitstempel ausführen müssen. Wenn Sie Ihren Lesevorgang mit einer der einzelnen Lesemethoden von Spanner ausdrücken können, sollten Sie stattdessen diese einzelne Lesemethode verwenden. Die Leistung bei der Verwendung eines solchen einzelnen Leseaufrufs sollte mit der Leistung eines einzelnen Lesevorgangs vergleichbar sein, der in einer schreibgeschützten Transaktion ausgeführt wird.

Wenn Sie eine große Datenmenge lesen, sollten Sie Partitionen verwenden, um die Daten parallel zu lesen.

Da schreibgeschützte Transaktionen keine Schreibvorgänge ausführen, haben sie keine Sperren und blockieren andere Transaktionen nicht. Schreibgeschützte Transaktionen erkennen ein konsistentes Präfix des Commit-Verlaufs der Transaktion, damit Ihre Anwendung immer konsistente Daten erhält.

Attribute

Eine Spanner-Lesetransaktion führt eine Reihe von Lesevorgängen zu einem einzigen logischen Zeitpunkt aus, sowohl aus der Perspektive der schreibgeschützten Transaktion selbst als auch aus der Perspektive anderer Leser und Autoren für die Spanner-Datenbank. Dies bedeutet, dass schreibgeschützte Transaktionen immer einen konsistenten Zustand der Datenbank zu einem ausgewählten Punkt im Transaktionsverlauf erkennen.

Schnittstelle

Spanner bietet eine Schnittstelle zum Ausführen eines Arbeitsablaufs im Kontext einer schreibgeschützten Transaktion mit Wiederholungen für Transaktionsabbrüche.

Beispiel

Im Folgenden wird gezeigt, wie eine schreibgeschützte Transaktion verwendet werden kann, um konsistente Daten für zwei Lesevorgänge zum selben Zeitstempel zu erhalten:

C++

Auf GitHub ansehen

void ReadOnlyTransaction(google::cloud::spanner::Client client) {
  namespace spanner = ::google::cloud::spanner;
  auto read_only = spanner::MakeReadOnlyTransaction();

  spanner::SqlStatement select(
      "SELECT SingerId, AlbumId, AlbumTitle FROM Albums");
  using RowType = std::tuple<std::int64_t, std::int64_t, std::string>;

  // Read#1.
  auto rows1 = client.ExecuteQuery(read_only, select);
  std::cout << "Read 1 results\n";
  for (auto& row : spanner::StreamOf<RowType>(rows1)) {
    if (!row) throw std::move(row).status();
    std::cout << "SingerId: " << std::get<0>(*row)
              << " AlbumId: " << std::get<1>(*row)
              << " AlbumTitle: " << std::get<2>(*row) << "\n";
  }
  // Read#2. Even if changes occur in-between the reads the transaction ensures
  // that Read #1 and Read #2 return the same data.
  auto rows2 = client.ExecuteQuery(read_only, select);
  std::cout << "Read 2 results\n";
  for (auto& row : spanner::StreamOf<RowType>(rows2)) {
    if (!row) throw std::move(row).status();
    std::cout << "SingerId: " << std::get<0>(*row)
              << " AlbumId: " << std::get<1>(*row)
              << " AlbumTitle: " << std::get<2>(*row) << "\n";
  }
}

C#

Auf GitHub ansehen

using Google.Cloud.Spanner.Data;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using System.Transactions;

public class QueryDataWithTransactionAsyncSample
{
    public class Album
    {
        public int SingerId { get; set; }
        public int AlbumId { get; set; }
        public string AlbumTitle { get; set; }
    }

    public async Task<List<Album>> QueryDataWithTransactionAsync(string projectId, string instanceId, string databaseId)
    {
        string connectionString = $"Data Source=projects/{projectId}/instances/{instanceId}/databases/{databaseId}";

        var albums = new List<Album>();
        using TransactionScope scope = new TransactionScope(TransactionScopeAsyncFlowOption.Enabled);
        using var connection = new SpannerConnection(connectionString);

        // Open the connection, making the implicitly created
        // transaction read only when it connects to the outer
        // transaction scope.
        await connection.OpenAsReadOnlyAsync();
        using var cmd = connection.CreateSelectCommand("SELECT SingerId, AlbumId, AlbumTitle FROM Albums");

        // Read #1.
        using (var reader = await cmd.ExecuteReaderAsync())
        {
            while (await reader.ReadAsync())
            {
                Console.WriteLine("SingerId : " + reader.GetFieldValue<string>("SingerId")
                    + " AlbumId : " + reader.GetFieldValue<string>("AlbumId")
                    + " AlbumTitle : " + reader.GetFieldValue<string>("AlbumTitle"));
            }
        }

        // Read #2. Even if changes occur in-between the reads,
        // the transaction ensures that Read #1 and Read #2
        // return the same data.
        using (var reader = await cmd.ExecuteReaderAsync())
        {
            while (await reader.ReadAsync())
            {
                albums.Add(new Album
                {
                    AlbumId = reader.GetFieldValue<int>("AlbumId"),
                    SingerId = reader.GetFieldValue<int>("SingerId"),
                    AlbumTitle = reader.GetFieldValue<string>("AlbumTitle")
                });
            }
        }
        scope.Complete();
        Console.WriteLine("Transaction complete.");
        return albums;
    }
}

Einfach loslegen (Go)

Auf GitHub ansehen

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/spanner"
	"google.golang.org/api/iterator"
)

func readOnlyTransaction(w io.Writer, db string) error {
	ctx := context.Background()
	client, err := spanner.NewClient(ctx, db)
	if err != nil {
		return err
	}
	defer client.Close()

	ro := client.ReadOnlyTransaction()
	defer ro.Close()
	stmt := spanner.Statement{SQL: `SELECT SingerId, AlbumId, AlbumTitle FROM Albums`}
	iter := ro.Query(ctx, stmt)
	defer iter.Stop()
	for {
		row, err := iter.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return err
		}
		var singerID int64
		var albumID int64
		var albumTitle string
		if err := row.Columns(&singerID, &albumID, &albumTitle); err != nil {
			return err
		}
		fmt.Fprintf(w, "%d %d %s\n", singerID, albumID, albumTitle)
	}

	iter = ro.Read(ctx, "Albums", spanner.AllKeys(), []string{"SingerId", "AlbumId", "AlbumTitle"})
	defer iter.Stop()
	for {
		row, err := iter.Next()
		if err == iterator.Done {
			return nil
		}
		if err != nil {
			return err
		}
		var singerID int64
		var albumID int64
		var albumTitle string
		if err := row.Columns(&singerID, &albumID, &albumTitle); err != nil {
			return err
		}
		fmt.Fprintf(w, "%d %d %s\n", singerID, albumID, albumTitle)
	}
}

Java

Auf GitHub ansehen

static void readOnlyTransaction(DatabaseClient dbClient) {
  // ReadOnlyTransaction must be closed by calling close() on it to release resources held by it.
  // We use a try-with-resource block to automatically do so.
  try (ReadOnlyTransaction transaction = dbClient.readOnlyTransaction()) {
    ResultSet queryResultSet =
        transaction.executeQuery(
            Statement.of("SELECT SingerId, AlbumId, AlbumTitle FROM Albums"));
    while (queryResultSet.next()) {
      System.out.printf(
          "%d %d %s\n",
          queryResultSet.getLong(0), queryResultSet.getLong(1), queryResultSet.getString(2));
    }
    try (ResultSet readResultSet =
        transaction.read(
            "Albums", KeySet.all(), Arrays.asList("SingerId", "AlbumId", "AlbumTitle"))) {
      while (readResultSet.next()) {
        System.out.printf(
            "%d %d %s\n",
            readResultSet.getLong(0), readResultSet.getLong(1), readResultSet.getString(2));
      }
    }
  }
}

Node.js

Auf GitHub ansehen

// Imports the Google Cloud client library
const {Spanner} = require('@google-cloud/spanner');

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const projectId = 'my-project-id';
// const instanceId = 'my-instance';
// const databaseId = 'my-database';

// Creates a client
const spanner = new Spanner({
  projectId: projectId,
});

// Gets a reference to a Cloud Spanner instance and database
const instance = spanner.instance(instanceId);
const database = instance.database(databaseId);

// Gets a transaction object that captures the database state
// at a specific point in time
database.getSnapshot(async (err, transaction) => {
  if (err) {
    console.error(err);
    return;
  }
  const queryOne = 'SELECT SingerId, AlbumId, AlbumTitle FROM Albums';

  try {
    // Read #1, using SQL
    const [qOneRows] = await transaction.run(queryOne);

    qOneRows.forEach(row => {
      const json = row.toJSON();
      console.log(
        `SingerId: ${json.SingerId}, AlbumId: ${json.AlbumId}, AlbumTitle: ${json.AlbumTitle}`
      );
    });

    const queryTwo = {
      columns: ['SingerId', 'AlbumId', 'AlbumTitle'],
    };

    // Read #2, using the `read` method. Even if changes occur
    // in-between the reads, the transaction ensures that both
    // return the same data.
    const [qTwoRows] = await transaction.read('Albums', queryTwo);

    qTwoRows.forEach(row => {
      const json = row.toJSON();
      console.log(
        `SingerId: ${json.SingerId}, AlbumId: ${json.AlbumId}, AlbumTitle: ${json.AlbumTitle}`
      );
    });

    console.log('Successfully executed read-only transaction.');
  } catch (err) {
    console.error('ERROR:', err);
  } finally {
    transaction.end();
    // Close the database when finished.
    await database.close();
  }
});

PHP

Auf GitHub ansehen

use Google\Cloud\Spanner\SpannerClient;

/**
 * Reads data inside of a read-only transaction.
 *
 * Within the read-only transaction, or "snapshot", the application sees
 * consistent view of the database at a particular timestamp.
 * Example:
 * ```
 * read_only_transaction($instanceId, $databaseId);
 * ```
 *
 * @param string $instanceId The Spanner instance ID.
 * @param string $databaseId The Spanner database ID.
 */
function read_only_transaction(string $instanceId, string $databaseId): void
{
    $spanner = new SpannerClient();
    $instance = $spanner->instance($instanceId);
    $database = $instance->database($databaseId);

    $snapshot = $database->snapshot();
    $results = $snapshot->execute(
        'SELECT SingerId, AlbumId, AlbumTitle FROM Albums'
    );
    print('Results from the first read:' . PHP_EOL);
    foreach ($results as $row) {
        printf('SingerId: %s, AlbumId: %s, AlbumTitle: %s' . PHP_EOL,
            $row['SingerId'], $row['AlbumId'], $row['AlbumTitle']);
    }

    // Perform another read using the `read` method. Even if the data
    // is updated in-between the reads, the snapshot ensures that both
    // return the same data.
    $keySet = $spanner->keySet(['all' => true]);
    $results = $database->read(
        'Albums',
        $keySet,
        ['SingerId', 'AlbumId', 'AlbumTitle']
    );

    print('Results from the second read:' . PHP_EOL);
    foreach ($results->rows() as $row) {
        printf('SingerId: %s, AlbumId: %s, AlbumTitle: %s' . PHP_EOL,
            $row['SingerId'], $row['AlbumId'], $row['AlbumTitle']);
    }
}

Python

Auf GitHub ansehen

def read_only_transaction(instance_id, database_id):
    """Reads data inside of a read-only transaction.

    Within the read-only transaction, or "snapshot", the application sees
    consistent view of the database at a particular timestamp.
    """
    spanner_client = spanner.Client()
    instance = spanner_client.instance(instance_id)
    database = instance.database(database_id)

    with database.snapshot(multi_use=True) as snapshot:
        # Read using SQL.
        results = snapshot.execute_sql(
            "SELECT SingerId, AlbumId, AlbumTitle FROM Albums"
        )

        print("Results from first read:")
        for row in results:
            print("SingerId: {}, AlbumId: {}, AlbumTitle: {}".format(*row))

        # Perform another read using the `read` method. Even if the data
        # is updated in-between the reads, the snapshot ensures that both
        # return the same data.
        keyset = spanner.KeySet(all_=True)
        results = snapshot.read(
            table="Albums", columns=("SingerId", "AlbumId", "AlbumTitle"), keyset=keyset
        )

        print("Results from second read:")
        for row in results:
            print("SingerId: {}, AlbumId: {}, AlbumTitle: {}".format(*row))

Ruby

Auf GitHub ansehen

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new project: project_id
client  = spanner.client instance_id, database_id

client.snapshot do |snapshot|
  snapshot.execute("SELECT SingerId, AlbumId, AlbumTitle FROM Albums").rows.each do |row|
    puts "#{row[:AlbumId]} #{row[:AlbumTitle]} #{row[:SingerId]}"
  end

  # Even if changes occur in-between the reads, the transaction ensures that
  # both return the same data.
  snapshot.read("Albums", [:AlbumId, :AlbumTitle, :SingerId]).rows.each do |row|
    puts "#{row[:AlbumId]} #{row[:AlbumTitle]} #{row[:SingerId]}"
  end
end

Partitionierte DML-Transaktionen

Mit partitionierten DML-Anweisungen (Partitioned Data Manipulation Language) können Sie umfangreiche Anweisungen des Typs UPDATE und DELETE ausführen, ohne die Transaktionslimits zu überschreiten oder eine ganze Tabelle zu sperren. Spanner partitioniert den Schlüsselbereich und führt die DML-Anweisungen für jede Partition in einer separaten Lese-Schreib-Transaktion aus.

Sie führen DML-Anweisungen in Lese-/Schreibtransaktionen aus, die Sie explizit in Ihrem Code erstellen. Weitere Informationen finden Sie unter DML verwenden.

Attribute

Sie können jeweils nur eine partitionierte DML-Anweisung ausführen, unabhängig davon, ob Sie eine Clientbibliotheksmethode oder die Google Cloud CLI verwenden.

Partitionierte Transaktionen unterstützen kein Commit oder Rollback. Spanner führt die DML-Anweisung sofort aus und wendet sie an. Wenn Sie den Vorgang abbrechen oder der Vorgang fehlschlägt, bricht Spanner alle ausgeführten Partitionen ab und startet keine der verbleibenden Partitionen. Spanner führt kein Rollback für bereits ausgeführte Partitionen durch.

Schnittstelle

Spanner bietet eine Schnittstelle zum Ausführen einer einzelnen partitionierten DML-Anweisung.

Beispiele

Mit den folgenden Codebeispielen wird die Spalte MarketingBudget der Tabelle Albums aktualisiert.

C++

Zum Ausführen einer partitionierten DML-Anweisung verwenden Sie die Funktion ExecutePartitionedDml().

Auf GitHub ansehen

void DmlPartitionedUpdate(google::cloud::spanner::Client client) {
  namespace spanner = ::google::cloud::spanner;
  auto result = client.ExecutePartitionedDml(
      spanner::SqlStatement("UPDATE Albums SET MarketingBudget = 100000"
                            "  WHERE SingerId > 1"));
  if (!result) throw std::move(result).status();
  std::cout << "Updated at least " << result->row_count_lower_bound
            << " row(s) [spanner_dml_partitioned_update]\n";
}

C#

Zum Ausführen einer partitionierten DML-Anweisung verwenden Sie die Methode ExecutePartitionedUpdateAsync().

Auf GitHub ansehen

using Google.Cloud.Spanner.Data;
using System;
using System.Threading.Tasks;

public class UpdateUsingPartitionedDmlCoreAsyncSample
{
    public async Task<long> UpdateUsingPartitionedDmlCoreAsync(string projectId, string instanceId, string databaseId)
    {
        string connectionString = $"Data Source=projects/{projectId}/instances/{instanceId}/databases/{databaseId}";

        using var connection = new SpannerConnection(connectionString);
        await connection.OpenAsync();

        using var cmd = connection.CreateDmlCommand("UPDATE Albums SET MarketingBudget = 100000 WHERE SingerId > 1");
        long rowCount = await cmd.ExecutePartitionedUpdateAsync();

        Console.WriteLine($"{rowCount} row(s) updated...");
        return rowCount;
    }
}

Einfach loslegen (Go)

Zum Ausführen einer partitionierten DML-Anweisung verwenden Sie die Methode PartitionedUpdate().

Auf GitHub ansehen

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/spanner"
)

func updateUsingPartitionedDML(w io.Writer, db string) error {
	ctx := context.Background()
	client, err := spanner.NewClient(ctx, db)
	if err != nil {
		return err
	}
	defer client.Close()

	stmt := spanner.Statement{SQL: "UPDATE Albums SET MarketingBudget = 100000 WHERE SingerId > 1"}
	rowCount, err := client.PartitionedUpdate(ctx, stmt)
	if err != nil {
		return err
	}
	fmt.Fprintf(w, "%d record(s) updated.\n", rowCount)
	return nil
}

Java

Zum Ausführen einer partitionierten DML-Anweisung verwenden Sie die Methode executePartitionedUpdate().

Auf GitHub ansehen

static void updateUsingPartitionedDml(DatabaseClient dbClient) {
  String sql = "UPDATE Albums SET MarketingBudget = 100000 WHERE SingerId > 1";
  long rowCount = dbClient.executePartitionedUpdate(Statement.of(sql));
  System.out.printf("%d records updated.\n", rowCount);
}

Node.js

Zum Ausführen einer partitionierten DML-Anweisung verwenden Sie die Methode runPartitionedUpdate().

Auf GitHub ansehen

// Imports the Google Cloud client library
const {Spanner} = require('@google-cloud/spanner');

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const projectId = 'my-project-id';
// const instanceId = 'my-instance';
// const databaseId = 'my-database';

// Creates a client
const spanner = new Spanner({
  projectId: projectId,
});

// Gets a reference to a Cloud Spanner instance and database
const instance = spanner.instance(instanceId);
const database = instance.database(databaseId);

try {
  const [rowCount] = await database.runPartitionedUpdate({
    sql: 'UPDATE Albums SET MarketingBudget = 100000 WHERE SingerId > 1',
  });
  console.log(`Successfully updated ${rowCount} records.`);
} catch (err) {
  console.error('ERROR:', err);
} finally {
  // Close the database when finished.
  database.close();
}

PHP

Zum Ausführen einer partitionierten DML-Anweisung verwenden Sie die Methode executePartitionedUpdate().

Auf GitHub ansehen

use Google\Cloud\Spanner\SpannerClient;

/**
 * Updates sample data in the database by partition with a DML statement.
 *
 * This updates the `MarketingBudget` column which must be created before
 * running this sample. You can add the column by running the `add_column`
 * sample or by running this DDL statement against your database:
 *
 *     ALTER TABLE Albums ADD COLUMN MarketingBudget INT64
 *
 * Example:
 * ```
 * update_data($instanceId, $databaseId);
 * ```
 *
 * @param string $instanceId The Spanner instance ID.
 * @param string $databaseId The Spanner database ID.
 */
function update_data_with_partitioned_dml(string $instanceId, string $databaseId): void
{
    $spanner = new SpannerClient();
    $instance = $spanner->instance($instanceId);
    $database = $instance->database($databaseId);

    $rowCount = $database->executePartitionedUpdate(
        'UPDATE Albums SET MarketingBudget = 100000 WHERE SingerId > 1'
    );

    printf('Updated %d row(s).' . PHP_EOL, $rowCount);
}

Python

Zum Ausführen einer partitionierten DML-Anweisung verwenden Sie die Methode execute_partitioned_dml().

Auf GitHub ansehen

# instance_id = "your-spanner-instance"
# database_id = "your-spanner-db-id"

spanner_client = spanner.Client()
instance = spanner_client.instance(instance_id)
database = instance.database(database_id)

row_ct = database.execute_partitioned_dml(
    "UPDATE Albums SET MarketingBudget = 100000 WHERE SingerId > 1"
)

print("{} records updated.".format(row_ct))

Ruby

Zum Ausführen einer partitionierten DML-Anweisung verwenden Sie die Methode execute_partitioned_update().

Auf GitHub ansehen

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new project: project_id
client  = spanner.client instance_id, database_id

row_count = client.execute_partition_update(
  "UPDATE Albums SET MarketingBudget = 100000 WHERE SingerId > 1"
)

puts "#{row_count} records updated."

Im folgenden Codebeispiel werden Zeilen aus der Tabelle Singers anhand der Spalte SingerId gelöscht.

C++

Auf GitHub ansehen

void DmlPartitionedDelete(google::cloud::spanner::Client client) {
  namespace spanner = ::google::cloud::spanner;
  auto result = client.ExecutePartitionedDml(
      spanner::SqlStatement("DELETE FROM Singers WHERE SingerId > 10"));
  if (!result) throw std::move(result).status();
  std::cout << "Deleted at least " << result->row_count_lower_bound
            << " row(s) [spanner_dml_partitioned_delete]\n";
}

C#

Auf GitHub ansehen

using Google.Cloud.Spanner.Data;
using System;
using System.Threading.Tasks;

public class DeleteUsingPartitionedDmlCoreAsyncSample
{
    public async Task<long> DeleteUsingPartitionedDmlCoreAsync(string projectId, string instanceId, string databaseId)
    {
        string connectionString = $"Data Source=projects/{projectId}/instances/{instanceId}/databases/{databaseId}";

        using var connection = new SpannerConnection(connectionString);
        await connection.OpenAsync();

        using var cmd = connection.CreateDmlCommand("DELETE FROM Singers WHERE SingerId > 10");
        long rowCount = await cmd.ExecutePartitionedUpdateAsync();

        Console.WriteLine($"{rowCount} row(s) deleted...");
        return rowCount;
    }
}

Einfach loslegen (Go)

Auf GitHub ansehen

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/spanner"
)

func deleteUsingPartitionedDML(w io.Writer, db string) error {
	ctx := context.Background()
	client, err := spanner.NewClient(ctx, db)
	if err != nil {
		return err
	}
	defer client.Close()

	stmt := spanner.Statement{SQL: "DELETE FROM Singers WHERE SingerId > 10"}
	rowCount, err := client.PartitionedUpdate(ctx, stmt)
	if err != nil {
		return err

	}
	fmt.Fprintf(w, "%d record(s) deleted.", rowCount)
	return nil
}

Java

Auf GitHub ansehen

static void deleteUsingPartitionedDml(DatabaseClient dbClient) {
  String sql = "DELETE FROM Singers WHERE SingerId > 10";
  long rowCount = dbClient.executePartitionedUpdate(Statement.of(sql));
  System.out.printf("%d records deleted.\n", rowCount);
}

Node.js

Auf GitHub ansehen

// Imports the Google Cloud client library
const {Spanner} = require('@google-cloud/spanner');

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const projectId = 'my-project-id';
// const instanceId = 'my-instance';
// const databaseId = 'my-database';

// Creates a client
const spanner = new Spanner({
  projectId: projectId,
});

// Gets a reference to a Cloud Spanner instance and database
const instance = spanner.instance(instanceId);
const database = instance.database(databaseId);

try {
  const [rowCount] = await database.runPartitionedUpdate({
    sql: 'DELETE FROM Singers WHERE SingerId > 10',
  });
  console.log(`Successfully deleted ${rowCount} records.`);
} catch (err) {
  console.error('ERROR:', err);
} finally {
  // Close the database when finished.
  database.close();
}

PHP

Auf GitHub ansehen

use Google\Cloud\Spanner\SpannerClient;

/**
 * Delete sample data in the database by partition with a DML statement.
 *
 * This updates the `MarketingBudget` column which must be created before
 * running this sample. You can add the column by running the `add_column`
 * sample or by running this DDL statement against your database:
 *
 *     ALTER TABLE Albums ADD COLUMN MarketingBudget INT64
 *
 * Example:
 * ```
 * update_data($instanceId, $databaseId);
 * ```
 *
 * @param string $instanceId The Spanner instance ID.
 * @param string $databaseId The Spanner database ID.
 */
function delete_data_with_partitioned_dml(string $instanceId, string $databaseId): void
{
    $spanner = new SpannerClient();
    $instance = $spanner->instance($instanceId);
    $database = $instance->database($databaseId);

    $rowCount = $database->executePartitionedUpdate(
        'DELETE FROM Singers WHERE SingerId > 10'
    );

    printf('Deleted %d row(s).' . PHP_EOL, $rowCount);
}

Python

Auf GitHub ansehen

# instance_id = "your-spanner-instance"
# database_id = "your-spanner-db-id"
spanner_client = spanner.Client()
instance = spanner_client.instance(instance_id)
database = instance.database(database_id)

row_ct = database.execute_partitioned_dml("DELETE FROM Singers WHERE SingerId > 10")

print("{} record(s) deleted.".format(row_ct))

Ruby

Auf GitHub ansehen

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new project: project_id
client  = spanner.client instance_id, database_id

row_count = client.execute_partition_update(
  "DELETE FROM Singers WHERE SingerId > 10"
)

puts "#{row_count} records deleted."