Class Instance (7.3.0)

The Instance class represents a [Cloud Spanner instance](https://cloud.google.com/spanner/docs/instances).

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

Inheritance

common.GrpcServiceObject > Instance

Package

Example


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

Constructors

(constructor)(spanner, name)

constructor(spanner: Spanner, name: string);

Constructs a new instance of the Instance class

Parameters
Name	Description
`spanner`	`Spanner`
`name`	`string`

Properties

databases_

databases_: Map<string, Database>;

formattedName_

formattedName_: string;

metadata

metadata?: IInstance;

request

request: InstanceRequest;

requestStream

requestStream: (config: RequestConfig) => Duplex;

resourceHeader_

resourceHeader_: {
        [k: string]: string;
    };

Methods

backup(backupId)

backup(backupId: string): Backup;

Get a reference to a Backup object.

Parameter
Name	Description
`backupId`	`string` The name of the backup. {Backup} A Backup object.

Returns
Type	Description
`Backup`

Example


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

copyBackup(sourceBackupId, backupId, options, callback)

copyBackup(sourceBackupId: string, backupId: string, options: CopyBackupOptions, callback?: CopyBackupCallback): Promise<CopyBackupResponse> | void;

CopyBackupCallback

Parameters
Name	Description
`sourceBackupId`	`string` Full path of the source backup to be copied.
`backupId`	`string` The name of the backup.
`options`	`CopyBackupOptions`
`callback`	`CopyBackupCallback`

Returns
Type	Description
`Promise<CopyBackupResponse> \| void`

Example


const {Spanner} = require('@google-cloud/spanner');
const spanner = new Spanner();
const instance = spanner.instance('my-instance');
const backup = instance.copyBackup('my-source-backup','my-backup',{
  expireTime: expireTime,
  encryptionConfig: {
    encryptionType: 'CUSTOMER_MANAGED_ENCRYPTION',
    kmsKeyName: 'projects/my-project-id/my-region/keyRings/my-key-ring/cryptoKeys/my-key',
  },);

createDatabase(name, options)

createDatabase(name: string, options?: CreateDatabaseOptions): Promise<CreateDatabaseResponse>;

Create a database in this instance.

Wrapper around .

Parameters
Name	Description
`name`	`string` The name of the database to create.
`options`	`CreateDatabaseOptions` Configuration object.

Returns

Type Description

Promise<CreateDatabaseResponse>

{Promise

Examples


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:


  // 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),
        FullName    STRING(2048) AS (ARRAY_TO_STRING([FirstName, LastName], " ")) STORED,
      ) 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}.`);

createDatabase(name, callback)

createDatabase(name: string, callback: CreateDatabaseCallback): void;

Parameters
Name	Description
`name`	`string`
`callback`	`CreateDatabaseCallback`

Returns
Type	Description
`void`

createDatabase(name, options, callback)

createDatabase(name: string, options: CreateDatabaseOptions, callback: CreateDatabaseCallback): void;

Parameters
Name	Description
`name`	`string`
`options`	`CreateDatabaseOptions`
`callback`	`CreateDatabaseCallback`

Returns
Type	Description
`void`

database(name, poolOptions, queryOptions)

database(name: string, poolOptions?: SessionPoolOptions | SessionPoolConstructor, queryOptions?: spannerClient.spanner.v1.ExecuteSqlRequest.IQueryOptions): Database;

Get a reference to a Database object.

Parameters
Name	Description
`name`	`string` The name of the instance.
`poolOptions`	`SessionPoolOptions \| SessionPoolConstructor` Session pool configuration options.
`queryOptions`	`IQueryOptions` Default query options to use with the database. These options will be overridden by any query options set in environment variables or that are specified on a per-query basis. {Database} A Database object.

Returns
Type	Description
`Database`

Example


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

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

delete(gaxOptions)

delete(gaxOptions?: CallOptions): Promise<DeleteInstanceResponse>;

Delete the instance.

Wrapper around .

Parameter
Name	Description
`gaxOptions`	`CallOptions` Request configuration options, See CallOptions for more details.

Returns

Type Description

Promise<DeleteInstanceResponse>

{Promise

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];
});

delete(callback)

delete(callback: DeleteInstanceCallback): void;

Parameter
Name	Description
`callback`	`DeleteInstanceCallback`

Returns
Type	Description
`void`

delete(gaxOptions, callback)

delete(gaxOptions: CallOptions, callback: DeleteInstanceCallback): void;

Parameters
Name	Description
`gaxOptions`	`CallOptions`
`callback`	`DeleteInstanceCallback`

Returns
Type	Description
`void`

exists(gaxOptions)

exists(gaxOptions?: CallOptions): Promise<ExistsInstanceResponse>;

Check if an instance exists.

Instance#exists

Parameter
Name	Description
`gaxOptions`	`CallOptions` Request configuration options, See CallOptions for more details.

Returns

Type Description

Promise<ExistsInstanceResponse>

{Promise

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];
});

exists(callback)

exists(callback: ExistsInstanceCallback): void;

Parameter
Name	Description
`callback`	`ExistsInstanceCallback`

Returns
Type	Description
`void`

exists(gaxOptions, callback)

exists(gaxOptions: CallOptions, callback: ExistsInstanceCallback): void;

Parameters
Name	Description
`gaxOptions`	`CallOptions`
`callback`	`ExistsInstanceCallback`

Returns
Type	Description
`void`

formatName_(projectId, name)

static formatName_(projectId: string, name: string): string;

Format the instance name to include the project ID.

Parameters
Name	Description
`projectId`	`string` The project ID.
`name`	`string` The instance name.

Returns
Type	Description
`string`	{string}

Example


Instance.formatName_('grape-spaceship-123', 'my-instance');
// 'projects/grape-spaceship-123/instances/my-instance'

get(options)

get(options?: GetInstanceConfig): Promise<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
Name	Description
`options`	`GetInstanceConfig` Configuration object.

Returns

Type Description

Promise<GetInstanceResponse>

{Promise

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];
});

get(callback)

get(callback: GetInstanceCallback): void;

Parameter
Name	Description
`callback`	`GetInstanceCallback`

Returns
Type	Description
`void`

get(options, callback)

get(options: GetInstanceConfig, callback: GetInstanceCallback): void;

Parameters
Name	Description
`options`	`GetInstanceConfig`
`callback`	`GetInstanceCallback`

Returns
Type	Description
`void`

getBackupOperations(options)

getBackupOperations(options?: GetBackupOperationsOptions): Promise<GetBackupOperationsResponse>;

GetBackupOperationsCallback

Parameter
Name	Description
`options`	`GetBackupOperationsOptions`

Returns
Type	Description
`Promise<GetBackupOperationsResponse>`

getBackupOperations(callback)

getBackupOperations(callback: GetBackupOperationsCallback): void;

Parameter
Name	Description
`callback`	`GetBackupOperationsCallback`

Returns
Type	Description
`void`

getBackupOperations(options, callback)

getBackupOperations(options: GetBackupOperationsOptions, callback: GetBackupOperationsCallback): void;

Parameters
Name	Description
`options`	`GetBackupOperationsOptions`
`callback`	`GetBackupOperationsCallback`

Returns
Type	Description
`void`

getBackups(options)

getBackups(options?: GetBackupsOptions): Promise<GetBackupsResponse>;

List backups on the instance.

Both completed and in-progress backups are listed if no filter is supplied.

Parameter
Name	Description
`options`	`GetBackupsOptions` The query object for listing backups.

Returns

Type Description

Promise<GetBackupsResponse>

{Promise

Example


const {Spanner} = require('@google-cloud/spanner');
const spanner = new Spanner();
const instance = spanner.instance('my-instance');
const [backups] = await instance.getBackups();

//-
// To manually handle pagination, set autoPaginate:false in gaxOptions.
//-
let pageToken = undefined;
do {
  const [backups, , response] = await instance.getBackups({
    pageSize: 3,
    pageToken,
    gaxOptions: {autoPaginate: false},
  });
  backups.forEach(backup => {
    // Do something with backup
  });
  pageToken = response.nextPageToken;
} while (pageToken);

getBackups(callback)

getBackups(callback: GetBackupsCallback): void;

Parameter
Name	Description
`callback`	`GetBackupsCallback`

Returns
Type	Description
`void`

getBackups(options, callback)

getBackups(options: GetBackupsOptions, callback: GetBackupsCallback): void;

Parameters
Name	Description
`options`	`GetBackupsOptions`
`callback`	`GetBackupsCallback`

Returns
Type	Description
`void`

getBackupsStream(options)

getBackupsStream(options?: GetBackupsOptions): NodeJS.ReadableStream;

Get a list of backups as a readable object stream.

Wrapper around .

Parameter
Name	Description
`options`	`GetBackupsOptions` Query object for listing backups.

Returns
Type	Description
`NodeJS.ReadableStream`	{ReadableStream} A readable stream that emits Backup instances.

Example


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

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

instance.getBackupsStream()
  .on('error', console.error)
  .on('data', function(database) {
    // `backups` is a `Backup` object.
  })
  .on('end', function() {
    // All backups retrieved.
  });

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

getDatabaseOperations(options)

getDatabaseOperations(options?: GetDatabaseOperationsOptions): Promise<GetDatabaseOperationsResponse>;

GetDatabaseOperationsCallback

Parameter
Name	Description
`options`	`GetDatabaseOperationsOptions`

Returns
Type	Description
`Promise<GetDatabaseOperationsResponse>`

getDatabaseOperations(callback)

getDatabaseOperations(callback: GetDatabaseOperationsCallback): void;

Parameter
Name	Description
`callback`	`GetDatabaseOperationsCallback`

Returns
Type	Description
`void`

getDatabaseOperations(options, callback)

getDatabaseOperations(options: GetDatabaseOperationsOptions, callback: GetDatabaseOperationsCallback): void;

Parameters
Name	Description
`options`	`GetDatabaseOperationsOptions`
`callback`	`GetDatabaseOperationsCallback`

Returns
Type	Description
`void`

getDatabases(options)

getDatabases(options?: GetDatabasesOptions): Promise<GetDatabasesResponse>;

Get a list of databases.

Wrapper around .

Parameter
Name	Description
`options`	`GetDatabasesOptions` Query object for listing databases.

Returns

Type Description

Promise<GetDatabasesResponse>

{Promise

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({
  gaxOptions: {autoPaginate: false}
}, callback);

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

getDatabases(callback)

getDatabases(callback: GetDatabasesCallback): void;

Parameter
Name	Description
`callback`	`GetDatabasesCallback`

Returns
Type	Description
`void`

getDatabases(options, callback)

getDatabases(options: GetDatabasesOptions, callback: GetDatabasesCallback): void;

Parameters
Name	Description
`options`	`GetDatabasesOptions`
`callback`	`GetDatabasesCallback`

Returns
Type	Description
`void`

getDatabasesStream(options)

getDatabasesStream(options?: GetDatabasesOptions): NodeJS.ReadableStream;

Get a list of databases as a readable object stream.

Wrapper around .

Parameter
Name	Description
`options`	`GetDatabasesOptions` Query object for listing databases.

Returns
Type	Description
`NodeJS.ReadableStream`	{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();
  });

getMetadata(options)

getMetadata(options?: GetInstanceMetadataOptions): Promise<GetInstanceMetadataResponse>;

Get the instance's metadata.

Wrapper around .

Parameter
Name	Description
`options`	`GetInstanceMetadataOptions` Configuration object

Returns

Type Description

Promise<GetInstanceMetadataResponse>

{Promise

Example


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

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

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

//-
// Request only `displayName`.
//-
instance.getMetadata({fieldNames: 'displayName'}, (err, metadata, apiResponse) => {
  // metadata will only contain value for `displayName`
  const displayName = metadata['displayName'];
})

//-
// Request multiple specific field names.
//-
instance.getMetadata({fieldNames: ['displayName', 'nodeCount']}, (err, metadata, apiResponse) => {
  // metadata will only contain value for `displayName` and 'nodeCount'
  const displayName = metadata['displayName'];
  const nodeCount = metadata['nodeCount'];
});

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

getMetadata(callback)

getMetadata(callback: GetInstanceMetadataCallback): void;

Parameter
Name	Description
`callback`	`GetInstanceMetadataCallback`

Returns
Type	Description
`void`

getMetadata(options, callback)

getMetadata(options: GetInstanceMetadataOptions, callback: GetInstanceMetadataCallback): void;

Parameters
Name	Description
`options`	`GetInstanceMetadataOptions`
`callback`	`GetInstanceMetadataCallback`

Returns
Type	Description
`void`

setMetadata(metadata, gaxOptions)

setMetadata(metadata: IInstance, gaxOptions?: CallOptions): Promise<SetInstanceMetadataResponse>;

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

Wrapper around .

Parameters
Name	Description
`metadata`	`IInstance` The metadata you wish to set.
`gaxOptions`	`CallOptions` Request configuration options, See CallOptions for more details.

Returns

Type Description

Promise<SetInstanceMetadataResponse>

{Promise

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];
});

setMetadata(metadata, callback)

setMetadata(metadata: IInstance, callback: SetInstanceMetadataCallback): void;

Parameters
Name	Description
`metadata`	`IInstance`
`callback`	`SetInstanceMetadataCallback`

Returns
Type	Description
`void`

setMetadata(metadata, gaxOptions, callback)

setMetadata(metadata: IInstance, gaxOptions: CallOptions, callback: SetInstanceMetadataCallback): void;

Parameters
Name	Description
`metadata`	`IInstance`
`gaxOptions`	`CallOptions`
`callback`	`SetInstanceMetadataCallback`

Returns
Type	Description
`void`