Class Instance (7.5.0)

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

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;

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;

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>;

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:

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

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

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

  const databaseAdminClient = spanner.getDatabaseAdminClient();

  const createSingersTableStatement = `
    CREATE TABLE Singers (
        SingerId   INT64 NOT NULL,
        FirstName  STRING(1024),
        LastName   STRING(1024),
        SingerInfo BYTES(MAX)
    ) PRIMARY KEY (SingerId)`;
  const createAlbumsTableStatement = `
    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 new database
  try {
    const [operation] = await databaseAdminClient.createDatabase({
      createStatement: 'CREATE DATABASE `' + databaseID + '`',
      extraStatements: [
        createSingersTableStatement,
        createAlbumsTableStatement,
      ],
      parent: databaseAdminClient.instancePath(projectID, instanceID),
    });

    console.log(`Waiting for creation of ${databaseID} to complete...`);
    await operation.promise();

    console.log(`Created database ${databaseID} on instance ${instanceID}.`);
  } catch (err) {
    console.error('ERROR:', err);
  }

createDatabase(name, callback)

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

createDatabase(name, options, callback)

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

database(name, poolOptions, queryOptions)

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

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>;

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;

delete(gaxOptions, callback)

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

exists(gaxOptions)

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

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;

exists(gaxOptions, callback)

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

formatName_(projectId, name)

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

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

get(options)

get(options?: GetInstanceConfig): Promise<GetInstanceResponse>;

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;

get(options, callback)

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

getBackupOperations(options)

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

getBackupOperations(callback)

getBackupOperations(callback: GetBackupOperationsCallback): void;

getBackupOperations(options, callback)

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

getBackups(options)

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

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;

getBackups(options, callback)

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

getBackupsStream(options)

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

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>;

getDatabaseOperations(callback)

getDatabaseOperations(callback: GetDatabaseOperationsCallback): void;

getDatabaseOperations(options, callback)

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

getDatabases(options)

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

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;

getDatabases(options, callback)

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

getDatabasesStream(options)

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

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>;

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;

getMetadata(options, callback)

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

setMetadata(metadata, gaxOptions)

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

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;

setMetadata(metadata, gaxOptions, callback)

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