@google-cloud/spanner 1.4.3 » Class: Spanner

Spanner

class

Constructor

Spanner

new Spanner(options)

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.

Parameter
options	Optional ClientConfig Configuration options.

See also

Cloud Spanner Documentation

Cloud Spanner Concepts

Examples

Install the client library with npm:

npm install --save @google-cloud/spanner

Create a client that uses Application Default Credentials (ADC):

const client = new Spanner();

Create a client with explicit credentials:

const client = new Spanner({
  projectId: 'your-project-id',
  keyFilename: '/path/to/keyfile.json'
});

Full quickstart example:

View on GitHub

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

// Your Google Cloud Platform project ID
const projectId = 'YOUR_PROJECT_ID';

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

// Your Cloud Spanner instance ID
const instanceId = 'my-instance';

// Your Cloud Spanner database ID
const databaseId = 'my-database';

// 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
database
  .run(query)
  .then(results => {
    const rows = results[0];

    rows.forEach(row => console.log(row));
  })
  .catch(err => {
    console.error('ERROR:', err);
  });

Properties

COMMIT_TIMESTAMP

static

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.

Database

static

Constructor

Database class.

See also

Database

Instance

static

Constructor

Instance class.

See also

Instance

Session

static

Constructor

Session class.

See also

Session

SessionPool

static

Constructor

SessionPool class.

See also

SessionPool

Table

static

Constructor

Table class.

See also

Table

Transaction

static

Constructor

Transaction class.

See also

Transaction

TransactionRequest

static

Constructor

TransactionRequest class.

See also

TransactionRequest

Methods

date

static

date(value) returns object

Helper function to get a Cloud Spanner Date object.

Parameter
value	(string or date) The date as a string or Date object.

See also

Spanner#date

Returns

object 

Example

const Spanner = require('@google-cloud/spanner');
const date = Spanner.date('08-20-1969');

float

static

float(value) returns object

Helper function to get a Cloud Spanner Float64 object.

Parameter
value	(string or number) The float as a number or string.

See also

Spanner#float

Returns

object 

Example

const Spanner = require('@google-cloud/spanner');
const float = Spanner.float(10);

int

static

int(value) returns object

Helper function to get a Cloud Spanner Int64 object.

Parameter
value	(string or number) The int as a number or string.

See also

Spanner#int

Returns

object 

Example

const Spanner = require('@google-cloud/spanner');
const int = Spanner.int(10);

createInstance

createInstance(name, config, callback) returns Promise containing CreateInstanceResponse

Create an instance.

Wrapper around v1.InstanceAdminClient#createInstance.

Parameter
name	string The name of the instance to be created.
config	CreateInstanceRequest Configuration object.
callback	Optional CreateInstanceCallback Callback function.

See also

v1.InstanceAdminClient#createInstance

CreateInstace API Documentation

Throws

Error 

If a name is not provided.

Error 

If a configuration object is not provided.

Returns

Promise containing CreateInstanceResponse 

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) {
    var instance = data[0];
    var operation = data[1];
    return operation.promise();
  })
  .then(function() {
    // Instance created successfully.
  });

getDatabasesStream

getDatabasesStream(query) returns ReadableStream

Get a list of databases as a readable object stream.

Wrapper around v1.DatabaseAdminClient#listDatabases.

Parameter
query	Optional GetDatabasesRequest Query object for listing databases.

See also

v1.DatabaseAdminClient#listDatabases

ListDatabases API Documentation

Returns

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

getInstanceConfigs

getInstanceConfigs(query, callback) returns Promise containing GetInstanceConfigsResponse

Get a list of instance configs.

Wrapper around v1.InstanceAdminClient#listInstanceConfigs.

Parameter
query	Optional GetInstanceConfigsRequest Query object for listing instance configs.
callback	Optional GetInstanceConfigsCallback Callback function.

See also

v1.InstanceAdminClient#listInstanceConfigs

ListInstanceConfigs API Documentation

Returns

Promise containing GetInstanceConfigsResponse 

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

getInstanceConfigsStream(query) returns ReadableStream

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

Wrapper around v1.InstanceAdminClient#listInstanceConfigsStream.

Parameter
query	Optional GetInstanceConfigsRequest Query object for listing instance configs.

See also

v1.InstanceAdminClient#listInstanceConfigsStream

ListInstanceConfigs API Documentation

Returns

ReadableStream 

A readable stream that emits instance configs.

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

getInstances(query, callback) returns Promise containing GetInstancesResponse

Get a list of instances.

Wrapper around v1.InstanceAdminClient#listInstances.

Parameter
query	Optional GetInstancesRequest Query object for listing instances.
callback	Optional GetInstancesCallback Callback function.

See also

v1.InstanceAdminClient#listInstances

ListInstances API Documentation

Returns

Promise containing GetInstancesResponse 

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

getInstancesStream(query) returns ReadableStream

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

Wrapper around v1.InstanceAdminClient#listInstances.

Parameter
query	Optional GetInstancesRequest Query object for listing instances.

See also

v1.InstanceAdminClient#listInstances

ListInstances API Documentation

Returns

ReadableStream 

A readable stream that emits Instance instances.

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

instance(name) returns Instance

Get a reference to an Instance object.

Parameter
name	string The name of the instance.

Throws

Error 

If a name is not provided.

Returns

Instance 

An Instance object.

Example

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

operation

operation(name) returns Operation

Get a reference to an Operation object.

Parameter
name	string The name of the operation.

Throws

Error 

If a name is not provided.

Returns

Operation 

An Operation object.

Example

const Spanner = require('@google-cloud/spanner');
const spanner = new Spanner();
const operation = spanner.operation('operation-name');

request

request(config, callback)

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

Parameter
config	object Configuration object. Values in config have the following properties: Parameter gaxOpts object GAX options. method function() The gax method to call. reqOpts object Request options.
callback	Optional function() Callback function.

requestStream

requestStream(config, callback)

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

Parameter
config	object Configuration object. Values in config have the following properties: Parameter gaxOpts object GAX options. method function() The gax method to call. reqOpts object Request options.
callback	Optional function() Callback function.