Spanner

Spanner

Cloud Spanner is a highly scalable, transactional, managed, NewSQL database service. Cloud Spanner solves the need for a horizontally-scaling database with consistent global transaction and SQL semantics. With Cloud Spanner you don't need to choose between consistency and horizontal scaling — you get both.

Constructor

new Spanner(optionsopt)

Parameters:
Name Type Attributes Description
options ClientConfig <optional>

Configuration options.
See:
Examples
<caption>Install the client library with <a
href="https://www.npmjs.com/">npm</a>:</caption> npm install --save
<caption>Create a client that uses <a
href="https://cloud.google.com/docs/authentication/production#providing_credentials_to_your_application">Application
Default Credentials (ADC)</a>:</caption> const client = new Spanner();
<caption>Create a client with <a
href="https://cloud.google.com/docs/authentication/production#obtaining_and_providing_service_account_credentials_manually">explicit
credentials</a>:</caption> const client = new Spanner({ projectId:
'your-project-id', keyFilename: '/path/to/keyfile.json'
});

Full quickstart example: 

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

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

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

  // The query to execute
  const query = {
    sql: 'SELECT 1',
  };

  // Execute a simple SQL statement
  const [rows] = await database.run(query);
  console.log(`Query: ${rows.length} found.`);
  rows.forEach(row => console.log(row));

Members

COMMIT_TIMESTAMP

Placeholder used to auto populate a column with the commit timestamp. This can only be used for timestamp columns that have set the option "(allow_commit_timestamp=true)" in the schema.

Methods

(static) date(dateopt, monthopt, dateopt) → {SpannerDate}

Helper function to get a Cloud Spanner Date object.

DATE types represent a logical calendar date, independent of time zone. DATE values do not represent a specific 24-hour period. Rather, a given DATE value represents a different 24-hour period when interpreted in a different time zone. Because of this, all values passed to Spanner.date will be interpreted as local time.

To represent an absolute point in time, use Spanner.timestamp.

Parameters:
Name Type Attributes Description
date string | number <optional>

String representing the date or number representing the year.
month number <optional>

Number representing the month.
date number <optional>

Number representing the date.
Returns:
Type Description
SpannerDate
Example
const {Spanner} = require('@google-cloud/spanner');
const date = Spanner.date('08-20-1969');

(static) float(value) → {Float}

Helper function to get a Cloud Spanner Float64 object.

Parameters:
Name Type Description
value string | number

The float as a number or string.
Returns:
Type Description
Float
Example
const {Spanner} = require('@google-cloud/spanner');
const float = Spanner.float(10);

(static) getSpannerEmulatorHost()

Gets the configured Spanner emulator host from an environment variable.

(static) int(value) → {Int}

Helper function to get a Cloud Spanner Int64 object.

Parameters:
Name Type Description
value string | number

The int as a number or string.
Returns:
Type Description
Int
Example
const {Spanner} = require('@google-cloud/spanner');
const int = Spanner.int(10);

(static) numeric(value) → {Numeric}

Helper function to get a Cloud Spanner Numeric object.

Parameters:
Name Type Description
value string

The numeric value as a string.
Returns:
Type Description
Numeric
Example
const {Spanner} = require('@google-cloud/spanner');
const numeric = Spanner.numeric("3.141592653");

(static) struct(value) → {Struct}

Helper function to get a Cloud Spanner Struct object.

Parameters:
Name Type Description
value object

The struct as a JSON object.
Returns:
Type Description
Struct
Example
const {Spanner} = require('@google-cloud/spanner');
const struct = Spanner.struct({
  user: 'bob',
  age: 32
});

(static) timestamp(timestampopt) → {external:PreciseDate}

Helper function to get a Cloud Spanner Timestamp object.

String timestamps should have a canonical format of YYYY-[M]M-[D]D[( |T)[H]H:[M]M:[S]S[.DDDDDDDDD]]Z

Timestamp values must be expressed in Zulu time and cannot include a UTC offset.

Parameters:
Name Type Attributes Description
timestamp string | number | google.protobuf.Timestamp | external:PreciseDate <optional>

Either a RFC 3339 timestamp formatted string or a google.protobuf.Timestamp object. If a PreciseDate is given, it will return that timestamp as is.
Returns:
Type Description
external:PreciseDate
See:
Examples
const timestamp = Spanner.timestamp('2019-02-08T10:34:29.481145231Z');

With a `google.protobuf.Timestamp` object 

const [seconds, nanos] = process.hrtime();
const timestamp = Spanner.timestamp({seconds, nanos});

With a Date timestamp 

const timestamp = Spanner.timestamp(Date.now());

createInstance(name, config, callbackopt) → {Promise.<CreateInstanceResponse>}

Create an instance.

Wrapper around v1.InstanceAdminClient#createInstance.

Parameters:
Name Type Attributes Description
name string

The name of the instance to be created.
config CreateInstanceRequest

Configuration object.
callback CreateInstanceCallback <optional>

Callback function.
Returns:
Type Description
Promise.<CreateInstanceResponse>
See:
Throws:

  • If a name is not provided.

    Type
    Error

  • If a configuration object is not provided.

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

const config = {
  config: 'regional-us-central1',
  nodes: 1
};

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

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

spanner.createInstance('new-instance-name', config, callback);

//-
// If the callback is omitted, we'll return a Promise.
//-
spanner.createInstance('new-instance-name', config)
  .then(function(data) {
    const instance = data[0];
    const operation = data[1];
    return operation.promise();
  })
  .then(function() {
    // Instance created successfully.
  });

getBackupsStream(optionsopt) → {ReadableStream}

Get a list of backups as a readable object stream.

Wrapper around v1.DatabaseAdminClient#listBackups.

Parameters:
Name Type Attributes Description
options GetBackupOptions <optional>

Query object for listing backups.
Returns:
Type Description
ReadableStream

A readable stream that emits Backup instances.
See:
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();
  });

getDatabasesStream(optionsopt) → {ReadableStream}

Get a list of databases as a readable object stream.

Wrapper around v1.DatabaseAdminClient#listDatabases.

Parameters:
Name Type Attributes Description
options GetDatabasesOptions <optional>

Query object for listing databases.
Returns:
Type Description
ReadableStream

A readable stream that emits Database instances.
See:
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();
  });

getInstanceConfigs(optionsopt, callbackopt) → {Promise.<GetInstanceConfigsResponse>}

Get a list of instance configs.

Wrapper around v1.InstanceAdminClient#listInstanceConfigs.

Parameters:
Name Type Attributes Description
options GetInstanceConfigsOptions <optional>

Query object for listing instance configs.
callback GetInstanceConfigsCallback <optional>

Callback function.
Returns:
Type Description
Promise.<GetInstanceConfigsResponse>
See:
Example
const {Spanner} = require('@google-cloud/spanner');
const spanner = new Spanner();

spanner.getInstanceConfigs(function(err, instanceConfigs) {
  // `instanceConfigs` is an array of instance configuration descriptors.
});

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

spanner.getInstanceConfigs({
  gaxOptions: {
    autoPaginate: false,
  }
}, callback);

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

getInstanceConfigsStream(optionsopt) → {ReadableStream}

Get a list of instance configs as a readable object stream.

Wrapper around v1.InstanceAdminClient#listInstanceConfigsStream.

Parameters:
Name Type Attributes Description
options GetInstanceConfigsOptions <optional>

Query object for listing instance configs.
Returns:
Type Description
ReadableStream

A readable stream that emits instance configs.
See:
Example
const {Spanner} = require('@google-cloud/spanner');
const spanner = new Spanner();

spanner.getInstanceConfigsStream()
  .on('error', console.error)
  .on('data', function(instanceConfig) {})
  .on('end', function() {
    // All instances retrieved.
  });

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

getInstances(optionsopt, callbackopt) → {Promise.<GetInstancesResponse>}

Get a list of instances.

Wrapper around v1.InstanceAdminClient#listInstances.

Parameters:
Name Type Attributes Description
options GetInstancesOptions <optional>

Query object for listing instances.
callback GetInstancesCallback <optional>

Callback function.
Returns:
Type Description
Promise.<GetInstancesResponse>
See:
Example
const {Spanner} = require('@google-cloud/spanner');
const spanner = new Spanner();

spanner.getInstances(function(err, instances) {
  // `instances` is an array of `Instance` objects.
});

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

spanner.getInstances({
  gaxOptions: {
    autoPaginate: false,
  }
}, callback);

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

getInstancesStream(optionsopt) → {ReadableStream}

Get a list of Instance objects as a readable object stream.

Wrapper around v1.InstanceAdminClient#listInstances.

Parameters:
Name Type Attributes Description
options GetInstancesOptions <optional>

Query object for listing instances.
Returns:
Type Description
ReadableStream

A readable stream that emits Instance instances.
See:
Example
const {Spanner} = require('@google-cloud/spanner');
const spanner = new Spanner();

spanner.getInstancesStream()
  .on('error', console.error)
  .on('data', function(instance) {
    // `instance` is an `Instance` object.
  })
  .on('end', function() {
    // All instances retrieved.
  });

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

getSessionsStream(optionsopt) → {ReadableStream}

Get a list of sessions as a readable object stream.

Wrapper around v1.SpannerClient#listSessions

Parameters:
Name Type Attributes Description
options GetSessionsOptions <optional>

Options object for listing sessions.
Returns:
Type Description
ReadableStream

A readable stream that emits Session instances.
See:
Example
const {Spanner} = require('@google-cloud/spanner');
const spanner = new Spanner();

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

database.getSessionsStream()
  .on('error', console.error)
  .on('data', function(database) {
    // `sessions` is a `Session` object.
  })
  .on('end', function() {
    // All sessions retrieved.
  });

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

instance(name) → {Instance}

Get a reference to an Instance object.

Parameters:
Name Type Description
name string

The name of the instance.
Returns:
Type Description
Instance

An Instance object.
Throws:

If a name is not provided.

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

request(config, callbackopt) → {Promise}

Funnel all API requests through this method to be sure we have a project ID.

Parameters:
Name Type Attributes Description
config object

Configuration object.

Properties
Name Type Description
gaxOpts object

GAX options.
method function

The gax method to call.
reqOpts object

Request options.
callback function <optional>

Callback function.
Returns:
Type Description
Promise

requestStream(config, callbackopt) → {Stream}

Funnel all streaming API requests through this method to be sure we have a project ID.

Parameters:
Name Type Attributes Description
config object

Configuration object.

Properties
Name Type Description
gaxOpts object

GAX options.
method function

The gax method to call.
reqOpts object

Request options.
callback function <optional>

Callback function.
Returns:
Type Description
Stream