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

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