Primeros pasos con Cloud Spanner en C#

Objetivos

En este instructivo, se explican los siguientes pasos a fin de usar la biblioteca cliente de Cloud Spanner para C#:

  • Crear una base de datos y una instancia de Cloud Spanner
  • Escribe, lee y ejecuta consultas de SQL sobre datos en la base de datos.
  • Actualiza el esquema de la base de datos.
  • Actualiza los datos mediante una transacción de lectura y escritura.
  • Agrega un índice secundario a la base de datos.
  • Usa el índice para leer y ejecutar consultas de SQL sobre datos.
  • Recupera datos con una transacción de solo lectura.

Costos

En este instructivo, se usa Cloud Spanner, que es un componente facturable de Google Cloud. Para obtener información sobre el costo de usar Cloud Spanner, consulta Precios.

Antes de comenzar

Completa los pasos descritos en Configuración, que abarcan la creación y configuración de un proyecto de Google Cloud predeterminado, la facturación, la habilitación de la API de Cloud Spanner y la configuración de OAuth 2.0 para obtener credenciales de autenticación para usar la API de Cloud Spanner.

En especial, asegúrate de ejecutar gcloud auth application-default login para configurar tu entorno de desarrollo local con credenciales de autenticación.

Prepara el entorno local de C#

  1. Establece la variable de entorno GOOGLE_PROJECT_ID en tu ID del proyecto de Google Cloud.

    1. Primero, configura GOOGLE_PROJECT_ID para la sesión actual de PowerShell:

      $env:GOOGLE_PROJECT_ID = "MY_PROJECT_ID"
    2. Luego, configura GOOGLE_PROJECT_ID para todos los procesos creados después de este comando:

      [Environment]::SetEnvironmentVariable("GOOGLE_PROJECT_ID", "MY_PROJECT_ID", "User")
  2. Descarga credenciales.

    1. Ve a la página Credenciales en Google Cloud Console.

      Ir a la página Credenciales

    2. Haz clic en Crear credenciales y selecciona Clave de cuenta de servicio.

    3. En "Cuenta de servicio", selecciona Cuenta de servicio predeterminada de Compute Engine y deja JSON seleccionado en "Tipo de clave". Haz clic en Crear. Tu computadora descarga un archivo JSON.

  3. Configura las credenciales. Para un archivo llamado FILENAME.json en el directorio Descargas de CURRENT_USER, ubicado en la unidad C, ejecuta los siguientes comandos para configurar GOOGLE_APPLICATION_CREDENTIALS a fin de que apunte a la clave JSON:

    1. En primer lugar, a fin de configurar GOOGLE_APPLICATION_CREDENTIALS para esta sesión de PowerShell, ejecuta este comando:

      $env:GOOGLE_APPLICATION_CREDENTIALS = "C:\Users\CURRENT_USER\Downloads\FILENAME.json"
    2. Luego, ejecuta lo siguiente a fin de configurar GOOGLE_APPLICATION_CREDENTIALS para todos los procesos creados después de este comando:

      [Environment]::SetEnvironmentVariable("GOOGLE_APPLICATION_CREDENTIALS", "C:\Users\CURRENT_USER\Downloads\FILENAME.json", "User")
  4. Clona el repositorio de la aplicación de muestra en tu máquina local con el siguiente comando:

    git clone https://github.com/GoogleCloudPlatform/dotnet-docs-samples
    

    De manera opcional, puedes descargar la muestra como un archivo zip y extraerla.

  5. Abre Spanner.sln, que se encuentra en el directorio dotnet-docs-samples\spanner\api del repositorio descargado, con Visual Studio 2017 o una versión posterior y, luego, compílala.

  6. Ve al directorio dentro del repositorio descargado que contiene la aplicación compilada. Por ejemplo:

    cd dotnet-docs-samples\spanner\api\Spanner
    

Crea una instancia

Cuando usas Cloud Spanner por primera vez, debes crear una instancia, que es una asignación de recursos que usan las bases de datos de Cloud Spanner. Cuando creas una instancia, debes elegir una configuración de instancia, que determina dónde se almacenan tus datos y también la cantidad de nodos que se usarán, lo que, a su vez, determina la cantidad de recursos de entrega y almacenamiento de tu instancia.

Ejecuta el siguiente comando para crear una instancia de Cloud Spanner en la región us-central1 con 1 nodo:

gcloud spanner instances create test-instance --config=regional-us-central1 `
    --description="Test Instance" --nodes=1

Ten en cuenta que esto crea una instancia con las siguientes características:

  • ID de instancia: test-instance
  • Nombre visible: Test Instance
  • Configuración de la instancia: regional-us-central1 (la configuración regional almacena datos en una región, mientras que la multirregional distribuye datos en varias regiones; obtén más información en Instancias)
  • Recuento de nodos: 1 (node_count corresponde a la cantidad de recursos de procesamiento y almacenamiento disponibles para las bases de datos de la instancia; obtén más información en Recuento de nodos)

Deberías ver lo siguiente:

Creating instance...done.

Examina archivos de muestra

El repositorio de muestras contiene una muestra que indica cómo usar Cloud Spanner con C#.

Observa el archivo spanner/api/Spanner/Program.cs, que muestra cómo crear una base de datos y modificar un esquema de base de datos. Los datos utilizan el esquema de ejemplo que se muestra en la página Esquema y modelo de datos.

Crea una base de datos

Para crear una base de datos llamada example-db en la instancia test-instance, ejecuta lo siguiente en la línea de comandos.

dotnet run createSampleDatabase $env:GOOGLE_PROJECT_ID test-instance example-db

Deberías ver lo siguiente:

Created sample database example-db on instance test-instance

Acabas de crear una base de datos de Cloud Spanner. El siguiente es el código que creó la base de datos:

// Initialize request connection string for database creation.
string connectionString =
    $"Data Source=projects/{projectId}/instances/{instanceId}";
// Make the request.
using (var connection = new SpannerConnection(connectionString))
{
    string createStatement = $"CREATE DATABASE `{databaseId}`";
    var cmd = connection.CreateDdlCommand(createStatement);
    await cmd.ExecuteNonQueryAsync();
}
// Update connection string with Database ID for table creation.
connectionString = connectionString + $"/databases/{databaseId}";
using (var connection = new SpannerConnection(connectionString))
{
    // Define create table statement for table #1.
    string createTableStatement =
   @"CREATE TABLE Singers (
         SingerId INT64 NOT NULL,
         FirstName    STRING(1024),
         LastName STRING(1024),
         ComposerInfo   BYTES(MAX)
     ) PRIMARY KEY (SingerId)";
    // Make the request.
    var cmd = connection.CreateDdlCommand(createTableStatement);
    await cmd.ExecuteNonQueryAsync();
    // Define create table statement for table #2.
    createTableStatement =
    @"CREATE TABLE Albums (
         SingerId     INT64 NOT NULL,
         AlbumId      INT64 NOT NULL,
         AlbumTitle   STRING(MAX)
     ) PRIMARY KEY (SingerId, AlbumId),
     INTERLEAVE IN PARENT Singers ON DELETE CASCADE";
    // Make the request.
    cmd = connection.CreateDdlCommand(createTableStatement);
    await cmd.ExecuteNonQueryAsync();
}

El código también define dos tablas, Singers y Albums, para una aplicación básica de música. Ambas tablas se usan en toda la página. Si aún no lo has hecho, consulta el esquema de ejemplo.

El siguiente paso consiste en escribir datos en tu base de datos.

Crea un cliente de base de datos

Para poder realizar operaciones de lectura o escritura, debes crear un Spanner​Connection:


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

namespace GoogleCloudSamples.Spanner
{
    public class QuickStart
    {
        static async Task MainAsync()
        {
            string projectId = "YOUR-PROJECT-ID";
            string instanceId = "my-instance";
            string databaseId = "my-database";
            string connectionString =
                $"Data Source=projects/{projectId}/instances/{instanceId}/"
                + $"databases/{databaseId}";
            // Create connection to Cloud Spanner.
            using (var connection = new SpannerConnection(connectionString))
            {
                // Execute a simple SQL statement.
                var cmd = connection.CreateSelectCommand(
                    @"SELECT ""Hello World"" as test");
                using (var reader = await cmd.ExecuteReaderAsync())
                {
                    while (await reader.ReadAsync())
                    {
                        Console.WriteLine(
                            reader.GetFieldValue<string>("test"));
                    }
                }
            }
        }
        public static void Main(string[] args)
        {
            MainAsync().Wait();
        }
    }
}

Un Spanner​Connection es como una conexión de base de datos: todas tus interacciones con Cloud Spanner deben pasar por un Spanner​Connection.

Obtén más información en la referencia Spanner​Connection.

Escribe datos con DML

Puedes insertar datos mediante el lenguaje de manipulación de datos (DML) en una transacción de lectura y escritura.

Usarás el método ExecuteNonQueryAsync() para ejecutar una Declaración DML.

public static async Task WriteUsingDmlCoreAsync(
    string projectId,
    string instanceId,
    string databaseId)
{
    string connectionString =
        $"Data Source=projects/{projectId}/instances/{instanceId}"
        + $"/databases/{databaseId}";

    // Create connection to Cloud Spanner.
    using (var connection =
        new SpannerConnection(connectionString))
    {
        await connection.OpenAsync();

        SpannerCommand cmd = connection.CreateDmlCommand(
            "INSERT Singers (SingerId, FirstName, LastName) VALUES "
               + "(12, 'Melissa', 'Garcia'), "
               + "(13, 'Russell', 'Morales'), "
               + "(14, 'Jacqueline', 'Long'), "
               + "(15, 'Dylan', 'Shaw')");
        int rowCount = await cmd.ExecuteNonQueryAsync();
        Console.WriteLine($"{rowCount} row(s) inserted...");
    }
}

Ejecuta la muestra con el argumento writeUsingDml.

dotnet run writeUsingDml $env:GOOGLE_PROJECT_ID test-instance example-db

Debería ver lo siguiente:

4 row(s) inserted...

Escribe datos con mutaciones

También puedes insertar datos mediante mutaciones.

Puedes insertar datos con el método connection.CreateInsertCommand(), que crea un SpannerCommand nuevo para insertar filas en una tabla. El método SpannerCommand.ExecuteNonQueryAsync() agrega filas nuevas a la tabla.

En este código, se muestra cómo insertar datos mediante mutaciones:

public class Singer
{
    public int SingerId { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
}

public class Album
{
    public int SingerId { get; set; }
    public int AlbumId { get; set; }
    public string AlbumTitle { get; set; }
}
public static async Task InsertSampleDataAsync(
    string projectId, string instanceId, string databaseId)
{
    const int firstSingerId = 1;
    const int secondSingerId = 2;
    string connectionString =
    $"Data Source=projects/{projectId}/instances/{instanceId}"
    + $"/databases/{databaseId}";
    List<Singer> singers = new List<Singer>
    {
        new Singer { SingerId = firstSingerId, FirstName = "Marc",
            LastName = "Richards" },
        new Singer { SingerId = secondSingerId, FirstName = "Catalina",
            LastName = "Smith" },
        new Singer { SingerId = 3, FirstName = "Alice",
            LastName = "Trentor" },
        new Singer { SingerId = 4, FirstName = "Lea",
            LastName = "Martin" },
        new Singer { SingerId = 5, FirstName = "David",
            LastName = "Lomond" },
    };
    List<Album> albums = new List<Album>
    {
        new Album { SingerId = firstSingerId, AlbumId = 1,
            AlbumTitle = "Total Junk" },
        new Album { SingerId = firstSingerId, AlbumId = 2,
            AlbumTitle = "Go, Go, Go" },
        new Album { SingerId = secondSingerId, AlbumId = 1,
            AlbumTitle = "Green" },
        new Album { SingerId = secondSingerId, AlbumId = 2,
            AlbumTitle = "Forever Hold your Peace" },
        new Album { SingerId = secondSingerId, AlbumId = 3,
            AlbumTitle = "Terrified" },
    };
    // Create connection to Cloud Spanner.
    using (var connection = new SpannerConnection(connectionString))
    {
        await connection.OpenAsync();

        // Insert rows into the Singers table.
        var cmd = connection.CreateInsertCommand("Singers",
            new SpannerParameterCollection
            {
                { "SingerId", SpannerDbType.Int64 },
                { "FirstName", SpannerDbType.String },
                { "LastName", SpannerDbType.String }
            });
        await Task.WhenAll(singers.Select(singer =>
        {
            cmd.Parameters["SingerId"].Value = singer.SingerId;
            cmd.Parameters["FirstName"].Value = singer.FirstName;
            cmd.Parameters["LastName"].Value = singer.LastName;
            return cmd.ExecuteNonQueryAsync();
        }));

        // Insert rows into the Albums table.
        cmd = connection.CreateInsertCommand("Albums",
            new SpannerParameterCollection
            {
                { "SingerId", SpannerDbType.Int64 },
                { "AlbumId", SpannerDbType.Int64 },
                { "AlbumTitle", SpannerDbType.String }
            });
        await Task.WhenAll(albums.Select(album =>
        {
            cmd.Parameters["SingerId"].Value = album.SingerId;
            cmd.Parameters["AlbumId"].Value = album.AlbumId;
            cmd.Parameters["AlbumTitle"].Value = album.AlbumTitle;
            return cmd.ExecuteNonQueryAsync();
        }));
        Console.WriteLine("Inserted data.");
    }
}

Ejecuta la muestra con el argumento insertSampleData.

dotnet run insertSampleData $env:GOOGLE_PROJECT_ID test-instance example-db

Debería ver lo siguiente:

Inserted data.

Consulta datos mediante SQL

Cloud Spanner admite una interfaz nativa de SQL para leer datos, a la que puedes acceder desde la línea de comandos mediante la herramienta de línea de comandos de gcloud o de manera programática mediante la biblioteca cliente de Cloud Spanner para C#.

En la línea de comandos

Ejecuta la siguiente instrucción de SQL para leer los valores de todas las columnas de la tabla Albums:

gcloud spanner databases execute-sql example-db --instance=test-instance `
    --sql='SELECT SingerId, AlbumId, AlbumTitle FROM Albums'

El resultado debería ser este:

SingerId AlbumId AlbumTitle
1        1       Total Junk
1        2       Go, Go, Go
2        1       Green
2        2       Forever Hold Your Peace
2        3       Terrified

Usa la biblioteca cliente de Cloud Spanner para C#

Además de ejecutar una instrucción de SQL en la línea de comandos, puedes emitir la misma instrucción de SQL de manera programática con la biblioteca cliente de Cloud Spanner para C#.

Usa ExecuteReaderAsync() para ejecutar la consulta de SQL.

string connectionString =
$"Data Source=projects/{projectId}/instances/"
+ $"{instanceId}/databases/{databaseId}";
// Create connection to Cloud Spanner.
using (var connection = new SpannerConnection(connectionString))
{
    var cmd = connection.CreateSelectCommand(
        "SELECT SingerId, AlbumId, AlbumTitle FROM Albums");
    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"));
        }
    }
}

Aquí se muestra cómo enviar la consulta y acceder a los datos:

dotnet run querySampleData $env:GOOGLE_PROJECT_ID test-instance example-db

Deberías ver el siguiente resultado:

SingerId: 1 AlbumId: 1 AlbumTitle: Total Junk
SingerId: 1 AlbumId: 2 AlbumTitle: Go, Go, Go
SingerId: 2 AlbumId: 1 AlbumTitle: Green
SingerId: 2 AlbumId: 2 AlbumTitle: Forever Hold your Peace
SingerId: 2 AlbumId: 3 AlbumTitle: Terrified

Realiza consultas con un parámetro de SQL

Puedes incluir valores personalizados en las instrucciones de SQL mediante parámetros. Este es un ejemplo del uso de @lastName como parámetro en la cláusula WHERE a fin de consultar registros que contienen un valor específico para LastName.

string connectionString =
$"Data Source=projects/{projectId}/instances/{instanceId}"
+ $"/databases/{databaseId}";
// Create connection to Cloud Spanner.
using (var connection = new SpannerConnection(connectionString))
{
    var cmd = connection.CreateSelectCommand(
        "SELECT SingerId, FirstName, LastName FROM Singers "
        + $"WHERE LastName = @lastName",
        new SpannerParameterCollection {
            {"lastName", SpannerDbType.String}});
    cmd.Parameters["lastName"].Value = "Garcia";
    using (var reader = await cmd.ExecuteReaderAsync())
    {
        while (await reader.ReadAsync())
        {
            Console.WriteLine("SingerId : "
            + reader.GetFieldValue<string>("SingerId")
            + " FirstName : "
            + reader.GetFieldValue<string>("FirstName")
            + " LastName : "
            + reader.GetFieldValue<string>("LastName"));
        }
    }
}

A continuación, se muestra cómo enviar la consulta con un parámetro y acceder a los datos:

dotnet run queryWithParameter $env:GOOGLE_PROJECT_ID test-instance example-db

Deberías ver el siguiente resultado:

SingerId : 12 FirstName : Melissa LastName : Garcia

Actualiza el esquema de la base de datos

Supongamos que necesitas agregar una columna nueva llamada MarketingBudget a la tabla Albums. Para agregar una columna nueva a una tabla existente, es necesario actualizar el esquema de la base de datos. Cloud Spanner admite actualizaciones del esquema de una base de datos mientras esta sigue entregando tráfico. Las actualizaciones de esquema no requieren que la base de datos esté sin conexión y no bloquean tablas ni columnas completas. Puedes continuar escribiendo datos en la base de datos durante la actualización del esquema. Obtén más información sobre las actualizaciones admitidas del esquema y el rendimiento de los cambios de esquema en la página sobre actualizaciones de esquema.

Agrega una columna

Puedes agregar una columna en la línea de comandos mediante la herramienta de línea de comandos de gcloud o de manera programática mediante la biblioteca cliente de Cloud Spanner para C#.

En la línea de comandos

Usa el siguiente comando ALTER TABLE para agregar la columna nueva a la tabla:

gcloud spanner databases ddl update example-db --instance=test-instance `
    --ddl='ALTER TABLE Albums ADD COLUMN MarketingBudget INT64'

Deberías ver lo siguiente:

Schema updating...done.

Usa la biblioteca cliente de Cloud Spanner para C#

Usa CreateDdlCommand() para modificar el esquema:

// Initialize request argument(s).
string connectionString =
    $"Data Source=projects/{projectId}/instances/"
    + $"{instanceId}/databases/{databaseId}";
string alterStatement =
    "ALTER TABLE Albums ADD COLUMN MarketingBudget INT64";
// Make the request.
using (var connection = new SpannerConnection(connectionString))
{
    var updateCmd = connection.CreateDdlCommand(alterStatement);
    await updateCmd.ExecuteNonQueryAsync();
}
Console.WriteLine("Added the MarketingBudget column.");

Ejecuta la muestra mediante el comando addColumn.

dotnet run addColumn $env:GOOGLE_PROJECT_ID test-instance example-db

Deberías ver lo siguiente:

Added the MarketingBudget column.

Escribe datos en la columna nueva

Con el siguiente código, se escriben datos en la columna nueva. Configura MarketingBudget en 100000 para la fila marcada por Albums(1, 1) y en 500000 para la fila marcada por Albums(2, 2).

string connectionString =
$"Data Source=projects/{projectId}/instances/{instanceId}"
+ $"/databases/{databaseId}";
// Create connection to Cloud Spanner.
using (var connection = new SpannerConnection(connectionString))
{
    var cmd = connection.CreateUpdateCommand("Albums",
        new SpannerParameterCollection {
            {"SingerId", SpannerDbType.Int64},
            {"AlbumId", SpannerDbType.Int64},
            {"MarketingBudget", SpannerDbType.Int64},
        });
    var cmdLookup =
        connection.CreateSelectCommand("SELECT * FROM Albums");
    using (var reader = await cmdLookup.ExecuteReaderAsync())
    {
        while (await reader.ReadAsync())
        {
            if (reader.GetFieldValue<int>("SingerId") == 1
                && reader.GetFieldValue<int>("AlbumId") == 1)
            {
                cmd.Parameters["SingerId"].Value =
                    reader.GetFieldValue<int>("SingerId");
                cmd.Parameters["AlbumId"].Value =
                    reader.GetFieldValue<int>("AlbumId");
                cmd.Parameters["MarketingBudget"].Value = 100000;
                await cmd.ExecuteNonQueryAsync();
            }
            if (reader.GetInt64(0) == 2 && reader.GetInt64(1) == 2)
            {
                cmd.Parameters["SingerId"].Value =
                    reader.GetFieldValue<int>("SingerId");
                cmd.Parameters["AlbumId"].Value =
                    reader.GetFieldValue<int>("AlbumId");
                cmd.Parameters["MarketingBudget"].Value = 500000;
                await cmd.ExecuteNonQueryAsync();
            }
        }
    }
}
Console.WriteLine("Updated data.");

Ejecuta la muestra mediante el comando writeDataToNewColumn.

dotnet run writeDataToNewColumn $env:GOOGLE_PROJECT_ID test-instance example-db

Deberías ver lo siguiente:

Updated data.

También puedes ejecutar una consulta de SQL para obtener los valores que acabas de escribir.

Este es el código para ejecutar la consulta:

string connectionString =
$"Data Source=projects/{projectId}/instances/{instanceId}"
+ $"/databases/{databaseId}";
// Create connection to Cloud Spanner.
using (var connection = new SpannerConnection(connectionString))
{
    var cmd =
        connection.CreateSelectCommand("SELECT * FROM Albums");
    using (var reader = await cmd.ExecuteReaderAsync())
    {
        while (await reader.ReadAsync())
        {
            string budget = string.Empty;
            if (reader["MarketingBudget"] != DBNull.Value)
            {
                budget = reader.GetFieldValue<string>("MarketingBudget");
            }
            Console.WriteLine("SingerId : "
            + reader.GetFieldValue<string>("SingerId")
            + " AlbumId : "
            + reader.GetFieldValue<string>("AlbumId")
            + $" MarketingBudget : {budget}");
        }
    }
}

Para ejecutar esta consulta, ejecuta la muestra con el argumento queryNewColumn.

dotnet run queryNewColumn $env:GOOGLE_PROJECT_ID test-instance example-db

Deberías ver lo siguiente:

SingerId : 1 AlbumId : 1 MarketingBudget : 100000
SingerId : 1 AlbumId : 2 MarketingBudget :
SingerId : 2 AlbumId : 1 MarketingBudget :
SingerId : 2 AlbumId : 2 MarketingBudget : 500000
SingerId : 2 AlbumId : 3 MarketingBudget :

Actualiza datos

Puedes actualizar los datos mediante DML en una transacción de lectura y escritura.

Usarás el método ExecuteNonQueryAsync() para ejecutar una Declaración DML.

public static async Task WriteWithTransactionUsingDmlCoreAsync(
    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 addColumn and writeDataToNewColumn samples first,
    // in that order.
    string connectionString =
        $"Data Source=projects/{projectId}/instances/{instanceId}"
        + $"/databases/{databaseId}";

    decimal transferAmount = 200000;
    decimal secondBudget = 0;
    decimal firstBudget = 0;

    // Create connection to Cloud Spanner.
    using (var connection =
        new SpannerConnection(connectionString))
    {
        await connection.OpenAsync();

        // Create a readwrite transaction that we'll assign
        // to each SpannerCommand.
        using (var transaction =
                await connection.BeginTransactionAsync())
        {
            // Create statement to select the second album's data.
            var cmdLookup = connection.CreateSelectCommand(
             "SELECT * FROM Albums WHERE SingerId = 2 AND AlbumId = 2");
            cmdLookup.Transaction = transaction;
            // Excecute the select query.
            using (var reader = await cmdLookup.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 first album's "
                                + $"budget {secondBudget} "
                                + "is less than the "
                                + "amount to transfer.");
                    }
                }
            }
            // Read the first album's budget.
            cmdLookup = connection.CreateSelectCommand(
             "SELECT * FROM Albums WHERE SingerId = 1 and AlbumId = 1");
            cmdLookup.Transaction = transaction;
            using (var reader = await cmdLookup.ExecuteReaderAsync())
            {
                while (await reader.ReadAsync())
                {
                    firstBudget =
                      reader.GetFieldValue<decimal>("MarketingBudget");
                }
            }

            // Update second album to remove the transfer amount.
            secondBudget -= transferAmount;
            SpannerCommand cmd = connection.CreateDmlCommand(
                "UPDATE Albums SET MarketingBudget = @MarketingBudget "
                + "WHERE SingerId = 2 and AlbumId = 2");
            cmd.Parameters.Add("MarketingBudget", SpannerDbType.Int64, secondBudget);
            cmd.Transaction = transaction;
            await cmd.ExecuteNonQueryAsync();
            // Update first album to add the transfer amount.
            firstBudget += transferAmount;
            cmd = connection.CreateDmlCommand(
                "UPDATE Albums SET MarketingBudget = @MarketingBudget "
                + "WHERE SingerId = 1 and AlbumId = 1");
            cmd.Parameters.Add("MarketingBudget", SpannerDbType.Int64, firstBudget);
            cmd.Transaction = transaction;
            await cmd.ExecuteNonQueryAsync();

            await transaction.CommitAsync();
        }
        Console.WriteLine("Transaction complete.");
    }
}

Ejecuta la muestra con el argumento writeWithTransactionUsingDml.

dotnet run writeWithTransactionUsingDml $env:GOOGLE_PROJECT_ID test-instance example-db

Deberías ver lo siguiente:

Transaction complete.

Realiza reintentos en las transacciones de lectura y escritura

Cloud Spanner realiza reintentos para cada llamada de red y es resiliente a las fallas de red. Sin embargo, es posible que se produzca un interbloqueo cuando hay mucho esfuerzo, lo que provoca que una transacción de Cloud Spanner genere un mensaje SpannerException "Abortado". A fin de manejar esta excepción, debes utilizar un enfoque de "reintentar", como se muestra a continuación, para reintentar toda la transacción.

Primero, define un método al que se llamará cuando se deba reintentar la transacción. En el siguiente ejemplo, se define un método llamado RetryRobot.

public class RetryRobot
{
    public TimeSpan FirstRetryDelay { get; set; } = TimeSpan.FromSeconds(1000);
    public float DelayMultiplier { get; set; } = 2;
    public int MaxTryCount { get; set; } = 7;
    public Func<Exception, bool> ShouldRetry { get; set; }

    /// <summary>
    /// Retry action when assertion fails.
    /// </summary>
    /// <param name="func"></param>
    public T Eventually<T>(Func<T> func)
    {
        TimeSpan delay = FirstRetryDelay;
        for (int i = 0; ; ++i)
        {
            try
            {
                return func();
            }
            catch (Exception e)
            when (ShouldCatch(e) && i < MaxTryCount)
            {
                Thread.Sleep(delay);
                delay *= (int)DelayMultiplier;
            }
        }
    }

    private bool ShouldCatch(Exception e)
    {
        return ShouldRetry != null && ShouldRetry(e);
    }
}

A continuación, crea una instancia, llamada retryRobot, del método RetryRobot, y especifica IsTransientSpannerFault() como la condición de error que se debe reintentar. Luego, ejecuta la transacción completa con retryRobot.Eventually.

Este es el código para realizar el reintento:

var retryRobot = new RetryRobot
{
    MaxTryCount = 3,
    DelayMultiplier = 2,
    ShouldRetry = (e) => e.IsTransientSpannerFault()
};

await retryRobot.Eventually(() =>
    ReadWriteWithTransactionAsync(
        projectId, instanceId, databaseId));

Usa un índice secundario

Supongamos que deseas recuperar todas las filas de Albums que tienen valores AlbumTitle en un rango determinado. Puedes leer todos los valores de la columna AlbumTitle con una instrucción de SQL o una llamada de lectura y, luego, descartar las filas que no cumplan con los criterios. Sin embargo, analizar tablas enteras es costoso, especialmente si tienen muchas filas. En su lugar, crea un índice secundario en la tabla para acelerar la recuperación de filas cuando realizas búsquedas por columnas sin claves primarias.

Para agregar un índice secundario a una tabla existente, es necesario actualizar el esquema. Al igual que otras actualizaciones de esquema, Cloud Spanner admite que se agregue un índice mientras la base de datos continúa entregando tráfico. Cloud Spanner reabastece de manera automática el índice con tus datos existentes. Los reabastecimientos pueden tardar unos minutos en completarse, pero no es necesario que uses la base de datos sin conexión ni que evites escribir en la tabla indexada durante este proceso. Para obtener más detalles, consulta la sección sobre el reabastecimiento de índices.

Después de agregar un índice secundario, Cloud Spanner lo usa de forma automática en las consultas de SQL que probablemente se ejecuten más rápido con el índice. Si usas la interfaz de lectura, debes especificar el índice que deseas usar.

Agrega un índice secundario

Puedes agregar un índice en la línea de comandos mediante la herramienta de línea de comandos de gcloud o de manera programática mediante la biblioteca cliente de Cloud Spanner para C#.

En la línea de comandos

Usa el siguiente comando CREATE INDEX para agregar un índice a la base de datos:

gcloud spanner databases ddl update example-db --instance=test-instance `
    --ddl='CREATE INDEX AlbumsByAlbumTitle ON Albums(AlbumTitle)'

Deberías ver lo siguiente:

Schema updating...done.

Usa la biblioteca cliente de Cloud Spanner para C#

Usa CreateDdlCommand() para agregar un índice:

// Initialize request argument(s).
string connectionString =
    $"Data Source=projects/{projectId}/instances/"
    + $"{instanceId}/databases/{databaseId}";
string createStatement =
    "CREATE INDEX AlbumsByAlbumTitle ON Albums(AlbumTitle)";
// Make the request.
using (var connection = new SpannerConnection(connectionString))
{
    var createCmd = connection.CreateDdlCommand(createStatement);
    await createCmd.ExecuteNonQueryAsync();
}
Console.WriteLine("Added the AlbumsByAlbumTitle index.");

Ejecuta la muestra mediante el comando addIndex.

  dotnet run addIndex $env:GOOGLE_PROJECT_ID test-instance example-db

Agregar un índice puede tardar unos minutos. Después de agregar el índice, deberías ver lo siguiente:

  Added the AlbumsByAlbumTitle index.

Agrega un índice con una cláusula STORING

Quizás notaste que, en el ejemplo de lectura anterior, no se incluye la lectura de la columna MarketingBudget. Esto se debe a que la interfaz de lectura de Cloud Spanner no admite la posibilidad de unir un índice con una tabla de datos para buscar valores que no están almacenados en el índice.

Crea una definición alternativa de AlbumsByAlbumTitle que almacene una copia de MarketingBudget en el índice.

En la línea de comandos

gcloud spanner databases ddl update example-db --instance=test-instance `
    --ddl='CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) STORING (MarketingBudget)'

Agregar un índice puede tardar unos minutos. Después de agregar el índice, deberías ver lo siguiente:

Schema updating...done.

Usa la biblioteca cliente de Cloud Spanner para C#

Usa CreateDdlCommand() para agregar un índice con una cláusula STORING:

// Initialize request argument(s).
string connectionString =
    $"Data Source=projects/{projectId}/instances/"
    + $"{instanceId}/databases/{databaseId}";
string createStatement =
    "CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) "
    + "STORING (MarketingBudget)";
// Make the request.
using (var connection = new SpannerConnection(connectionString))
{
    var createCmd = connection.CreateDdlCommand(createStatement);
    await createCmd.ExecuteNonQueryAsync();
}
Console.WriteLine("Added the AlbumsByAlbumTitle2 index.");

Ejecuta la muestra mediante el comando addStoringIndex.

dotnet run addStoringIndex $env:GOOGLE_PROJECT_ID test-instance example-db

Deberías ver lo siguiente:

Added the AlbumsByAlbumTitle2 index.

Ahora puedes ejecutar una operación de lectura que recupere todas las columnas AlbumId, AlbumTitle y MarketingBudget del índice AlbumsByAlbumTitle2:

Para leer los datos con el índice de almacenamiento que creaste, ejecuta una consulta que especifique explícitamente el índice:

string connectionString =
$"Data Source=projects/{projectId}/instances/{instanceId}"
+ $"/databases/{databaseId}";
// Create connection to Cloud Spanner.
using (var connection = new SpannerConnection(connectionString))
{
    var cmd = connection.CreateSelectCommand(
        "SELECT AlbumId, AlbumTitle, MarketingBudget FROM Albums@ "
        + "{FORCE_INDEX=AlbumsByAlbumTitle2} "
        + $"WHERE AlbumTitle >= @startTitle "
        + $"AND AlbumTitle < @endTitle",
        new SpannerParameterCollection {
            {"startTitle", SpannerDbType.String},
            {"endTitle", SpannerDbType.String} });
    cmd.Parameters["startTitle"].Value = startTitle;
    cmd.Parameters["endTitle"].Value = endTitle;
    using (var reader = await cmd.ExecuteReaderAsync())
    {
        while (await reader.ReadAsync())
        {
            Console.WriteLine("AlbumId : "
            + reader.GetFieldValue<string>("AlbumId")
            + " AlbumTitle : "
            + reader.GetFieldValue<string>("AlbumTitle")
            + " MarketingBudget : "
            + reader.GetFieldValue<string>("MarketingBudget"));
        }
    }
}

Ejecuta la muestra mediante el comando queryDataWithStoringIndex.

dotnet run queryDataWithStoringIndex $env:GOOGLE_PROJECT_ID test-instance example-db

Deberías ver un resultado similar a este:

AlbumId : 2 AlbumTitle : Forever Hold your Peace MarketingBudget : 300000
AlbumId : 2 AlbumTitle : Go, Go, Go MarketingBudget : 300000

Recupera datos mediante transacciones de solo lectura

Supongamos que quieres ejecutar más de una lectura en la misma marca de tiempo. En las transacciones de solo lectura, se observa un prefijo coherente del historial de confirmaciones de transacciones, por lo que la aplicación siempre obtiene datos coherentes. Usa TransactionScope() de .NET framework junto con OpenAsReadOnlyAsync() para ejecutar transacciones de solo lectura.

A continuación, se muestra cómo ejecutar una consulta y realizar una operación de lectura en la misma transacción de solo lectura:

.NET Standard 2.0

string connectionString =
$"Data Source=projects/{projectId}/instances/{instanceId}"
+ $"/databases/{databaseId}";
// Gets a transaction object that captures the database state
// at a specific point in time.
using (TransactionScope scope = new TransactionScope(
    TransactionScopeAsyncFlowOption.Enabled))
{
    // Create connection to Cloud Spanner.
    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()
            .ConfigureAwait(false);
        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())
            {
                Console.WriteLine("SingerId : "
                    + reader.GetFieldValue<string>("SingerId")
                    + " AlbumId : "
                    + reader.GetFieldValue<string>("AlbumId")
                    + " AlbumTitle : "
                    + reader.GetFieldValue<string>("AlbumTitle"));
            }
        }
    }
    scope.Complete();
    Console.WriteLine("Transaction complete.");
}

.NET Standard 1.5

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

// Create connection to Cloud Spanner.
using (var connection = new SpannerConnection(connectionString))
{
    await connection.OpenAsync();

    // Open a new read only transaction.
    using (var transaction =
        await connection.BeginReadOnlyTransactionAsync())
    {
        var cmd = connection.CreateSelectCommand(
            "SELECT SingerId, AlbumId, AlbumTitle FROM Albums");
        cmd.Transaction = transaction;

        // 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())
            {
                Console.WriteLine("SingerId : "
                    + reader.GetFieldValue<string>("SingerId")
                    + " AlbumId : "
                    + reader.GetFieldValue<string>("AlbumId")
                    + " AlbumTitle : "
                    + reader.GetFieldValue<string>("AlbumTitle"));
            }
        }
    }
}
Console.WriteLine("Transaction complete.");

Ejecuta la muestra mediante el comando queryDataWithTransaction.

dotnet run queryDataWithTransaction $env:GOOGLE_PROJECT_ID test-instance example-db

Deberías ver un resultado similar a este:

SingerId : 2 AlbumId : 2 AlbumTitle : Forever Hold your Peace
SingerId : 1 AlbumId : 2 AlbumTitle : Go, Go, Go
SingerId : 2 AlbumId : 1 AlbumTitle : Green
SingerId : 2 AlbumId : 3 AlbumTitle : Terrified
SingerId : 1 AlbumId : 1 AlbumTitle : Total Junk
SingerId : 2 AlbumId : 2 AlbumTitle : Forever Hold your Peace
SingerId : 1 AlbumId : 2 AlbumTitle : Go, Go, Go
SingerId : 2 AlbumId : 1 AlbumTitle : Green
SingerId : 2 AlbumId : 3 AlbumTitle : Terrified
SingerId : 1 AlbumId : 1 AlbumTitle : Total Junk

Realiza una limpieza

Para evitar que se apliquen cargos adicionales a tu cuenta de Google Cloud por los recursos que se usaron en este instructivo, descarta la base de datos y borra la instancia que creaste.

Borra la base de datos

Si borras una instancia, se borrarán de forma automática todas las bases de datos que contiene. En este paso, se muestra cómo borrar una base de datos sin borrar una instancia (ten en cuenta que se seguirán generando cargos por la instancia).

En la línea de comandos

gcloud spanner databases delete example-db --instance=test-instance

Usa Cloud Console.

  1. Ve a la página Instancias de Cloud Spanner en Google Cloud Console.

    Ir a la página Instancias

  2. Haz clic en la instancia.

  3. Haz clic en la base de datos que deseas borrar.

  4. En la página Detalles de la base de datos, haz clic en Borrar.

  5. Confirma que deseas borrar la base de datos y haz clic en Borrar.

Borra la instancia

Si borras una instancia, se descartarán de forma automática todas las bases de datos creadas en ella.

En la línea de comandos

gcloud spanner instances delete test-instance

Usa Cloud Console.

  1. Ve a la página Instancias de Cloud Spanner en Google Cloud Console.

    Ir a la página Instancias

  2. Haz clic en tu instancia.

  3. Haz clic en Borrar.

  4. Confirma que deseas borrar la instancia y haz clic en Borrar.

Próximos pasos

  • Accede a Cloud Spanner en una instancia de máquina virtual: crea una instancia de máquina virtual con acceso a tu base de datos de Cloud Spanner.
  • Obtén más información sobre las credenciales de autorización y autenticación en Cómo comenzar a usar la autenticación.
  • Obtén más información sobre los conceptos de Cloud Spanner.