Constructor

Instance

new Instance(spanner, name)

The Instance class represents a Cloud Spanner instance.

Create an Instance object to interact with a Cloud Spanner instance.

Parameter

spanner

Spanner

Spanner instance.

name

string

Name of the instance.

Example

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

Property

id

string

Methods

create

create(config, callback) returns Promise containing CreateInstanceResponse

Create an instance.

Wrapper around v1.InstanceAdminClient#createInstance.

Parameter

config

CreateInstanceRequest

Configuration object.

callback

Optional

CreateInstanceCallback

Callback function.

See also
v1.InstanceAdminClient#createInstance

CreateInstance API Documentation

Returns

Promise containing CreateInstanceResponse 

Example

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

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

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

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

//-
// If the callback is omitted, we'll return a Promise.
//-
instance.create()
  .then(function(data) {
    var operation = data[0];
    var apiResponse = data[1];

    return operation.promise();
  })
  .then(function() {
    // Instance created successfully.
  });

createDatabase

createDatabase(name, options, callback) returns Promise containing CreateDatabaseResponse

Create a database in this instance.

Wrapper around v1.DatabaseAdminClient#createDatabase.

Parameter

name

name

The name of the database to create.

options

Optional

CreateDatabaseRequest

Configuration object.

callback

Optional

CreateDatabaseCallback

Callback function.

See also
v1.DatabaseAdminClient#createDatabase

CreateDatabase API Documentation

Throws

Error 

If a name is not provided.

Returns

Promise containing CreateDatabaseResponse 

Example

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

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

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

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

instance.createDatabase('new-database-name', callback);

//-
// Set the schema for the database.
//-
instance.createDatabase('new-database-name', {
  schema:
    'CREATE TABLE Singers (' +
    '  SingerId STRING(1024) NOT NULL,' +
    '  Name STRING(1024),' +
    ') PRIMARY KEY(SingerId)'
}, callback);
//-
// If the callback is omitted, we'll return a Promise.
//-
instance.createDatabase('new-database-name')
  .then(function(data) {
    var database = data[0];
    var operation = data[1];
    return operation.promise();
  })
  .then(function() {
    // Database created successfully.
  });

Full example:

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

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const projectId = 'my-project-id';
// const instanceId = 'my-instance';
// const databaseId = 'my-database';

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

// Gets a reference to a Cloud Spanner instance
const instance = spanner.instance(instanceId);

// Note: Cloud Spanner interprets Node.js numbers as FLOAT64s, so they
// must be converted to strings before being inserted as INT64s
const request = {
  schema: [
    `CREATE TABLE Singers (
      SingerId    INT64 NOT NULL,
      FirstName   STRING(1024),
      LastName    STRING(1024),
      SingerInfo  BYTES(MAX)
    ) PRIMARY KEY (SingerId)`,
    `CREATE TABLE Albums (
      SingerId    INT64 NOT NULL,
      AlbumId     INT64 NOT NULL,
      AlbumTitle  STRING(MAX)
    ) PRIMARY KEY (SingerId, AlbumId),
    INTERLEAVE IN PARENT Singers ON DELETE CASCADE`,
  ],
};

// Creates a database
instance
  .createDatabase(databaseId, request)
  .then(results => {
    const database = results[0];
    const operation = results[1];

    console.log(`Waiting for operation on ${database.id} to complete...`);
    return operation.promise();
  })
  .then(() => {
    console.log(`Created database ${databaseId} on instance ${instanceId}.`);
  })
  .catch(err => {
    console.error('ERROR:', err);
  });

database

database(name, poolOptions) returns Database

Get a reference to a Database object.

Parameter

name

string

The name of the instance.

poolOptions

Optional

SessionPoolOptions

Session pool configuration options.

Throws

Error 

If a name is not provided.

Returns

Database 

A Database object.

Example

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

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

delete

delete(callback) returns Promise containing DeleteInstanceResponse

Delete the instance.

Wrapper around v1.InstanceAdminClient#deleteInstance.

Parameter

callback

Optional

DeleteInstanceCallback

Callback function.

See also
v1.InstanceAdminClient#deleteInstance

DeleteInstance API Documentation

Returns

Promise containing DeleteInstanceResponse 

Example

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

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

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

  // Instance was deleted successfully.
});

//-
// If the callback is omitted, we'll return a Promise.
//-
instance.delete().then(function(data) {
  var apiResponse = data[0];
});

exists

exists(callback) returns Promise containing InstanceExistsResponse

Check if an instance exists.

Parameter

callback

Optional

InstanceExistsCallback

Callback function.

Returns

Promise containing InstanceExistsResponse 

Example

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

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

instance.exists(function(err, exists) {});

//-
// If the callback is omitted, we'll return a Promise.
//-
instance.exists().then(function(data) {
  var exists = data[0];
});

get

get(options, callback) returns Promise containing GetInstanceResponse

Get an instance if it exists.

You may optionally use this to "get or create" an object by providing an object with autoCreate set to true. Any extra configuration that is normally required for the create method must be contained within this object as well.

Parameter

options

Optional

options

Configuration object.

Values in options have the following properties:

Parameter

autoCreate

Optional

boolean

Automatically create the object if it does not exist.

callback

Optional

GetInstanceCallback

Callback function.

Returns

Promise containing GetInstanceResponse 

Example

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

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

instance.get(function(err, instance, apiResponse) {
  // `instance.metadata` has been populated.
});

//-
// If the callback is omitted, we'll return a Promise.
//-
instance.get().then(function(data) {
  var instance = data[0];
  var apiResponse = data[0];
});

getDatabases

getDatabases(query, callback) returns Promise containing GetDatabasesResponse

Get a list of databases.

Wrapper around v1.DatabaseAdminClient#listDatabases.

Parameter

query

Optional

GetDatabasesRequest

Query object for listing databases.

callback

Optional

GetDatabasesCallback

Callback function.

See also
v1.DatabaseAdminClient#listDatabases

ListDatabases API Documentation

Returns

Promise containing GetDatabasesResponse 

Example

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

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

instance.getDatabases(function(err, databases) {
  // `databases` is an array of `Database` objects.
});

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

instance.getDatabases({
  autoPaginate: false
}, callback);

//-
// If the callback is omitted, we'll return a Promise.
//-
instance.getDatabases().then(function(data) {
  var databases = data[0];
});

getMetadata

getMetadata(callback) returns Promise containing GetInstanceMetadataResponse

Get the instance's metadata.

Wrapper around v1.InstanceAdminClient#getInstance.

Parameter

callback

Optional

GetInstanceMetadataCallback

Callback function.

See also
v1.InstanceAdminClient#getInstance

GetInstance API Documentation

Returns

Promise containing GetInstanceMetadataResponse 

Example

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

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

instance.getMetadata(function(err, metadata, apiResponse) {});

//-
// If the callback is omitted, we'll return a Promise.
//-
instance.getMetadata().then(function(data) {
  var metadata = data[0];
  var apiResponse = data[1];
});

setMetadata

setMetadata(metadata, callback) returns Promise containing LongRunningOperationResponse

Update the metadata for this instance. Note that this method follows PATCH semantics, so previously-configured settings will persist.

Wrapper around v1.InstanceAdminClient#updateInstance.

Parameter

metadata

Object with any type properties

The metadata you wish to set.

callback

Optional

LongRunningOperationCallback

Callback function.

See also
v1.InstanceAdminClient#updateInstance

UpdateInstance API Documentation

Returns

Promise containing LongRunningOperationResponse 

Example

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

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

const metadata = {
  displayName: 'My Instance'
};

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

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

//-
// If the callback is omitted, we'll return a Promise.
//-
instance.setMetadata(metadata).then(function(data) {
  const operation = data[0];
  const apiResponse = data[1];
});