Class Instance (7.3.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:

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

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;