Constructor

Spanner

new Spanner(options)

Cloud Spanner is a highly scalable, transactional, managed, NewSQL database service. Cloud Spanner solves the need for a horizontally-scaling database with consistent global transaction and SQL semantics. With Cloud Spanner you don't need to choose between consistency and horizontal scaling — you get both.

Parameter

options

Optional

ClientConfig

Configuration options.

See also

Cloud Spanner Documentation

Cloud Spanner Concepts

Examples

Install the client library with npm:

npm install --save @google-cloud/spanner

Create a client that uses Application Default Credentials (ADC):

const client = new Spanner();

Create a client with explicit credentials:

const client = new Spanner({
  projectId: 'your-project-id',
  keyFilename: '/path/to/keyfile.json'
});

Full quickstart example:

// Imports the Google Cloud client library
const Spanner = require('@google-cloud/spanner');

// Your Google Cloud Platform project ID
const projectId = 'YOUR_PROJECT_ID';

// Creates a client
const spanner = Spanner({
  projectId: projectId,
});

// Your Cloud Spanner instance ID
const instanceId = 'my-instance';

// Your Cloud Spanner database ID
const databaseId = 'my-database';

// 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
database
  .run(query)
  .then(results => {
    const rows = results[0];

    rows.forEach(row => console.log(row));
  })
  .catch(err => {
    console.error('ERROR:', err);
  });

Properties

Database

static

Constructor

Database class.

See also
Database

Instance

static

Constructor

Instance class.

See also
Instance

Session

static

Constructor

Session class.

See also
Session

SessionPool

static

Constructor

SessionPool class.

See also
SessionPool

Table

static

Constructor

Table class.

See also
Table

Transaction

static

Constructor

Transaction class.

See also
Transaction

TransactionRequest

static

Constructor

TransactionRequest class.

See also
TransactionRequest

Methods

date

static

date(value) returns object

Helper function to get a Cloud Spanner Date object.

Parameter

value

(string or date)

The date as a string or Date object.

See also
Spanner#date
Returns

object 

Example

const Spanner = require('@google-cloud/spanner');
const date = Spanner.date('08-20-1969');

float

static

float(value) returns object

Helper function to get a Cloud Spanner Float64 object.

Parameter

value

(string or number)

The float as a number or string.

See also
Spanner#float
Returns

object 

Example

const Spanner = require('@google-cloud/spanner');
const float = Spanner.float(10);

int

static

int(value) returns object

Helper function to get a Cloud Spanner Int64 object.

Parameter

value

(string or number)

The int as a number or string.

See also
Spanner#int
Returns

object 

Example

const Spanner = require('@google-cloud/spanner');
const int = Spanner.int(10);

createInstance

createInstance(name, config, callback) returns Promise containing CreateInstanceResponse

Create an instance.

Wrapper around v1.InstanceAdminClient#createInstance.

Parameter

name

string

The name of the instance to be created.

config

CreateInstanceRequest

Configuration object.

callback

Optional

CreateInstanceCallback

Callback function.

See also
v1.InstanceAdminClient#createInstance

CreateInstace API Documentation

Throws

Error 

If a name is not provided.

Error 

If a configuration object is not provided.

Returns

Promise containing CreateInstanceResponse 

Example

const Spanner = require('@google-cloud/spanner');
const spanner = new Spanner();

const config = {
  config: 'regional-us-central1',
  nodes: 1
};

function callback(err, instance, operation, apiResponse) {
  if (err) {
    // Error handling omitted.
  }

  operation
    .on('error', function(err) {})
    .on('complete', function() {
      // Instance created successfully.
    });
}

spanner.createInstance('new-instance-name', config, callback);

//-
// If the callback is omitted, we'll return a Promise.
//-
spanner.createInstance('new-instance-name', config)
  .then(function(data) {
    var instance = data[0];
    var operation = data[1];
    return operation.promise();
  })
  .then(function() {
    // Instance created successfully.
  });

date

date(value) returns object

Helper function to get a Cloud Spanner Date object.

Parameter

value

(string or date)

The date as a string or Date object.

See also
Spanner.date
Returns

object 

Example

const Spanner = require('@google-cloud/spanner');
const spanner = new Spanner();
const date = spanner.date('08-20-1969');

float

float(value) returns object

Helper function to get a Cloud Spanner Float64 object.

Parameter

value

(string or number)

The float as a number or string.

See also
Spanner.float
Returns

object 

Example

const Spanner = require('@google-cloud/spanner');
const spanner = new Spanner();
const float = spanner.float(10);

getDatabasesStream

getDatabasesStream(query) returns ReadableStream

Get a list of databases as a readable object stream.

Wrapper around v1.DatabaseAdminClient#listDatabases.

Parameter

query

Optional

GetDatabasesRequest

Query object for listing databases.

See also
v1.DatabaseAdminClient#listDatabases

ListDatabases API Documentation

Returns

ReadableStream 

A readable stream that emits Database instances.

Example

const Spanner = require('@google-cloud/spanner');
const spanner = new Spanner();

const instance = spanner.instance('my-instance');

instance.getDatabasesStream()
  .on('error', console.error)
  .on('data', function(database) {
    // `database` is a `Database` object.
  })
  .on('end', function() {
    // All databases retrieved.
  });

//-
// If you anticipate many results, you can end a stream early to prevent
// unnecessary processing and API requests.
//-
instance.getDatabasesStream()
  .on('data', function(database) {
    this.end();
  });

getInstanceConfigs

getInstanceConfigs(query, callback) returns Promise containing GetInstanceConfigsResponse

Get a list of instance configs.

Wrapper around v1.InstanceAdminClient#listInstanceConfigs.

Parameter

query

Optional

GetInstanceConfigsRequest

Query object for listing instance configs.

callback

Optional

GetInstanceConfigsCallback

Callback function.

See also
v1.InstanceAdminClient#listInstanceConfigs

ListInstanceConfigs API Documentation

Returns

Promise containing GetInstanceConfigsResponse 

Example

const Spanner = require('@google-cloud/spanner');
const spanner = new Spanner();

spanner.getInstanceConfigs(function(err, instanceConfigs) {
  // `instanceConfigs` is an array of instance configuration descriptors.
});

//-
// To control how many API requests are made and page through the results
// manually, set `autoPaginate` to `false`.
//-
function callback(err, instanceConfigs, nextQuery, apiResponse) {
  if (nextQuery) {
    // More results exist.
    spanner.getInstanceConfigs(nextQuery, callback);
  }
}

spanner.getInstanceConfigs({
  autoPaginate: false
}, callback);

//-
// If the callback is omitted, we'll return a Promise.
//-
spanner.getInstanceConfigs().then(function(data) {
  const instanceConfigs = data[0];
});

getInstanceConfigsStream

getInstanceConfigsStream(query) returns ReadableStream

Get a list of instance configs as a readable object stream.

Wrapper around v1.InstanceAdminClient#listInstanceConfigsStream.

Parameter

query

Optional

GetInstanceConfigsRequest

Query object for listing instance configs.

See also
v1.InstanceAdminClient#listInstanceConfigsStream

ListInstanceConfigs API Documentation

Returns

ReadableStream 

A readable stream that emits instance configs.

Example

const Spanner = require('@google-cloud/spanner');
const spanner = new Spanner();

spanner.getInstanceConfigsStream()
  .on('error', console.error)
  .on('data', function(instanceConfig) {})
  .on('end', function() {
    // All instances retrieved.
  });

//-
// If you anticipate many results, you can end a stream early to prevent
// unnecessary processing and API requests.
//-
spanner.getInstanceConfigsStream()
  .on('data', function(instanceConfig) {
    this.end();
  });

getInstances

getInstances(query, callback) returns Promise containing GetInstancesResponse

Get a list of instances.

Wrapper around v1.InstanceAdminClient#listInstances.

Parameter

query

Optional

GetInstancesRequest

Query object for listing instances.

callback

Optional

GetInstancesCallback

Callback function.

See also
v1.InstanceAdminClient#listInstances

ListInstances API Documentation

Returns

Promise containing GetInstancesResponse 

Example

const Spanner = require('@google-cloud/spanner');
const spanner = new Spanner();

spanner.getInstances(function(err, instances) {
  // `instances` is an array of `Instance` objects.
});

//-
// To control how many API requests are made and page through the results
// manually, set `autoPaginate` to `false`.
//-
function callback(err, instances, nextQuery, apiResponse) {
  if (nextQuery) {
    // More results exist.
    spanner.getInstances(nextQuery, callback);
  }
}

spanner.getInstances({
  autoPaginate: false
}, callback);

//-
// If the callback is omitted, we'll return a Promise.
//-
spanner.getInstances().then(function(data) {
  const instances = data[0];
});

getInstancesStream

getInstancesStream(query) returns ReadableStream

Get a list of Instance objects as a readable object stream.

Wrapper around v1.InstanceAdminClient#listInstances.

Parameter

query

Optional

GetInstancesRequest

Query object for listing instances.

See also
v1.InstanceAdminClient#listInstances

ListInstances API Documentation

Returns

ReadableStream 

A readable stream that emits Instance instances.

Example

const Spanner = require('@google-cloud/spanner');
const spanner = new Spanner();

spanner.getInstancesStream()
  .on('error', console.error)
  .on('data', function(instance) {
    // `instance` is an `Instance` object.
  })
  .on('end', function() {
    // All instances retrieved.
  });

//-
// If you anticipate many results, you can end a stream early to prevent
// unnecessary processing and API requests.
//-
spanner.getInstancesStream()
  .on('data', function(instance) {
    this.end();
  });

instance

instance(name) returns Instance

Get a reference to an Instance object.

Parameter

name

string

The name of the instance.

Throws

Error 

If a name is not provided.

Returns

Instance 

An Instance object.

Example

const Spanner = require('@google-cloud/spanner');
const spanner = new Spanner();
const instance = spanner.instance('my-instance');

int

int(value) returns object

Helper function to get a Cloud Spanner Int64 object.

Parameter

value

(string or number)

The int as a number or string.

See also
Spanner.int
Returns

object 

Example

const Spanner = require('@google-cloud/spanner');
const spanner = new Spanner();
const int = spanner.int(10);

operation

operation(name) returns Operation

Get a reference to an Operation object.

Parameter

name

string

The name of the operation.

Throws

Error 

If a name is not provided.

Returns

Operation 

An Operation object.

Example

const Spanner = require('@google-cloud/spanner');
const spanner = new Spanner();
const operation = spanner.operation('operation-name');

request

request(config, callback)

Funnel all API requests through this method to be sure we have a project ID.

Parameter

config

object

Configuration object.

callback

Optional

function()

Callback function.

requestStream

requestStream(config, callback)

Funnel all streaming API requests through this method to be sure we have a project ID.

Parameter

config

object

Configuration object.

callback

Optional

function()

Callback function.