[Cloud Spanner]( https://cloud.google.com/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.
Inheritance
GrpcService > SpannerPackage
@google-cloud/spannerExamples
Install the client library with a href="https://www.npmjs.com/" npm:
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):
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:
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
));
Constructors
(constructor)(options)
constructor
(
options
?:
SpannerOptions
);
Constructs a new instance of the Spanner
class
Properties
auth
auth
:
GoogleAuth
;
clients_
clients_
:
Map<string
,
{}>;
COMMIT_TIMESTAMP
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.
{string}
directedReadOptions
directedReadOptions
:
google
.
spanner
.
v1
.
IDirectedReadOptions
|
null
;
GOOGLE_STANDARD_SQL
static
GOOGLE_STANDARD_SQL
:
google
.
spanner
.
admin
.
database
.
v1
.
DatabaseDialect
;
instanceConfigs_
instanceConfigs_
:
Map<string
,
InstanceConfig
> ;
instances_
instances_
:
Map<string
,
Instance
> ;
options
options
:
GoogleAuthOptions
;
POSTGRESQL
static
POSTGRESQL
:
google
.
spanner
.
admin
.
database
.
v1
.
DatabaseDialect
;
projectFormattedName_
projectFormattedName_
:
string
;
projectIdReplaced_
projectIdReplaced_
:
boolean
;
resourceHeader_
resourceHeader_
:
{
[
k
:
string
]
:
string
;
};
routeToLeaderEnabled
routeToLeaderEnabled
:
boolean
;
Methods
close()
close
()
:
void
;
Closes this Spanner client and cleans up all resources used by it.
Returns
Type
Description
void
createInstance(name, config)
createInstance
(
name
:
string
,
config
:
CreateInstanceRequest
)
:
Promise<CreateInstanceResponse>
;
Create an instance.
Wrapper around .
Parameters
Name
Description
name
string
The name of the instance to be created.
config
Returns
Type
Description
Promise
< CreateInstanceResponse
>
{Promise
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.
});
createInstance(name, config, callback)
createInstance
(
name
:
string
,
config
:
CreateInstanceRequest
,
callback
:
CreateInstanceCallback
)
:
void
;
Parameters
Name
Description
name
string
config
callback
CreateInstanceCallback
Returns
Type
Description
void
createInstanceConfig(name, config)
createInstanceConfig
(
name
:
string
,
config
:
CreateInstanceConfigRequest
)
:
Promise<CreateInstanceConfigResponse>
;
Create an instance config.
Wrapper around .
Parameters
Name
Description
name
string
The name of the instance config to be created.
config
Returns
Type
Description
Promise
< CreateInstanceConfigResponse
>
{Promise
const
{
Spanner
}
=
require
(
' @google-cloud/spanner
'
);
const
spanner
=
new
Spanner
();
const
[
baseInstanceConfig
]
=
await
spanner
.
getInstanceConfig
(
baseInstanceConfigId
);
const
config
=
{
baseConfig
:
baseInstanceConfig
.
name
,
replicas
:
baseInstanceConfig
.
replicas
.
concat
(
baseInstanceConfig
.
optionalReplicas
[
0
])
};
function
callback
(
err
,
instance
,
operation
,
apiResponse
)
{
if
(
err
)
{
// Error handling omitted.
}
operation
.
on
(
'error'
,
function
(
err
)
{})
.
on
(
'complete'
,
function
()
{
// Instance created successfully.
});
}
spanner
.
createInstanceConfig
(
'custom-new-instance-config'
,
config
,
callback
);
//-
// If the callback is omitted, we'll return a Promise.
//-
spanner
.
createInstanceConfig
(
'custom-new-instance-config'
,
config
)
.
then
(
function
(
data
)
{
const
instanceConfig
=
data
[
0
];
const
operation
=
data
[
1
];
return
operation
.
promise
();
})
.
then
(
function
()
{
// Instance config created successfully.
});
createInstanceConfig(name, config, callback)
createInstanceConfig
(
name
:
string
,
config
:
CreateInstanceConfigRequest
,
callback
:
CreateInstanceConfigCallback
)
:
void
;
Parameters
Name
Description
name
string
config
callback
CreateInstanceConfigCallback
Returns
Type
Description
void
date(dateString)
static
date
(
dateString
?:
string
)
:
any
;
Parameter
Name
Description
dateString
string
Returns
Type
Description
any
date(year, month, date)
static
date
(
year
:
number
,
month
:
number
,
date
:
number
)
:
any
;
Parameters
Name
Description
year
number
month
number
date
number
Returns
Type
Description
any
float(value)
static
float
(
value
:
any
)
:
Float
;
Helper function to get a Cloud Spanner Float64 object.
Parameter
Name
Description
value
any
The float as a number or string.
const
{
Spanner
}
=
require
(
' @google-cloud/spanner
'
);
const
float
=
Spanner
.
float
(
10
);
getInstanceConfig(name)
getInstanceConfig
(
name
:
string
)
:
Promise<GetInstanceConfigResponse>
;
Get a specific instance config.
Wrapper around .
Parameter
Name
Description
name
string
The name of the instance config to get.
const
{
Spanner
}
=
require
(
' @google-cloud/spanner
'
);
const
spanner
=
new
Spanner
();
spanner
.
getInstanceConfig
(
'nam6'
,
function
(
err
,
instanceConfig
)
{
// `instanceConfig` is an instance configuration descriptor.
});
//-
// If the callback is omitted, we'll return a Promise.
//-
spanner
.
getInstanceConfig
().
then
(
function
(
data
)
{
const
instanceConfig
=
data
[
0
];
});
getInstanceConfig(name, options)
getInstanceConfig
(
name
:
string
,
options
:
GetInstanceConfigOptions
)
:
Promise<GetInstanceConfigResponse>
;
getInstanceConfig(name, callback)
getInstanceConfig
(
name
:
string
,
callback
:
GetInstanceConfigCallback
)
:
void
;
Returns
Type
Description
void
getInstanceConfig(name, options, callback)
getInstanceConfig
(
name
:
string
,
options
:
GetInstanceConfigOptions
,
callback
:
GetInstanceConfigCallback
)
:
void
;
Parameters
Name
Description
name
string
options
callback
Returns
Type
Description
void
getInstanceConfigOperations(options)
getInstanceConfigOperations
(
options
?:
GetInstanceConfigOperationsOptions
)
:
Promise<GetInstanceConfigOperationsResponse>
;
List pending and completed instance config operations.
Parameter
Name
Description
options
const
{
Spanner
}
=
require
(
' @google-cloud/spanner
'
);
const
spanner
=
new
Spanner
();
const
[
operations
]
=
await
spanner
.
getInstanceConfigOperations
();
//-
// To manually handle pagination, set autoPaginate:false in gaxOptions.
//-
let
pageToken
=
undefined
;
do
{
const
[
operations
,
,
response
]
=
await
spanner
.
getInstanceConfigOperations
({
pageSize
:
3
,
pageToken
,
gaxOptions
:
{
autoPaginate
:
false
},
});
operations
.
forEach
(
operation
=
>
{
// Do something with operation
});
pageToken
=
response
.
nextPageToken
;
}
while
(
pageToken
);
getInstanceConfigOperations(callback)
getInstanceConfigOperations
(
callback
:
GetInstanceConfigOperationsCallback
)
:
void
;
Returns
Type
Description
void
getInstanceConfigOperations(options, callback)
getInstanceConfigOperations
(
options
:
GetInstanceConfigOperationsOptions
,
callback
:
GetInstanceConfigOperationsCallback
)
:
void
;
Parameters
Name
Description
callback
Returns
Type
Description
void
getInstanceConfigs(query)
getInstanceConfigs
(
query
?:
GetInstanceConfigsOptions
)
:
Promise<GetInstanceConfigsResponse>
;
Get a list of instance configs.
Wrapper around .
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
({
gaxOptions
:
{
autoPaginate
:
false
,
}
},
callback
);
//-
// If the callback is omitted, we'll return a Promise.
//-
spanner
.
getInstanceConfigs
().
then
(
function
(
data
)
{
const
instanceConfigs
=
data
[
0
];
});
getInstanceConfigs(callback)
getInstanceConfigs
(
callback
:
GetInstanceConfigsCallback
)
:
void
;
Returns
Type
Description
void
getInstanceConfigs(query, callback)
getInstanceConfigs
(
query
:
GetInstanceConfigsOptions
,
callback
:
GetInstanceConfigsCallback
)
:
void
;
Returns
Type
Description
void
getInstanceConfigsStream(options)
getInstanceConfigsStream
(
options
?:
GetInstanceConfigsOptions
)
:
NodeJS
.
ReadableStream
;
Get a list of instance configs as a readable object stream.
Wrapper around .
Parameter
Name
Description
options
Returns
Type
Description
NodeJS.ReadableStream
{ReadableStream} A readable stream that emits instance configs.
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(options)
getInstances
(
options
?:
GetInstancesOptions
)
:
Promise<GetInstancesResponse>
;
Get a list of instances.
Wrapper around .
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
({
gaxOptions
:
{
autoPaginate
:
false
,
}
},
callback
);
//-
// If the callback is omitted, we'll return a Promise.
//-
spanner
.
getInstances
().
then
(
function
(
data
)
{
const
instances
=
data
[
0
];
});
getInstances(callback)
getInstances
(
callback
:
GetInstancesCallback
)
:
void
;
Returns
Type
Description
void
getInstances(query, callback)
getInstances
(
query
:
GetInstancesOptions
,
callback
:
GetInstancesCallback
)
:
void
;
Returns
Type
Description
void
getInstancesStream(options)
getInstancesStream
(
options
?:
GetInstancesOptions
)
:
NodeJS
.
ReadableStream
;
Get a list of Instance objects as a readable object stream.
Wrapper around .
Returns
Type
Description
NodeJS.ReadableStream
{ReadableStream} A readable stream that emits Instance instances.
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
();
});
getSpannerEmulatorHost()
static
getSpannerEmulatorHost
()
:
{
endpoint
:
string
;
port
?:
number
;
}
|
undefined
;
Gets the configured Spanner emulator host from an environment variable.
Returns
Type
Description
{
endpoint: string;
port?: number;
} | undefined
instance(name)
instance
(
name
:
string
)
:
Instance
;
Get a reference to an Instance object.
Parameter
Name
Description
name
string
The name of the instance.
const
{
Spanner
}
=
require
(
' @google-cloud/spanner
'
);
const
spanner
=
new
Spanner
();
const
instance
=
spanner
.
instance
(
'my-instance'
);
instanceConfig(name)
instanceConfig
(
name
:
string
)
:
InstanceConfig
;
Get a reference to an InstanceConfig object.
Parameter
Name
Description
name
string
The name of the instance config.
const
{
Spanner
}
=
require
(
' @google-cloud/spanner
'
);
const
spanner
=
new
Spanner
();
const
instanceConfig
=
spanner
.
instanceConfig
(
'my-instance-config'
);
int(value)
static
int
(
value
:
any
)
:
Int
;
Helper function to get a Cloud Spanner Int64 object.
Parameter
Name
Description
value
any
The int as a number or string.
const
{
Spanner
}
=
require
(
' @google-cloud/spanner
'
);
const
int
=
Spanner
.
int
(
10
);
numeric(value)
static
numeric
(
value
:
any
)
:
Numeric
;
Helper function to get a Cloud Spanner Numeric object.
Parameter
Name
Description
value
any
The numeric value as a string.
const
{
Spanner
}
=
require
(
' @google-cloud/spanner
'
);
const
numeric
=
Spanner
.
numeric
(
"3.141592653"
);
pgJsonb(value)
static
pgJsonb
(
value
:
any
)
:
PGJsonb
;
Helper function to get a Cloud Spanner pgJsonb object.
Parameter
Name
Description
value
any
The pgJsonb value as a string or object.
Returns
Type
Description
PGJsonb
{PGJsonb}
const
{
Spanner
}
=
require
(
' @google-cloud/spanner
'
);
const
pgJsonb1
=
Spanner
.
pgJsonb
({
rating
:
6
});
const
pgJsonb2
=
Spanner
.
pgJsonb
(
`[
{
"name": null,
"open": true
}]`
)
pgNumeric(value)
static
pgNumeric
(
value
:
any
)
:
PGNumeric
;
Helper function to get a Cloud Spanner pgNumeric object.
Parameter
Name
Description
value
any
The pgNumeric value as a string.
const
{
Spanner
}
=
require
(
' @google-cloud/spanner
'
);
const
pgNumeric
=
Spanner
.
pgNumeric
(
"3.141592653"
);
prepareGapicRequest_(config, callback)
prepareGapicRequest_
(
config
:
any
,
callback
:
any
)
:
void
;
Prepare a gapic request. This will cache the GAX client and replace {{projectId}} placeholders, if necessary.
Parameters
Name
Description
config
any
Request config
callback
any
Callback function
Returns
Type
Description
void
request(config, callback)
request
(
config
:
any
,
callback
?:
any
)
:
any
;
Funnel all API requests through this method to be sure we have a project ID.
Parameters
Name
Description
config
any
Configuration object.
callback
any
Callback function.
Returns
Type
Description
any
{Promise}
requestStream(config)
requestStream
(
config
:
any
)
:
any
;
Funnel all streaming API requests through this method to be sure we have a project ID.
Parameter
Name
Description
config
any
Configuration object.
Returns
Type
Description
any
{Stream}
struct(value)
static
struct
(
value
?:
any
)
:
Struct
;
Helper function to get a Cloud Spanner Struct object.
Parameter
Name
Description
value
any
The struct as a JSON object.
const
{
Spanner
}
=
require
(
' @google-cloud/spanner
'
);
const
struct
=
Spanner
.
struct
({
user
:
'bob'
,
age
:
32
});
timestamp(value)
static
timestamp
(
value
?:
string
|
number
|
p
.
ITimestamp
|
PreciseDate
)
:
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.**
Parameter
Name
Description
value
string | number | common.ITimestamp
| PreciseDate
Returns
Type
Description
PreciseDate
{external:PreciseDate}
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
());
