Cloud Spanner: Node.js Client

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.

• Cloud Spanner Node.js Client API Reference
• Cloud Spanner Documentation
• github.com/googleapis/nodejs-spanner

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
  • Installing the client library
  • Using the client library
• Samples
• Versioning
• Contributing
• License

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

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