Constructor
new Spanner(optionsopt)
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
options |
ClientConfig |
<optional> |
Configuration options. |
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'
});
```
// 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:
-
- v1.DatabaseAdminClient#listBackups
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:
-
- v1.DatabaseAdminClient#listDatabases
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. |
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:
-
- v1.InstanceAdminClient#listInstances
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:
-
- v1.SpannerClient#listSessions
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
|
|||||||||||||
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
|
|||||||||||||
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 |
(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 |
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());
```