Google Cloud Platform logo

Cloud Spanner: Node.js Client

release level npm version

Cloud Spanner is a fully managed, mission-critical, relational database service that offers transactional consistency at global scale, schemas, SQL (ANSI 2011 with extensions), and automatic, synchronous replication for high availability.

A comprehensive list of changes in each version may be found in the CHANGELOG.

Read more about the client libraries for Cloud APIs, including the older Google APIs Client Libraries, in Client Libraries Explained.

Table of contents:

Quickstart

Before you begin

  1. Select or create a Cloud Platform project.
  2. Enable billing for your project.
  3. Enable the Cloud Spanner API.
  4. Set up authentication with a service account so you can access the API from your local workstation.

Installing the client library

npm install @google-cloud/spanner

Using the client library

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

Samples

Samples are in the samples/ directory. Each sample's README.md has instructions for running its sample.

Sample Source Code Try it
Add and drop new database role source code Open in Cloud Shell
Backups-cancel source code Open in Cloud Shell
Copies a source backup source code Open in Cloud Shell
Backups-create-with-encryption-key source code Open in Cloud Shell
Backups-create source code Open in Cloud Shell
Backups-delete source code Open in Cloud Shell
Backups-get-database-operations source code Open in Cloud Shell
Backups-get-operations source code Open in Cloud Shell
Backups-get source code Open in Cloud Shell
Backups-restore-with-encryption-key source code Open in Cloud Shell
Backups-restore source code Open in Cloud Shell
Backups-update source code Open in Cloud Shell
Backups source code Open in Cloud Shell
Batch source code Open in Cloud Shell
CRUD source code Open in Cloud Shell
Creates a new database with a specific default leader source code Open in Cloud Shell
Database-create-with-encryption-key source code Open in Cloud Shell
Database-create-with-version-retention-period source code Open in Cloud Shell
Gets the schema definition of an existing database source code Open in Cloud Shell
Gets the default leader option of an existing database source code Open in Cloud Shell
Updates the default leader of an existing database source code Open in Cloud Shell
Updates a Cloud Spanner Database. source code Open in Cloud Shell
Datatypes source code Open in Cloud Shell
Runs an execute sql request with directed read options source code Open in Cloud Shell
Delete using DML returning. source code Open in Cloud Shell
Insert using DML returning. source code Open in Cloud Shell
Update using DML returning. source code Open in Cloud Shell
DML source code Open in Cloud Shell
Enable fine grained access control source code Open in Cloud Shell
Get-commit-stats source code Open in Cloud Shell
List database roles source code Open in Cloud Shell
Gets the instance config metadata for the configuration nam6 source code Open in Cloud Shell
Creates a new value-storing index source code Open in Cloud Shell
Creates a new index source code Open in Cloud Shell
Executes a read-only SQL query using an existing index. source code Open in Cloud Shell
Reads data using an existing storing index. source code Open in Cloud Shell
Read data using an existing index. source code Open in Cloud Shell
Indexing source code Open in Cloud Shell
Creates a user-managed instance configuration. source code Open in Cloud Shell
Deletes a user-managed instance configuration. source code Open in Cloud Shell
Lists the instance configuration operations. source code Open in Cloud Shell
Updates a user-managed instance configuration. source code Open in Cloud Shell
Instance-with-processing-units source code Open in Cloud Shell
Instance source code Open in Cloud Shell
Json-add-column source code Open in Cloud Shell
Json-query-parameter source code Open in Cloud Shell
Json-update-data source code Open in Cloud Shell
Lists all databases on the selected instance source code Open in Cloud Shell
Lists all the available instance configs for the selected project. source code Open in Cloud Shell
Numeric-add-column source code Open in Cloud Shell
Numeric-query-parameter source code Open in Cloud Shell
Numeric-update-data source code Open in Cloud Shell
Adds a column to an existing table in a Spanner PostgreSQL database. source code Open in Cloud Shell
Showcase the rules for case-sensitivity and case folding for a Spanner PostgreSQL database. source code Open in Cloud Shell
Creates a PostgreSQL Database. source code Open in Cloud Shell
Use cast operator to cast from one data type to another in a Spanner PostgreSQL database. source code Open in Cloud Shell
Execute a batch of DML statements on a Spanner PostgreSQL database. source code Open in Cloud Shell
Updates data in a table in a Spanner PostgreSQL database. source code Open in Cloud Shell
Execute a Partitioned DML on a Spanner PostgreSQL database. source code Open in Cloud Shell
Delete using DML returning on a Spanner PostgreSQL database. source code Open in Cloud Shell
Insert using DML returning on a Spanner PostgreSQL database. source code Open in Cloud Shell
Update using DML returning on a Spanner PostgreSQL database. source code Open in Cloud Shell
Execute a DML statement with parameters on a Spanner PostgreSQL database. source code Open in Cloud Shell
Calls a server side function on a Spanner PostgreSQL database. source code Open in Cloud Shell
Creates a new storing index in a Spanner PostgreSQL database. source code Open in Cloud Shell
Created interleaved table hierarchy using PostgreSQL dialect. source code Open in Cloud Shell
Showcase how add a jsonb column in a PostgreSQL table. source code Open in Cloud Shell
Showcase how query data to a jsonb column in a PostgreSQL table. source code Open in Cloud Shell
Showcase how update data to a jsonb column in a PostgreSQL table. source code Open in Cloud Shell
Showcase how to work with the PostgreSQL NUMERIC/DECIMAL data type on a Spanner PostgreSQL database. source code Open in Cloud Shell
Showcases how a Spanner PostgreSQL database orders null values in a query. source code Open in Cloud Shell
Execute a query with parameters on a Spanner PostgreSQL database. source code Open in Cloud Shell
Query the information schema metadata in a Spanner PostgreSQL database. source code Open in Cloud Shell
Alters a sequence in a PostgreSQL database. source code Open in Cloud Shell
Creates sequence in PostgreSQL database. source code Open in Cloud Shell
Drops a sequence in PostgreSQL database. source code Open in Cloud Shell
Queryoptions source code Open in Cloud Shell
Quickstart source code Open in Cloud Shell
Read data with database role source code Open in Cloud Shell
Sets a request tag for a single query source code Open in Cloud Shell
Run Batch update with RPC priority source code Open in Cloud Shell
Run partitioned update with RPC priority source code Open in Cloud Shell
Create partitions with RPC priority source code Open in Cloud Shell
Read data with RPC Priority source code Open in Cloud Shell
Query data with RPC Priority source code Open in Cloud Shell
Run transaction with RPC priority source code Open in Cloud Shell
Schema source code Open in Cloud Shell
Alters a sequence in a GoogleSQL database. source code Open in Cloud Shell
Creates sequence in GoogleSQL database. source code Open in Cloud Shell
Drops a sequence in GoogleSQL database. source code Open in Cloud Shell
Struct source code Open in Cloud Shell
Alters a table with foreign key delete cascade action source code Open in Cloud Shell
Creates a table with foreign key delete cascade action source code Open in Cloud Shell
Drops a foreign key constraint with delete cascade action source code Open in Cloud Shell
Timestamp source code Open in Cloud Shell
Executes a read/write transaction with transaction and request tags source code Open in Cloud Shell
Transaction source code Open in Cloud Shell

The Cloud Spanner Node.js Client API Reference documentation also contains samples.

Supported Node.js Versions

Our client libraries follow the Node.js release schedule. Libraries are compatible with all current active and maintenance versions of Node.js. If you are using an end-of-life version of Node.js, we recommend that you update as soon as possible to an actively supported LTS version.

Google's client libraries support legacy versions of Node.js runtimes on a best-efforts basis with the following warnings:

  • Legacy versions are not tested in continuous integration.
  • Some security patches and features cannot be backported.
  • Dependencies cannot be kept up-to-date.

Client libraries targeting some end-of-life versions of Node.js are available, and can be installed through npm dist-tags. The dist-tags follow the naming convention legacy-(version). For example, npm install @google-cloud/spanner@legacy-8 installs client libraries for versions compatible with Node.js 8.

Versioning

This library follows Semantic Versioning.

This library is considered to be stable. The code surface will not change in backwards-incompatible ways unless absolutely necessary (e.g. because of critical security issues) or with an extensive deprecation period. Issues and requests against stable libraries are addressed with the highest priority.

More Information: Google Cloud Platform Launch Stages

Contributing

Contributions welcome! See the Contributing Guide.

Please note that this README.md, the samples/README.md, and a variety of configuration files in this repository (including .nycrc and tsconfig.json) are generated from a central template. To edit one of these files, make an edit to its templates in directory.

License

Apache Version 2.0

See LICENSE