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
Install the client library with <a
href="https://www.npmjs.com/">npm</a>:
```
npm install --save @google-cloud/spanner
```
Create a client that uses <a
href="https://cloud.google.com/docs/authentication/production#providing_credentials_to_your_application">Application
Default Credentials (ADC)</a>:
```
const client = new Spanner();
```
Create a client with <a
href="https://cloud.google.com/docs/authentication/production#obtaining_and_providing_service_account_credentials_manually">explicit
credentials</a>:
```
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

batchWriteAtLeastOnce(mutationGroupsopt, optionsopt) → {ReadableStream}

Write a batch of mutations to Spanner.

All mutations in a group are committed atomically. However, mutations across groups can be committed non-atomically in an unspecified order and thus, they must be independent of each other. Partial failure is possible, i.e., some groups may have been committed successfully, while some may have failed. The results of individual batches are streamed into the response as the batches are applied.

batchWriteAtLeastOnce requests are not replay protected, meaning that each mutation group may be applied more than once. Replays of non-idempotent mutations may have undesirable effects. For example, replays of an insert mutation may produce an already exists error or if you use generated or commit timestamp-based keys, it may result in additional rows being added to the mutation's table. We recommend structuring your mutation groups to be idempotent to avoid this issue.

Parameters:
Name Type Attributes Description
mutationGroups Array.<MutationGroup> <optional>

The group of mutations to be applied.
options BatchWriteOptions <optional>

Options object for batch write request.
Returns:
Type Description
ReadableStream

An object stream which emits BatchWriteResponse on 'data' event.
Example
```
const {Spanner} = require('@google-cloud/spanner');
const spanner = new Spanner();

const instance = spanner.instance('my-instance');
const database = instance.database('my-database');
const mutationGroup = new MutationGroup();
mutationGroup.insert('Singers', {
 SingerId: '1',
 FirstName: 'Marc',
 LastName: 'Richards',
 });

database.batchWriteAtLeastOnce([mutationGroup])
  .on('error', console.error)
  .on('data', response => {
       console.log('response: ', response);
  })
  .on('end', () => {
       console.log('Request completed successfully');
  });

//-
// If you anticipate many results, you can end a stream early to prevent
// unnecessary processing and API requests.
//-
database.batchWriteAtLeastOnce()
  .on('data', response => {
    this.end();
  });
```

close()

Closes this Spanner client and cleans up all resources used by it.

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

getDatabaseAdminClient() → {v1.DatabaseAdminClient}

Gets the DatabaseAdminClient object. The returned DatabaseAdminClient object is a managed, shared instance and should not be manually closed.

Returns:
Type Description
v1.DatabaseAdminClient

The DatabaseAdminClient object.
Example
```
const {Spanner} = require('@google-cloud/spanner');
const spanner = new Spanner({
   projectId: projectId,
});
const databaseAdminClient = spanner.getDatabaseAdminClient();
```

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

getInstanceAdminClient() → {v1.InstanceAdminClient}

Gets the InstanceAdminClient object. The returned InstanceAdminClient object is a shared, managed instance and should not be manually closed.

Returns:
Type Description
v1.InstanceAdminClient

The InstanceAdminClient object
Example
```
const {Spanner} = require('@google-cloud/spanner');
const spanner = new Spanner({
   projectId: projectId,
 });
const instanceAdminClient = spanner.getInstanceAdminClient();
```

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

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
GoogleError
Example
```
const {Spanner} = require('@google-cloud/spanner');
const spanner = new Spanner();
const instance = spanner.instance('my-instance');
```

instanceConfig(name) → {InstanceConfig}

Get a reference to an InstanceConfig object.

Parameters:
Name Type Description
name string

The name of the instance config.
Returns:
Type Description
InstanceConfig

An InstanceConfig object.
Throws:

If a name is not provided.

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

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

(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) float32(value) → {Float32}

Helper function to get a Cloud Spanner Float32 object.

Parameters:
Name Type Description
value string | number

The float as a number or string.
Returns:
Type Description
Float32
Example
```
const {Spanner} = require('@google-cloud/spanner');
const float = Spanner.float32(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) pgJsonb(value) → {PGJsonb}

Helper function to get a Cloud Spanner pgJsonb object.

Parameters:
Name Type Description
value object | string

The pgJsonb value as a string or object.
Returns:
Type Description
PGJsonb
Example
```
const {Spanner} = require('@google-cloud/spanner');
const pgJsonb1 = Spanner.pgJsonb({rating: 6});
const pgJsonb2 = Spanner.pgJsonb(`[
        {
          "name": null,
          "open": true
        }]`)
```

(static) pgNumeric(value) → {PGNumeric}

Helper function to get a Cloud Spanner pgNumeric object.

Parameters:
Name Type Description
value string

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

(static) protoEnum(params) → {ProtoEnum}

Helper function to get a Cloud Spanner proto enum object.

Parameters:
Name Type Description
params IProtoEnumParams

The proto enum value params in the format of
Returns:
Type Description
ProtoEnum
Example
```
const {Spanner} = require('@google-cloud/spanner');
const protoEnum = Spanner.protoEnum({
  value: 'ROCK',
  enumObject: music.Genre,
  fullName: "examples.spanner.music.Genre"
});
```

(static) protoMessage(params) → {ProtoMessage}

Helper function to get a Cloud Spanner proto Message object.

Parameters:
Name Type Description
params IProtoMessageParams

The proto message value params
Returns:
Type Description
ProtoMessage
Example
```
const {Spanner} = require('@google-cloud/spanner');
const protoMessage = Spanner.protoMessage({
  value: singerInfo,
  messageFunction: music.SingerInfo,
  fullName: "examples.spanner.music.SingerInfo"
});
```

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