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.

SampleSource CodeTry it
Add and drop new database rolesource codeOpen in Cloud Shell
Backups-cancelsource codeOpen in Cloud Shell
Copies a source backupsource codeOpen in Cloud Shell
Backups-create-with-encryption-keysource codeOpen in Cloud Shell
Backups-createsource codeOpen in Cloud Shell
Backups-deletesource codeOpen in Cloud Shell
Backups-get-database-operationssource codeOpen in Cloud Shell
Backups-get-operationssource codeOpen in Cloud Shell
Backups-getsource codeOpen in Cloud Shell
Backups-restore-with-encryption-keysource codeOpen in Cloud Shell
Backups-restoresource codeOpen in Cloud Shell
Backups-updatesource codeOpen in Cloud Shell
Backupssource codeOpen in Cloud Shell
Batchsource codeOpen in Cloud Shell
CRUDsource codeOpen in Cloud Shell
Creates a new database with a specific default leadersource codeOpen in Cloud Shell
Database-create-with-encryption-keysource codeOpen in Cloud Shell
Database-create-with-version-retention-periodsource codeOpen in Cloud Shell
Gets the schema definition of an existing databasesource codeOpen in Cloud Shell
Gets the default leader option of an existing databasesource codeOpen in Cloud Shell
Updates the default leader of an existing databasesource codeOpen in Cloud Shell
Updates a Cloud Spanner Database.source codeOpen in Cloud Shell
Datatypessource codeOpen in Cloud Shell
Delete using DML returning.source codeOpen in Cloud Shell
Insert using DML returning.source codeOpen in Cloud Shell
Update using DML returning.source codeOpen in Cloud Shell
DMLsource codeOpen in Cloud Shell
Enable fine grained access controlsource codeOpen in Cloud Shell
Get-commit-statssource codeOpen in Cloud Shell
List database rolessource codeOpen in Cloud Shell
Gets the instance config metadata for the configuration nam6source codeOpen in Cloud Shell
Creates a new value-storing indexsource codeOpen in Cloud Shell
Creates a new indexsource codeOpen in Cloud Shell
Executes a read-only SQL query using an existing index.source codeOpen in Cloud Shell
Reads data using an existing storing index.source codeOpen in Cloud Shell
Read data using an existing index.source codeOpen in Cloud Shell
Indexingsource codeOpen in Cloud Shell
Creates a user-managed instance configuration.source codeOpen in Cloud Shell
Deletes a user-managed instance configuration.source codeOpen in Cloud Shell
Lists the instance configuration operations.source codeOpen in Cloud Shell
Updates a user-managed instance configuration.source codeOpen in Cloud Shell
Instance-with-processing-unitssource codeOpen in Cloud Shell
Instancesource codeOpen in Cloud Shell
Json-add-columnsource codeOpen in Cloud Shell
Json-query-parametersource codeOpen in Cloud Shell
Json-update-datasource codeOpen in Cloud Shell
Lists all databases on the selected instancesource codeOpen in Cloud Shell
Lists all the available instance configs for the selected project.source codeOpen in Cloud Shell
Numeric-add-columnsource codeOpen in Cloud Shell
Numeric-query-parametersource codeOpen in Cloud Shell
Numeric-update-datasource codeOpen in Cloud Shell
Adds a column to an existing table in a Spanner PostgreSQL database.source codeOpen in Cloud Shell
Showcase the rules for case-sensitivity and case folding for a Spanner PostgreSQL database.source codeOpen in Cloud Shell
Creates a PostgreSQL Database.source codeOpen in Cloud Shell
Use cast operator to cast from one data type to another in a Spanner PostgreSQL database.source codeOpen in Cloud Shell
Execute a batch of DML statements on a Spanner PostgreSQL database.source codeOpen in Cloud Shell
Updates data in a table in a Spanner PostgreSQL database.source codeOpen in Cloud Shell
Execute a Partitioned DML on a Spanner PostgreSQL database.source codeOpen in Cloud Shell
Delete using DML returning on a Spanner PostgreSQL database.source codeOpen in Cloud Shell
Insert using DML returning on a Spanner PostgreSQL database.source codeOpen in Cloud Shell
Update using DML returning on a Spanner PostgreSQL database.source codeOpen in Cloud Shell
Execute a DML statement with parameters on a Spanner PostgreSQL database.source codeOpen in Cloud Shell
Calls a server side function on a Spanner PostgreSQL database.source codeOpen in Cloud Shell
Creates a new storing index in a Spanner PostgreSQL database.source codeOpen in Cloud Shell
Created interleaved table hierarchy using PostgreSQL dialect.source codeOpen in Cloud Shell
Showcase how add a jsonb column in a PostgreSQL table.source codeOpen in Cloud Shell
Showcase how query data to a jsonb column in a PostgreSQL table.source codeOpen in Cloud Shell
Showcase how update data to a jsonb column in a PostgreSQL table.source codeOpen in Cloud Shell
Showcase how to work with the PostgreSQL NUMERIC/DECIMAL data type on a Spanner PostgreSQL database.source codeOpen in Cloud Shell
Showcases how a Spanner PostgreSQL database orders null values in a query.source codeOpen in Cloud Shell
Execute a query with parameters on a Spanner PostgreSQL database.source codeOpen in Cloud Shell
Query the information schema metadata in a Spanner PostgreSQL database.source codeOpen in Cloud Shell
Alters a sequence in a PostgreSQL database.source codeOpen in Cloud Shell
Creates sequence in PostgreSQL database.source codeOpen in Cloud Shell
Drops a sequence in PostgreSQL database.source codeOpen in Cloud Shell
Queryoptionssource codeOpen in Cloud Shell
Quickstartsource codeOpen in Cloud Shell
Read data with database rolesource codeOpen in Cloud Shell
Sets a request tag for a single querysource codeOpen in Cloud Shell
Run Batch update with RPC prioritysource codeOpen in Cloud Shell
Run partitioned update with RPC prioritysource codeOpen in Cloud Shell
Create partitions with RPC prioritysource codeOpen in Cloud Shell
Read data with RPC Prioritysource codeOpen in Cloud Shell
Query data with RPC Prioritysource codeOpen in Cloud Shell
Run transaction with RPC prioritysource codeOpen in Cloud Shell
Schemasource codeOpen in Cloud Shell
Alters a sequence in a GoogleSQL database.source codeOpen in Cloud Shell
Creates sequence in GoogleSQL database.source codeOpen in Cloud Shell
Drops a sequence in GoogleSQL database.source codeOpen in Cloud Shell
Structsource codeOpen in Cloud Shell
Alters a table with foreign key delete cascade actionsource codeOpen in Cloud Shell
Creates a table with foreign key delete cascade actionsource codeOpen in Cloud Shell
Drops a foreign key constraint with delete cascade actionsource codeOpen in Cloud Shell
Timestampsource codeOpen in Cloud Shell
Executes a read/write transaction with transaction and request tagssource codeOpen in Cloud Shell
Transactionsource codeOpen 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