Comienza a usar Spanner en Node.js

---

Nota de la interfaz de PostgreSQL: Los ejemplos de este tema están destinados a bases de datos de dialecto GoogleSQL.

Objetivos

En este instructivo, se explican los siguientes pasos para usar Spanner biblioteca cliente para Node.js:

• Crear una instancia y una base de datos de 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 Spanner, que es un componente facturable del en Google Cloud. Para obtener información sobre el costo de usar 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.

Nota: Si no planeas conservar los recursos que creaste en este instructivo, considera crear un proyecto nuevo de Google Cloud en lugar de seleccionar uno existente. Cuando termines el instructivo, puedes borrar el proyecto y quitar todos los recursos asociados con él.

Prepara el entorno local de Node.js

1. Sigue los pasos de la página sobre cómo configurar un entorno de desarrollo de Node.js.

2. Clona el repositorio de la app de muestra en tu máquina local:

   git clone https://github.com/googleapis/nodejs-spanner
   

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

3. Ve al directorio que contiene el código de muestra de Spanner:

   cd samples/
   

4. Instala dependencias con npm:

   npm install
   

Crea una instancia

Cuando usas Spanner por primera vez, debes crear una instancia, que es una asignación de recursos que usan las bases de datos de 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 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; Para obtener más información, consulta Acerca de las 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 Nodos y unidades de procesamiento de datos).

Deberías ver lo siguiente:

Creating instance...done.

Examina archivos de muestra

El repositorio de muestras contiene una muestra en la que se indica cómo usar Spanner con Node.js.

Consulta el archivo samples/schema.js, que muestra cómo crear una base de datos y modificar un esquema de base de datos. Los datos usan 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:

node schema.js createDatabase test-instance example-db MY_PROJECT_ID

Deberías ver lo siguiente:

Created database example-db on instance test-instance.

El siguiente código crea una base de datos y dos tablas en la base de datos.

Nota: En las muestras de código posteriores, se usan estas dos tablas. Si no realizas este código y, luego, crear las tablas con la consola de Google Cloud o gcloud CLI. Para obtener más información, consulta el esquema de ejemplo.

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

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

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

const databaseAdminClient = spanner.getDatabaseAdminClient();

const createSingersTableStatement = `
CREATE TABLE Singers (
  SingerId    INT64 NOT NULL,
  FirstName   STRING(1024),
  LastName    STRING(1024),
  SingerInfo  BYTES(MAX),
  FullName    STRING(2048) AS (ARRAY_TO_STRING([FirstName, LastName], " ")) STORED,
) PRIMARY KEY (SingerId)`;
const createAlbumsTableStatement = `
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`;

// Creates a new database
try {
  const [operation] = await databaseAdminClient.createDatabase({
    createStatement: 'CREATE DATABASE `' + databaseID + '`',
    extraStatements: [
      createSingersTableStatement,
      createAlbumsTableStatement,
    ],
    parent: databaseAdminClient.instancePath(projectID, instanceID),
  });

  console.log(`Waiting for creation of ${databaseID} to complete...`);
  await operation.promise();

  console.log(`Created database ${databaseID} on instance ${instanceID}.`);
} catch (err) {
  console.error('ERROR:', err);
}

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 Database:

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

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

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

// The query to execute
const query = {
  sql: 'SELECT 1',
};

// Execute a simple SQL statement
const [rows] = await database.run(query);
console.log(`Query: ${rows.length} found.`);
rows.forEach(row => console.log(row));

Un Database es como una conexión de base de datos: todas tus interacciones con Spanner deben pasar por un Database. Normalmente, cuando se inicia la aplicación, se crea un Database y se vuelve a usar ese Database para leer, escribir y ejecutar transacciones. Cada cliente usa recursos en Spanner.

Si creas varios clientes en la misma app, debes llamar a Database.close() para limpiar los recursos del cliente, incluidas las conexiones de red, cuando ya no sea necesario.

Obtén más información en la referencia de Database.

Escribe datos con DML

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

Usa el método runUpdate() para ejecutar una declaración DML.

// 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);

database.runTransaction(async (err, transaction) => {
  if (err) {
    console.error(err);
    return;
  }
  try {
    const [rowCount] = await transaction.runUpdate({
      sql: `INSERT Singers (SingerId, FirstName, LastName) VALUES
      (12, 'Melissa', 'Garcia'),
      (13, 'Russell', 'Morales'),
      (14, 'Jacqueline', 'Long'),
      (15, 'Dylan', 'Shaw')`,
    });
    console.log(`${rowCount} records inserted.`);
    await transaction.commit();
  } catch (err) {
    console.error('ERROR:', err);
  } finally {
    // Close the database when finished.
    database.close();
  }
});

Ejecuta la muestra con el argumento writeUsingDml.

node dml.js writeUsingDml test-instance example-db MY_PROJECT_ID

Deberías ver lo siguiente:

4 records inserted.

Nota: Existen límites para confirmar el tamaño. Consulta el límite de CRUD para obtener más información.

Escribe datos con mutaciones

También puedes insertar datos mediante mutaciones.

Escribe datos con un objeto Table. El método Table.insert() agrega filas nuevas a la tabla. Todas las inserciones en un solo lote se aplican de forma atómica.

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

// 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);

// Instantiate Spanner table objects
const singersTable = database.table('Singers');
const albumsTable = database.table('Albums');

// Inserts rows into the Singers table
// Note: Cloud Spanner interprets Node.js numbers as FLOAT64s, so
// they must be converted to strings before being inserted as INT64s
try {
  await singersTable.insert([
    {SingerId: '1', FirstName: 'Marc', LastName: 'Richards'},
    {SingerId: '2', FirstName: 'Catalina', LastName: 'Smith'},
    {SingerId: '3', FirstName: 'Alice', LastName: 'Trentor'},
    {SingerId: '4', FirstName: 'Lea', LastName: 'Martin'},
    {SingerId: '5', FirstName: 'David', LastName: 'Lomond'},
  ]);

  await albumsTable.insert([
    {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'},
  ]);

  console.log('Inserted data.');
} catch (err) {
  console.error('ERROR:', err);
} finally {
  await database.close();
}

Ejecuta la muestra con el argumento insert.

node crud.js insert test-instance example-db MY_PROJECT_ID

Deberías ver lo siguiente:

Inserted data.

Nota: Existen límites para confirmar el tamaño. Consulta el límite de CRUD. para obtener más información.

Consulta datos mediante SQL

Spanner admite una interfaz de SQL para leer datos, a la que puedes acceder desde la línea de comandos mediante Google Cloud CLI o de manera programática con la biblioteca cliente de Spanner para Node.js.

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'

Nota: Para obtener la referencia de GoogleSQL, visita Sintaxis de consultas en GoogleSQL y, como referencia de PostgreSQL, consulta Estructura léxica y sintaxis de PostgreSQL.

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 Spanner para Node.js

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 Spanner para Node.js.

Usa Database.run() para ejecutar la consulta de SQL.

// 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 query = {
  sql: 'SELECT SingerId, AlbumId, AlbumTitle FROM Albums',
};

// Queries rows from the Albums table
try {
  const [rows] = await database.run(query);

  rows.forEach(row => {
    const json = row.toJSON();
    console.log(
      `SingerId: ${json.SingerId}, AlbumId: ${json.AlbumId}, AlbumTitle: ${json.AlbumTitle}`
    );
  });
} catch (err) {
  console.error('ERROR:', err);
} finally {
  // Close the database when finished.
  await database.close();
}

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

node crud.js query test-instance example-db MY_PROJECT_ID

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

Consulta mediante un parámetro de SQL

Si tu aplicación tiene una consulta que se ejecuta con frecuencia, puedes mejorar su rendimiento parametrizándola. La consulta paramétrica resultante se puede almacenar en caché y volver a usar, lo que reduce los costos de compilación. Para obtener más información, consulta Usa parámetros de consulta para agilizar las consultas que se ejecutan con frecuencia.

Este es un ejemplo del uso de un parámetro en la cláusula WHERE para consultar registros que contienen un valor específico de LastName.

// 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 query = {
  sql: `SELECT SingerId, FirstName, LastName
        FROM Singers WHERE LastName = @lastName`,
  params: {
    lastName: 'Garcia',
  },
};

// Queries rows from the Albums table
try {
  const [rows] = await database.run(query);

  rows.forEach(row => {
    const json = row.toJSON();
    console.log(
      `SingerId: ${json.SingerId}, FirstName: ${json.FirstName}, LastName: ${json.LastName}`
    );
  });
} catch (err) {
  console.error('ERROR:', err);
} finally {
  // Close the database when finished.
  database.close();
}

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

node dml.js queryWithParameter test-instance example-db MY_PROJECT_ID

Deberías ver el siguiente resultado:

SingerId: 12, FirstName: Melissa, LastName: Garcia

Lee datos con la API de lectura

Además de la interfaz de SQL de Spanner, Spanner también admite un de lectura.

Usa Table.read() para leer filas de la base de datos. Usa un objeto KeySet para definir una colección de claves y rangos de claves que se leerán.

Aquí te indicamos cómo leer los datos:

// 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);

// Reads rows from the Albums table
const albumsTable = database.table('Albums');

const query = {
  columns: ['SingerId', 'AlbumId', 'AlbumTitle'],
  keySet: {
    all: true,
  },
};

try {
  const [rows] = await albumsTable.read(query);

  rows.forEach(row => {
    const json = row.toJSON();
    console.log(
      `SingerId: ${json.SingerId}, AlbumId: ${json.AlbumId}, AlbumTitle: ${json.AlbumTitle}`
    );
  });
} catch (err) {
  console.error('ERROR:', err);
} finally {
  // Close the database when finished.
  await database.close();
}

Ejecuta la muestra con el argumento read.

node crud.js read test-instance example-db MY_PROJECT_ID

Deberías ver un resultado similar a este:

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

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. Spanner admite actualizaciones del esquema de una base de datos mientras esta sigue entregando tráfico. Las actualizaciones de esquema no requieren la base de datos sin conexión y no bloquean tablas ni columnas enteras; puedes continuar la escritura de 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 Cómo realizar actualizaciones de esquema.

Agrega una columna

Puedes agregar una columna en la línea de comandos con Google Cloud CLI o programáticamente con la biblioteca cliente de Spanner para Node.js.

En la línea de comandos

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

GoogleSQL

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

PostgreSQL

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

Deberías ver lo siguiente:

Schema updating...done.

Usa la biblioteca cliente de Spanner para Node.js

Usa Database.updateSchema para modificar el esquema:

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

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

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

const databaseAdminClient = spanner.getDatabaseAdminClient();

// Creates a new index in the database
try {
  const [operation] = await databaseAdminClient.updateDatabaseDdl({
    database: databaseAdminClient.databasePath(
      projectId,
      instanceId,
      databaseId
    ),
    statements: ['ALTER TABLE Albums ADD COLUMN MarketingBudget INT64'],
  });

  console.log('Waiting for operation to complete...');
  await operation.promise();

  console.log('Added the MarketingBudget column.');
} catch (err) {
  console.error('ERROR:', err);
} finally {
  // Close the spanner client when finished.
  // The databaseAdminClient does not require explicit closure. The closure of the Spanner client will automatically close the databaseAdminClient.
  spanner.close();
}

Ejecuta la muestra con el argumento addColumn.

node schema.js addColumn test-instance example-db MY_PROJECT_ID

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. Establece MarketingBudget en 100000 para la fila marcada por Albums(1, 1) y en 500000 para la fila marcada por Albums(2, 2).

// 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);

// Update a row in the Albums table
// Note: Cloud Spanner interprets Node.js numbers as FLOAT64s, so they
// must be converted to strings before being inserted as INT64s
const albumsTable = database.table('Albums');

try {
  await albumsTable.update([
    {SingerId: '1', AlbumId: '1', MarketingBudget: '100000'},
    {SingerId: '2', AlbumId: '2', MarketingBudget: '500000'},
  ]);
  console.log('Updated data.');
} catch (err) {
  console.error('ERROR:', err);
} finally {
  // Close the database when finished.
  database.close();
}

Ejecuta la muestra con el argumento update.

node crud.js update test-instance example-db MY_PROJECT_ID

Deberías ver lo siguiente:

Updated data.

También puedes ejecutar una consulta de SQL o una llamada de lectura para recuperar los valores que acabas de escribir.

Este es el código para ejecutar la consulta:

// This sample uses the `MarketingBudget` column. 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

// 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 query = {
  sql: 'SELECT SingerId, AlbumId, MarketingBudget FROM Albums',
};

// Queries rows from the Albums table
try {
  const [rows] = await database.run(query);

  rows.forEach(async row => {
    const json = row.toJSON();

    console.log(
      `SingerId: ${json.SingerId}, AlbumId: ${
        json.AlbumId
      }, MarketingBudget: ${
        json.MarketingBudget ? json.MarketingBudget : null
      }`
    );
  });
} catch (err) {
  console.error('ERROR:', err);
} finally {
  // Close the database when finished.
  database.close();
}

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

node schema.js queryNewColumn test-instance example-db MY_PROJECT_ID

Debería ver lo siguiente:

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

Actualiza datos

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

Usa el método runUpdate() para ejecutar una declaración DML.

// 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((err, transaction) => {
  if (err) {
    console.error(err);
    return;
  }
  let firstBudget, secondBudget;
  const queryOne = `SELECT MarketingBudget FROM Albums
    WHERE SingerId = 2 AND AlbumId = 2`;

  const queryTwo = `SELECT MarketingBudget FROM Albums
  WHERE SingerId = 1 AND AlbumId = 1`;

  Promise.all([
    // Reads the second album's budget
    transaction.run(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.run(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(() => {
      // Transfers the budgets between the albums
      console.log(firstBudget, secondBudget);
      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.

      return transaction
        .runUpdate({
          sql: `UPDATE Albums SET MarketingBudget = @Budget
              WHERE SingerId = 1 and AlbumId = 1`,
          params: {
            Budget: firstBudget,
          },
        })
        .then(() =>
          transaction.runUpdate({
            sql: `UPDATE Albums SET MarketingBudget = @Budget
                  WHERE SingerId = 2 and AlbumId = 2`,
            params: {
              Budget: secondBudget,
            },
          })
        );
    })
    .then(() => {
      // Commits the transaction and send the changes to the database
      return transaction.commit();
    })
    .then(() => {
      console.log(
        `Successfully executed read-write transaction using DML to transfer ${transferAmount} from Album 2 to Album 1.`
      );
    })
    .then(() => {
      // Closes the database when finished
      database.close();
    });
});

Ejecuta la muestra con el argumento writeWithTransactionUsingDml.

node dml.js writeWithTransactionUsingDml test-instance example-db MY_PROJECT_ID

Deberías ver lo siguiente:

Successfully executed read-write transaction using DML to transfer $200000 from Album 2 to Album 1.

Nota: También puedes actualizar los datos mediante mutaciones.

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. Me gusta otras actualizaciones de esquema, Spanner admite agregar un índice, mientras que base de datos siga entregando tráfico. Spanner reabastece automáticamente el indexar 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 Agrega un índice secundario.

Después de agregar un índice secundario, 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 con la CLI de gcloud o de manera programática con la biblioteca cliente de Spanner para Node.js.

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 Spanner para Node.js

Usa Database.updateSchema() para agregar un índice:

// 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,
});

const databaseAdminClient = spanner.getDatabaseAdminClient();

const request = ['CREATE INDEX AlbumsByAlbumTitle ON Albums(AlbumTitle)'];

// Creates a new index in the database
try {
  const [operation] = await databaseAdminClient.updateDatabaseDdl({
    database: databaseAdminClient.databasePath(
      projectId,
      instanceId,
      databaseId
    ),
    statements: request,
  });

  console.log('Waiting for operation to complete...');
  await operation.promise();

  console.log('Added the AlbumsByAlbumTitle index.');
} catch (err) {
  console.error('ERROR:', err);
} finally {
  // Close the spanner client when finished.
  // The databaseAdminClient does not require explicit closure. The closure of the Spanner client will automatically close the databaseAdminClient.
  spanner.close();
}

Ejecuta la muestra con el argumento createIndex.

node indexing.js createIndex test-instance example-db MY_PROJECT_ID

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

Added the AlbumsByAlbumTitle index.

Leer con el índice

Para las consultas de SQL, Spanner usa automáticamente un índice adecuado. En la interfaz de lectura, debes especificar el índice en tu solicitud.

Para usar el índice en la interfaz de lectura, usa el método Table.read().

// 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 albumsTable = database.table('Albums');

const query = {
  columns: ['AlbumId', 'AlbumTitle'],
  keySet: {
    all: true,
  },
  index: 'AlbumsByAlbumTitle',
};

// Reads the Albums table using an index
try {
  const [rows] = await albumsTable.read(query);

  rows.forEach(row => {
    const json = row.toJSON();
    console.log(`AlbumId: ${json.AlbumId}, AlbumTitle: ${json.AlbumTitle}`);
  });
} catch (err) {
  console.error('ERROR:', err);
} finally {
  // Close the database when finished.
  database.close();
}

Ejecuta la muestra con el argumento readIndex.

node indexing.js readIndex test-instance example-db MY_PROJECT_ID

Deberías ver lo siguiente:

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

Agrega un índice para las operaciones de lectura de solo índice

Quizás hayas notado que el ejemplo de lectura anterior no incluye la lectura la columna MarketingBudget Esto se debe a que la interfaz de lectura de no admite la capacidad de unir un índice con una tabla de datos para buscar valores que no se almacenan 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

GoogleSQL

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

PostgreSQL

gcloud spanner databases ddl update example-db --instance=test-instance \
    --ddl='CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) INCLUDE (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 Spanner para Node.js

Usa Database.updateSchema() para agregar un índice con una cláusula STORING:

// "Storing" indexes store copies of the columns they index
// This speeds up queries, but takes more space compared to normal indexes
// See the link below for more information:
// https://cloud.google.com/spanner/docs/secondary-indexes#storing_clause

// 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,
});

const databaseAdminClient = spanner.getDatabaseAdminClient();

const request = [
  'CREATE INDEX AlbumsByAlbumTitle2 ON Albums(AlbumTitle) STORING (MarketingBudget)',
];

// Creates a new index in the database
try {
  const [operation] = await databaseAdminClient.updateDatabaseDdl({
    database: databaseAdminClient.databasePath(
      projectId,
      instanceId,
      databaseId
    ),
    statements: request,
  });

  console.log('Waiting for operation to complete...');
  await operation.promise();

  console.log('Added the AlbumsByAlbumTitle2 index.');
} catch (err) {
  console.error('ERROR:', err);
} finally {
  // Close the spanner client when finished.
  // The databaseAdminClient does not require explicit closure. The closure of the Spanner client will automatically close the databaseAdminClient.
  spanner.close();
}

Ejecuta la muestra con el argumento createStoringIndex.

node indexing.js createStoringIndex test-instance example-db MY_PROJECT_ID

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:

// "Storing" indexes store copies of the columns they index
// This speeds up queries, but takes more space compared to normal indexes
// See the link below for more information:
// https://cloud.google.com/spanner/docs/secondary-indexes#storing_clause

// 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 albumsTable = database.table('Albums');

const query = {
  columns: ['AlbumId', 'AlbumTitle', 'MarketingBudget'],
  keySet: {
    all: true,
  },
  index: 'AlbumsByAlbumTitle2',
};

// Reads the Albums table using a storing index
try {
  const [rows] = await albumsTable.read(query);

  rows.forEach(row => {
    const json = row.toJSON();
    let rowString = `AlbumId: ${json.AlbumId}`;
    rowString += `, AlbumTitle: ${json.AlbumTitle}`;
    if (json.MarketingBudget) {
      rowString += `, MarketingBudget: ${json.MarketingBudget}`;
    }
    console.log(rowString);
  });
} catch (err) {
  console.error('ERROR:', err);
} finally {
  // Close the database when finished.
  database.close();
}

Ejecuta la muestra con el argumento readStoringIndex.

node indexing.js readStoringIndex test-instance example-db MY_PROJECT_ID

Deberías ver un resultado similar a este:

AlbumId: 2, AlbumTitle: Forever Hold your Peace, MarketingBudget: 300000
AlbumId: 2, AlbumTitle: Go, Go, Go, MarketingBudget: null
AlbumId: 1, AlbumTitle: Green, MarketingBudget: null
AlbumId: 3, AlbumTitle: Terrified, MarketingBudget: null
AlbumId: 1, AlbumTitle: Total Junk, 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 Database.runTransaction() para ejecutar transacciones de solo lectura.

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

// 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();
  }
});

Ejecuta la muestra con el argumento readOnly.

node transaction.js readOnly test-instance example-db MY_PROJECT_ID

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: 1, AlbumId: 2, AlbumTitle: Go, Go, Go
SingerId: 1, AlbumId: 1, AlbumTitle: Total Junk
SingerId: 2, AlbumId: 1, AlbumTitle: Green
SingerId: 2, AlbumId: 2, AlbumTitle: Forever Hold your Peace
SingerId: 2, AlbumId: 3, AlbumTitle: Terrified
Successfully executed read-only transaction.

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 la consola de Google Cloud

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

   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 la consola de Google Cloud

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

   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.

¿Qué sigue?

• Aprende a acceder a Spanner con una instancia de máquina virtual.

• Obtén más información sobre las credenciales de autorización y autenticación en Autenticar en de Google Cloud con bibliotecas cliente.

• Obtén más información sobre las prácticas recomendadas de diseño de esquemas de Spanner.