Cloud Spanner Client Library for Node.js

The nodejs-spanner samples repository provides a comprehensive collection of code examples for interacting with Cloud Spanner using the Node.js client library. These samples cover a wide range of operations including:

• Backup Management: Creating, deleting, restoring, and canceling backups, including support for KMS encryption keys.
• Database Administration: Managing database roles, creating/updating databases, and configuring default leaders.
• Schema Management: Creating and altering tables, indexes, sequences, and foreign keys (including cascade actions) for both GoogleSQL and PostgreSQL dialects.
• Data Manipulation: Performing DML (Insert, Update, Delete) with RETURNING clauses, batch writes, and working with specialized types like JSON, JSONB, and Protobuf.
• Querying: Executing SQL queries, using parameters, directed reads, and utilizing indexes.
• Transactions: Implementing read-write transactions with various isolation levels, lock modes, and timeouts.
• Instance Management: Configuring instances, autoscaling, and managing instance configurations.
• Observability: Implementing tracing with OpenTelemetry and OTLP.
• PostgreSQL Dialect: Specific samples for Spanner's PostgreSQL interface, including sequence management and dialect-specific syntax.

Cloud Spanner supports two session modes. The Node.js client enables Multiplexed Sessions by default to reduce session management overhead and minimize errors.

Multiplexed Sessions

This is the default mode. It is designed to be more efficient for session management.

Regular Sessions

To use regular sessions instead of the default multiplexed mode, you must disable multiplexed sessions using specific environment variables. Depending on your transaction type, set the following to false:

To get started with the Cloud Spanner Node.js client, follow these steps:

1. Before you begin

• Select or create a Google Cloud Platform project.
• Enable billing for your project.
• Enable the Cloud Spanner API.
• Set up authentication to access the API from your local workstation.

2. Install the client library

Install the @google-cloud/spanner package using npm:

npm install @google-cloud/spanner

3. Use the client library

Initialize the Spanner client, reference an instance and database, and execute a query using database.run().

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

The nodejs-docs-samples-spanner repository contains a wide variety of code samples demonstrating how to use the @google-cloud/spanner client library. These samples cover advanced features including:

• Data Types: Working with proto columns, enum types, timestamp, struct, and sequence operations (create, alter, drop).
• Transactions: Performing read-write transactions with specific read-lock-mode, isolation level (e.g., repeatable reads), statement timeout, transaction timeout, and the use of transaction tags.
• Querying & Performance: Using queryoptions, setting request tags for single queries, and managing RPC priority for reads, queries, batch DML, and partitioned DML.
• Schema Management: Creating and altering tables with foreign key delete cascade actions, and managing database schemas.
• Administrative Tasks: Updating instance configurations (like default backup schedules) and backup schedules.
• Security: Reading data using specific database roles.

You can find the source code for each sample in the samples/ directory of the repository.

To populate your Spanner database for benchmarking, follow these steps:

1. Configure Environment Variables: Set GOOGLE_APPLICATION_CREDENTIALS to your service account JSON key path and GCLOUD_PROJECT to your Google Cloud project ID.
2. Download YCSB Binding: Download the custom YCSB Cloud Spanner binding release.
3. Execute Load: Use the ycsb load cloudspanner command. You must provide a workload file (-P), the target table (-p table=...), the Spanner instance and database names, and the desired recordcount and operationcount.

$ export GOOGLE_APPLICATION_CREDENTIALS=/path/to/your/credentials.json
$ export GCLOUD_PROJECT=your-project-id

$ curl https://storage.googleapis.com/cloud-spanner-ycsb-custom-release/ycsb-cloudspanner-binding-0.13.0.tar.gz | tar -xzv
$ ycsb-cloudspanner-binding-0.13.0/bin/ycsb load cloudspanner \
  -P ycsb-cloudspanner-binding-0.13.0/workloads/workloada \
  -p table=usertable -p cloudspanner.instance=ycsb-instance \
  -p recordcount=5000 -p operationcount=100 -p cloudspanner.database=ycsb \
  -threads 32

The client library supports various Data Manipulation Language (DML) operations for Spanner databases using the PostgreSQL dialect. Key capabilities include:

• Basic Updates: Updating data in existing tables.
• Parameterized DML: Executing DML statements with parameters for security and performance.
• DML with RETURNING: Using the RETURNING clause during INSERT, UPDATE, or DELETE operations to retrieve modified rows.
• Batch DML: Executing a batch of DML statements.
• Partitioned DML: Executing partitioned DML for large-scale data modifications.

Refer to the specific samples for implementation details.

// Examples available in:
// samples/pg-dml-getting-started-update.js
// samples/pg-dml-with-parameter.js
// samples/pg-dml-returning-insert.js
// samples/pg-dml-returning-update.js
// samples/pg-dml-returning-delete.js
// samples/pg-dml-batch.js
// samples/pg-dml-partitioned.js