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.

Source:
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

(static) COMMIT_TIMESTAMP :string

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.

Source:

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.

Source:
Example
const {Spanner} = require('@google-cloud/spanner');
const date = Spanner.date('08-20-1969');

(static) float(value) → {object}

Helper function to get a Cloud Spanner Float64 object.

Parameters:
Name Type Description
value string | number

The float as a number or string.

Source:
Example
const {Spanner} = require('@google-cloud/spanner');
const float = Spanner.float(10);

(static) getSpannerEmulatorHost()

Gets the configured Spanner emulator host from an environment variable.

Source:

(static) int(value) → {object}

Helper function to get a Cloud Spanner Int64 object.

Parameters:
Name Type Description
value string | number

The int as a number or string.

Source:
Example
const {Spanner} = require('@google-cloud/spanner');
const int = Spanner.int(10);

(static) struct(value) → {object}

Helper function to get a Cloud Spanner Struct object.

Parameters:
Name Type Description
value object

The struct as a JSON object.

Source:
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 <optional>

Either a RFC 3339 timestamp formatted string or google.protobuf.Timestamp object.

Source:
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.

Source:
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.
  });

getDatabasesStream(queryopt) → {ReadableStream}

Get a list of databases as a readable object stream.

Wrapper around v1.DatabaseAdminClient#listDatabases.

Parameters:
Name Type Attributes Description
query GetDatabasesRequest <optional>

Query object for listing databases.

Source:
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(queryopt, callbackopt) → {Promise.<GetInstanceConfigsResponse>}

Get a list of instance configs.

Wrapper around v1.InstanceAdminClient#listInstanceConfigs.

Parameters:
Name Type Attributes Description
query GetInstanceConfigsRequest <optional>

Query object for listing instance configs.

callback GetInstanceConfigsCallback <optional>

Callback function.

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

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

getInstanceConfigsStream(queryopt) → {ReadableStream}

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

Wrapper around v1.InstanceAdminClient#listInstanceConfigsStream.

Parameters:
Name Type Attributes Description
query GetInstanceConfigsRequest <optional>

Query object for listing instance configs.

Source:
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(queryopt, callbackopt) → {Promise.<GetInstancesResponse>}

Get a list of instances.

Wrapper around v1.InstanceAdminClient#listInstances.

Parameters:
Name Type Attributes Description
query GetInstancesRequest <optional>

Query object for listing instances.

callback GetInstancesCallback <optional>

Callback function.

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

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

getInstancesStream(queryopt) → {ReadableStream}

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

Wrapper around v1.InstanceAdminClient#listInstances.

Parameters:
Name Type Attributes Description
query GetInstancesRequest <optional>

Query object for listing instances.

Source:
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();
  });

instance(name) → {Instance}

Get a reference to an Instance object.

Parameters:
Name Type Description
name string

The name of the instance.

Source:
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');

operation(name) → {Operation}

Get a reference to an Operation object.

Parameters:
Name Type Description
name string

The name of the operation.

Source:
Throws:

If a name is not provided.

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

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.

Source:

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.

Source: