Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

開始使用 Node.js 中的 Spanner

目標

本教學課程將引導您使用 Node.js 適用的 Spanner 用戶端程式庫，完成下列步驟：

建立 Spanner 執行個體和資料庫。
對資料庫中的資料進行寫入和讀取，以及執行 SQL 查詢。
更新資料庫結構定義。
使用讀取/寫入交易來更新資料。
將次要索引新增至資料庫。
使用索引對資料執行讀取作業和 SQL 查詢。
使用唯讀交易擷取資料。

費用

本教學課程使用 Spanner，這是Google Cloud的計費元件。如要瞭解 Spanner 的使用費用，請參閱「定價」。

事前準備

完成「設定」一節所述的步驟，包括建立及設定預設 Google Cloud 專案、啟用計費功能、啟用 Cloud Spanner API，以及設定 OAuth 2.0，以取得使用 Cloud Spanner API 的驗證憑證。

請務必執行 gcloud auth application-default login，使用驗證憑證設定本機開發環境。

準備本機 Node.js 環境

按照步驟設定 Node.js 開發環境
將範例應用程式存放區複製到您的本機電腦：
```
git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git
```
您也可以透過 zip 檔案的格式下載範例，然後再解壓縮該檔案。
變更為包含 Spanner 程式碼範例的目錄：
```
cd nodejs-docs-samples/spanner/
```
使用 npm 安裝依附元件：
```
npm install
```

建立執行個體

首次使用 Spanner 時，必須建立執行個體，也就是 Spanner 資料庫所用的資源分配單位。建立執行個體時，請選擇「執行個體設定」以決定資料儲存的位置，再選擇要使用的節點數量以決定執行個體的服務和儲存空間資源量。

請參閱「建立執行個體」，瞭解如何使用下列任一方法建立 Spanner 執行個體。您可以將執行個體命名為 test-instance，以便與本文件中參照名為 test-instance 的執行個體的其他主題搭配使用。

Google Cloud CLI
Google Cloud 控制台
用戶端程式庫 (C++、C#、Go、Java、Node.js、PHP、Python、Ruby 或 Rust)

瀏覽範例檔案

範例存放區包含一個範例，說明如何搭配使用 Spanner 和 Node.js。

請查看 samples/schema.js 檔案，瞭解如何建立資料庫及修改資料庫結構定義。資料會使用「結構定義與資料模型」頁面中顯示的範例結構定義。

建立資料庫

GoogleSQL

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

PostgreSQL

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

如下所示：

Created database example-db on instance test-instance.

下列程式碼會建立資料庫，並在資料庫中建立兩個資料表。

GoogleSQL


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

PostgreSQL

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

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

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

const databaseAdminClient = spanner.getDatabaseAdminClient();

async function createPgDatabase() {
  // Creates a PostgreSQL database. PostgreSQL create requests may not contain any additional
  // DDL statements. We need to execute these separately after the database has been created.
  const [operationCreate] = await databaseAdminClient.createDatabase({
    createStatement: 'CREATE DATABASE "' + databaseId + '"',
    parent: databaseAdminClient.instancePath(projectId, instanceId),
    databaseDialect:
      protos.google.spanner.admin.database.v1.DatabaseDialect.POSTGRESQL,
  });

  console.log(`Waiting for operation on ${databaseId} to complete...`);
  await operationCreate.promise();
  const [metadata] = await databaseAdminClient.getDatabase({
    name: databaseAdminClient.databasePath(projectId, instanceId, databaseId),
  });
  console.log(
    `Created database ${databaseId} on instance ${instanceId} with dialect ${metadata.databaseDialect}.`,
  );

  // Create a couple of tables using a separate request. We must use PostgreSQL style DDL as the
  // database has been created with the PostgreSQL dialect.
  const statements = [
    `CREATE TABLE Singers 
      (SingerId   bigint NOT NULL,
      FirstName   varchar(1024),
      LastName    varchar(1024),
      SingerInfo  bytea,
      FullName    character varying(2048) GENERATED ALWAYS AS (FirstName || ' ' || LastName) STORED,
      PRIMARY KEY (SingerId)
      );
      CREATE TABLE Albums 
      (AlbumId    bigint NOT NULL,
      SingerId    bigint NOT NULL REFERENCES Singers (SingerId),
      AlbumTitle  text,
      PRIMARY KEY (AlbumId)
      );`,
  ];
  const [operationUpdateDDL] = await databaseAdminClient.updateDatabaseDdl({
    database: databaseAdminClient.databasePath(
      projectId,
      instanceId,
      databaseId,
    ),
    statements: [statements],
  });
  await operationUpdateDDL.promise();
  console.log('Updated schema');
}
createPgDatabase();

下一個步驟是將資料寫入資料庫。

建立資料庫用戶端

您必須先建立 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));

您可以將 Database 視為資料庫連線：您與 Spanner 的所有互動都必須透過 Database 進行。一般來說，您會在應用程式啟動時建立 Database，然後重複使用該 Database 來讀取、寫入及執行交易。每個用戶端都會使用 Spanner 中的資源。

如果您在同一個應用程式中建立多個用戶端，請在不再需要用戶端時，立即呼叫 Database.close() 清理用戶端的資源，包括網路連線。

詳情請參閱 Database 參考資料。

使用 DML 寫入資料

您可以在讀寫交易中使用 data manipulation language (DML) 插入資料。

您可以使用 runUpdate() 方法執行 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();
  }
});

使用 writeUsingDml 引數執行範例。

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

如下所示：

4 records inserted.

使用變異寫入資料

您也可以使用變異來插入資料。

您可以使用 Table 物件寫入資料。Table.insert() 方法會在資料表中新增資料列。系統會以不可分割的形式套用單一批次中的所有插入資料。

此程式碼顯示如何使用變異寫入資料：

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

使用 insert 引數執行範例。

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

如下所示：

Inserted data.

使用 SQL 查詢資料

Spanner 支援讀取資料的 SQL 介面，您可以使用 Google Cloud CLI 在指令列存取，或使用 Node.js 適用的 Spanner 用戶端程式庫，以程式輔助方式存取。

使用指令列

執行下列 SQL 陳述式，讀取 Albums 資料表中所有資料欄的值：

GoogleSQL

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

GoogleSQL 管道語法

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

結果顯示：

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

使用 Node.js 專用的 Spanner 用戶端程式庫

除了在指令列執行 SQL 陳述式，您也可以使用 Node.js 適用的 Spanner 用戶端程式庫，以程式輔助方式發出相同的 SQL 陳述式。

使用 Database.run() 執行 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();
}

下面說明如何發出查詢和存取資料：

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

畫面上應會顯示下列結果：

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

使用 SQL 參數查詢

如果應用程式經常執行某個查詢，您可以將其參數化，以提升效能。產生的參數化查詢可以快取並重複使用，進而降低編譯成本。詳情請參閱「使用查詢參數加快頻繁執行的查詢」。

以下範例說明如何在 WHERE 子句中使用參數，查詢包含特定 LastName 值的記錄。

GoogleSQL

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

PostgreSQL

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

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

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

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

  const fieldType = {
    type: 'string',
  };

  const query = {
    sql: `SELECT singerid, firstname, lastname
          FROM singers
          WHERE firstname LIKE $1`,
    params: {
      p1: 'A%',
    },
    types: {
      p1: fieldType,
    },
  };

  // Queries rows from the Singers 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();
  }
}
queryWithPgParameter();

下面說明如何發出查詢和存取資料：

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

畫面會顯示以下結果：

SingerId: 12, FirstName: Melissa, LastName: Garcia

使用讀取 API 讀取資料

除了 Spanner 的 SQL 介面外，Spanner 也支援讀取介面。

使用 Table.read() 讀取資料庫中的資料列。使用 KeySet 物件定義要讀取的索引鍵和索引鍵範圍集合。

下列內容將示範如何讀取資料：

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

使用 read 引數執行範例。

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

畫面會顯示類似以下的輸出：

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

更新資料庫結構定義

假設您需要在 Albums 資料表中新增名為 MarketingBudget 的資料欄。必須先更新資料庫結構定義，才能新增新資料欄到現有的資料表。Spanner 可支援更新資料庫結構定義，同時讓資料庫持續處理流量。結構定義更新作業不需要讓資料庫離線，也不會鎖定整個資料表或資料欄；您可以在結構定義更新期間，持續將資料寫入資料庫。如要進一步瞭解支援的結構定義更新和結構定義變更效能，請參閱「更新結構定義」。

新增資料欄

您可以使用 Google Cloud CLI 在指令列中新增資料欄，或使用 Node.js 適用的 Spanner 用戶端程式庫，以程式輔助方式新增資料欄。

使用指令列

使用下列 ALTER TABLE 指令，將新資料欄新增至資料表：

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'

如下所示：

Schema updating...done.

使用 Node.js 專用的 Spanner 用戶端程式庫

使用 Database.updateSchema 修改結構定義：

GoogleSQL


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

PostgreSQL

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

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

async function pgAddColumn() {
  const request = ['ALTER TABLE Albums ADD COLUMN MarketingBudget BIGINT'];

  // Alter existing table to add a column.
  const [operation] = await databaseAdminClient.updateDatabaseDdl({
    database: databaseAdminClient.databasePath(
      projectId,
      instanceId,
      databaseId,
    ),
    statements: request,
  });

  console.log(`Waiting for operation on ${databaseId} to complete...`);

  await operation.promise();

  console.log(
    `Added MarketingBudget column to Albums table in database ${databaseId}.`,
  );
}
pgAddColumn();

使用 addColumn 引數執行範例。

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

如下所示：

Added the MarketingBudget column.

寫入資料到新資料欄

以下程式碼會將資料寫入新資料欄，這會將索引鍵為 Albums(1, 1) 的資料列 MarketingBudget 設為 100000，並將索引鍵為 Albums(2, 2) 的資料列設為 500000。

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

使用 update 引數執行範例。

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

如下所示：

Updated data.

您也可以執行 SQL 查詢或讀取呼叫，以擷取剛寫入的值。

以下是執行查詢的程式碼：

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

如要執行這項查詢，請使用 queryNewColumn 引數執行範例。

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

如下所示：

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

更新資料

您可以在讀寫交易中使用 DML 來更新資料。

您可以使用 runUpdate() 方法執行 DML 陳述式。

GoogleSQL

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

PostgreSQL

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

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

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

function updateUsingDml() {
  // 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: 'UPDATE singers SET FirstName = $1 WHERE singerid = 1',
        params: {
          p1: 'Virginia',
        },
      });

      console.log(
        `Successfully updated ${rowCount} record in the Singers table.`,
      );

      await transaction.commit();
    } catch (err) {
      console.error('ERROR:', err);
    } finally {
      // Close the database when finished.
      await database.close();
    }
  });
}
updateUsingDml();

使用 writeWithTransactionUsingDml 引數執行範例。

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

如下所示：

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

使用次要索引

假設您要擷取 AlbumTitle 值在特定範圍內的所有 Albums 資料列，您可以先使用 SQL 陳述式或讀取呼叫，來讀取 AlbumTitle 資料欄的所有值，然後捨棄條件不符的資料列。不過，掃描完整資料表的費用高昂，資料表內含大量資料列時更是如此。因此您可以改為在資料表建立次要索引，這樣將非主鍵資料欄做為搜尋條件時，就能加快資料列的擷取速度。

您必須先更新結構定義，才能在現有資料表新增次要索引。如同其他結構定義更新作業，Spanner 可支援新增索引，同時讓資料庫持續處理流量。Spanner 會自動使用現有資料補充索引。補充作業可能需要幾分鐘才能完成，在這個過程中，您不需將資料庫設為離線，可照常執行索引資料表的寫入作業。詳情請參閱「新增次要索引」。

新增次要索引後，Spanner 會自動將其用於可能透過索引加快執行速度的 SQL 查詢。如果使用讀取介面，則必須指定要使用的索引。

新增次要索引

您可以使用 gcloud CLI 在指令列中新增索引，或使用 Node.js 適用的 Spanner 用戶端程式庫，以程式輔助方式新增索引。

使用指令列

使用下列 CREATE INDEX 指令，將索引新增至資料庫：

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

如下所示：

Schema updating...done.

使用 Node.js 適用的 Spanner 用戶端程式庫

使用 Database.updateSchema() 新增索引：

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

使用 createIndex 引數執行範例。

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

索引可能需要幾分鐘才能新增完成。之後畫面上會顯示以下訊息：

Added the AlbumsByAlbumTitle index.

使用索引進行讀取

Spanner 會自動為 SQL 查詢使用適當的索引。在讀取介面中，您必須在要求中指定索引。

如要在讀取介面中使用索引，請使用 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();
}

使用 readIndex 引數執行範例。

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

如下所示：

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

新增索引，以便執行僅限索引讀取作業

您可能已注意到，先前的讀取範例不包含讀取 MarketingBudget 欄。這是因為 Spanner 的讀取介面不支援透過 join 索引與資料表，再查詢未儲存於索引中的值。

建立 AlbumsByAlbumTitle 的替代定義，將 MarketingBudget 的副本儲存在索引中。

使用指令列

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)

索引可能需要幾分鐘才能新增完成。之後畫面上會顯示以下訊息：

Schema updating...done.

使用 Node.js 適用的 Spanner 用戶端程式庫

使用 Database.updateSchema() 新增含有 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();
}

使用 createStoringIndex 引數執行範例。

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

如下所示：

Added the AlbumsByAlbumTitle2 index.

現在您可以執行讀取作業，從 AlbumsByAlbumTitle2 索引擷取所有 AlbumId、AlbumTitle 和 MarketingBudget 欄：

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

使用 readStoringIndex 引數執行範例。

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

畫面會顯示類似以下的輸出：

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

使用唯讀交易擷取資料

假設您想要在相同時間戳記執行一次以上的讀取作業。唯讀交易會觀察交易修訂版本記錄的一致前置字串，因此應用程式一律會取得一致的資料。使用 Database.runTransaction() 執行唯讀交易。

以下顯示如何執行查詢，並在同一個唯讀交易中執行讀取作業：

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

使用 readOnly 引數執行範例。

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

畫面會顯示類似以下的輸出：

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.

清除所用資源

為避免系統向您的 Cloud Billing 帳戶收取本教學課程所用資源的額外費用，請捨棄資料庫並刪除您建立的執行個體。

刪除資料庫

如果刪除執行個體，其中的所有資料庫都會自動刪除。這個步驟說明如何在不刪除執行個體的情況下刪除資料庫 (您仍須支付執行個體費用)。

使用指令列

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

使用 Google Cloud 控制台

前往 Google Cloud 控制台的「Spanner Instances」(Spanner 執行個體) 頁面。

前往「Instances」(執行個體) 頁面
點選執行個體。
點選您要刪除的資料庫。
在「Database details」(資料庫詳細資料) 頁面，按一下 [Delete] (刪除)。
確認您要刪除資料庫，然後按一下 [Delete] (刪除)。

刪除執行個體

您刪除執行個體時，也會自動捨棄您在其中建立的所有資料庫。

使用指令列

gcloud spanner instances delete test-instance

使用 Google Cloud 控制台

前往 Google Cloud 控制台的「Spanner Instances」(Spanner 執行個體) 頁面。

前往「Instances」(執行個體) 頁面
點選執行個體。
按一下 [Delete] (刪除)。
確認您要刪除執行個體，然後按一下 [Delete] (刪除)。

後續步驟

瞭解如何透過虛擬機器執行個體存取 Spanner。
如要瞭解授權和驗證憑證，請參閱「使用用戶端程式庫向 Cloud 服務進行驗證」。
進一步瞭解 Spanner 結構定義設計最佳做法。

開始使用 Node.js 中的 Spanner 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

目標

費用

事前準備

準備本機 Node.js 環境

建立執行個體

瀏覽範例檔案

建立資料庫

GoogleSQL

PostgreSQL

GoogleSQL

PostgreSQL

建立資料庫用戶端

使用 DML 寫入資料

使用變異寫入資料

使用 SQL 查詢資料

使用指令列

GoogleSQL

GoogleSQL 管道語法

使用 Node.js 專用的 Spanner 用戶端程式庫

使用 SQL 參數查詢

GoogleSQL

PostgreSQL

使用讀取 API 讀取資料

更新資料庫結構定義

新增資料欄

使用指令列

GoogleSQL

PostgreSQL

使用 Node.js 專用的 Spanner 用戶端程式庫

GoogleSQL

PostgreSQL

寫入資料到新資料欄

更新資料

GoogleSQL

PostgreSQL

使用次要索引

新增次要索引

使用指令列

使用 Node.js 適用的 Spanner 用戶端程式庫

使用索引進行讀取

新增索引，以便執行僅限索引讀取作業

使用指令列

GoogleSQL

PostgreSQL

使用 Node.js 適用的 Spanner 用戶端程式庫

使用唯讀交易擷取資料

清除所用資源

刪除資料庫

使用指令列

使用 Google Cloud 控制台

刪除執行個體

使用指令列

使用 Google Cloud 控制台

後續步驟

開始使用 Node.js 中的 Spanner