@google-cloud/spanner 2.2.1 » Class: Instance

Instance

class

The Instance class represents a Cloud Spanner instance.

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

Constructor

Instance

new Instance(spanner, name)

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) {
    const operation = data[0];
    const 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) {
    const database = data[0];
    const operation = data[1];
    return operation.promise();
  })
  .then(function() {
    // Database created successfully.
  });

Full example:

View on GitHub

// 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
const [database, operation] = await instance.createDatabase(
  databaseId,
  request
);

console.log(`Waiting for operation on ${database.id} to complete...`);
await operation.promise();

console.log(`Created database ${databaseId} on instance ${instanceId}.`);

database

database(name, poolOptions) returns Database

Get a reference to a Database object.

Parameter
name	string The name of the instance.
poolOptions	Optional (SessionPoolOptions or SessionPoolCtor) 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) {
  const 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) {
  const 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) {
  const instance = data[0];
  const 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) {
  const 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) {
  const metadata = data[0];
  const 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 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];
});