Objectives
This tutorial walks you through the following steps using the Spanner client library for Node.js:
- Create a Spanner instance and database.
- Write, read, and execute SQL queries on data in the database.
- Update the database schema.
- Update data using a read-write transaction.
- Add a secondary index to the database.
- Use the index to read and execute SQL queries on data.
- Retrieve data using a read-only transaction.
Costs
This tutorial uses Spanner, which is a billable component of the Google Cloud. For information on the cost of using Spanner, see Pricing.
Before you begin
Complete the steps described in Set up, which cover creating and setting a default Google Cloud project, enabling billing, enabling the Cloud Spanner API, and setting up OAuth 2.0 to get authentication credentials to use the Cloud Spanner API.
In particular, make sure that you run gcloud auth
application-default login
to set up your local development environment with authentication
credentials.
Prepare your local Node.js environment
Follow the steps to Set Up a Node.js Development Environment
Clone the sample app repository to your local machine:
git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.gitAlternatively, you can download the sample as a zip file and extract it.
Change to the directory that contains the Spanner sample code:
cd nodejs-docs-samples/spanner/Install dependencies using
npm:npm install
Create an instance
When you first use Spanner, you must create an instance, which is an allocation of resources that are used by Spanner databases. When you create an instance, you choose an instance configuration, which determines where your data is stored, and also the number of nodes to use, which determines the amount of serving and storage resources in your instance.
See Create an instance
to learn how to create a Spanner instance using any of the
following methods. You can name your instance test-instance to use it with
other topics in this document that reference an instance named test-instance.
- The Google Cloud CLI
- The Google Cloud console
- A client library (C++, C#, Go, Java, Node.js, PHP, Python, or Ruby)
Look through sample files
The samples repository contains a sample that shows how to use Spanner with Node.js.
Take a look through the samples/schema.js file, which shows how to
create a database and modify a database schema. The data uses the example schema
shown in the Schema and data model
page.
Create a database
GoogleSQL
node schema.js createDatabase test-instance example-db MY_PROJECT_ID
PostgreSQL
node schema.js createPgDatabase test-instance example-db MY_PROJECT_ID
You should see:
Created database example-db on instance test-instance.
GoogleSQL
PostgreSQL
The next step is to write data to your database.
Create a database client
Before you can do reads or writes, you must create aDatabase:
You can think of a Database as a database connection: all of your interactions
with Spanner must go through a Database. Typically you create a Database
when your application starts up, then you re-use that Database to read, write,
and execute transactions. Each client uses resources in Spanner.
If you create multiple clients in the same app, you should call
Database.close()
to clean up the client's resources, including network connections, as soon as it
is no longer needed.
Read more in the Database
reference.
Write data with DML
You can insert data using Data Manipulation Language (DML) in a read-write transaction.
You use the runUpdate() method to execute a DML statement.
Run the sample using the writeUsingDml argument.
node dml.js writeUsingDml test-instance example-db MY_PROJECT_ID
You should see:
4 records inserted.
Write data with mutations
You can also insert data using mutations.
You write data using a
Table object. The
Table.insert()
method adds new rows to the table. All inserts in a single batch are applied
atomically.
This code shows how to write the data using mutations: