The Instance class represents a [Cloud Spanner instance]( https://cloud.google.com/spanner/docs/instances ).
Create an Instance
object to interact with a Cloud Spanner instance.
Inheritance
common .GrpcServiceObject > InstancePackage
@google-cloud/spannerExample
const
{
Spanner
}
=
require
(
' @google-cloud/spanner
'
);
const
spanner
=
new
Spanner
();
const
instance
=
spanner
.
instance
(
'my-instance'
);
Constructors
(constructor)(spanner, name)
constructor
(
spanner
:
Spanner
,
name
:
string
);
Constructs a new instance of the Instance
class
Properties
databases_
databases_
:
Map<string
,
Database
> ;
formattedName_
formattedName_
:
string
;
metadata
metadata
?:
IInstance
;
request
request
:
InstanceRequest
;
requestStream
requestStream
:
(
config
:
RequestConfig
)
=
>
Duplex
;
resourceHeader_
resourceHeader_
:
{
[
k
:
string
]
:
string
;
};
Methods
backup(backupId)
backup
(
backupId
:
string
)
:
Backup
;
Get a reference to a Backup object.
Parameter
Name
Description
backupId
string
The name of the backup. {Backup} A Backup object.
const
{
Spanner
}
=
require
(
' @google-cloud/spanner
'
);
const
spanner
=
new
Spanner
();
const
instance
=
spanner
.
instance
(
'my-instance'
);
const
backup
=
instance
.
backup
(
'my-backup'
);
copyBackup(sourceBackupId, backupId, options, callback)
copyBackup
(
sourceBackupId
:
string
,
backupId
:
string
,
options
:
CopyBackupOptions
,
callback
?:
CopyBackupCallback
)
:
Promise<CopyBackupResponse>
|
void
;
CopyBackupCallback
Parameters
Name
Description
sourceBackupId
string
Full path of the source backup to be copied.
backupId
string
The name of the backup.
options
CopyBackupOptions
callback
CopyBackupCallback
Returns
Type
Description
Promise
< CopyBackupResponse
> | void
const
{
Spanner
}
=
require
(
' @google-cloud/spanner
'
);
const
spanner
=
new
Spanner
();
const
instance
=
spanner
.
instance
(
'my-instance'
);
const
backup
=
instance
.
copyBackup
(
'my-source-backup'
,
'my-backup'
,{
expireTime
:
expireTime
,
encryptionConfig
:
{
encryptionType
:
'CUSTOMER_MANAGED_ENCRYPTION'
,
kmsKeyName
:
'projects/my-project-id/my-region/keyRings/my-key-ring/cryptoKeys/my-key'
,
},);
createDatabase(name, options)
createDatabase
(
name
:
string
,
options
?:
CreateDatabaseOptions
)
:
Promise<CreateDatabaseResponse>
;
Create a database in this instance.
Wrapper around .
Parameters
Name
Description
name
string
The name of the database to create.
options
CreateDatabaseOptions
Configuration object.
Returns
Type
Description
Promise
< CreateDatabaseResponse
>
{Promise
const
{
Spanner
}
=
require
(
' @google-cloud/spanner
'
);
const
spanner
=
new
Spanner
();
const
instance
=
spanner
.
instance
(
'my-instance'
);
function
callback
(
err
,
database
,
operation
,
apiResponse
)
{
if
(
err
)
{
// Error handling omitted.
}
operation
.
on
(
'error'
,
function
(
err
)
{})
.
on
(
'complete'
,
function
()
{
// Database created successfully.
});
}
instance
.
createDatabase
(
'new-database-name'
,
callback
);
//-
// Set the schema for the database.
//-
instance
.
createDatabase
(
'new-database-name'
,
{
schema
:
'CREATE TABLE Singers ('
+
' SingerId STRING(1024) NOT NULL,'
+
' Name STRING(1024),'
+
') PRIMARY KEY(SingerId)'
},
callback
);
//-
// If the callback is omitted, we'll return a Promise.
//-
instance
.
createDatabase
(
'new-database-name'
)
.
then
(
function
(
data
)
{
const
database
=
data
[
0
];
const
operation
=
data
[
1
];
return
operation
.
promise
();
})
.
then
(
function
()
{
// Database created successfully.
});
Full example:
// Imports the Google Cloud client library
const
{
Spanner
}
=
require
(
' @google-cloud/spanner
'
);
/**
* TODO(developer): Uncomment the following lines before running the sample.
*/
// const projectId = 'my-project-id';
// const instanceId = 'my-instance';
// const databaseId = 'my-database';
// Creates a client
const
spanner
=
new
Spanner
({
projectId
:
projectId
,
});
// Gets a reference to a Cloud Spanner instance
const
instance
=
spanner
.
instance
(
instanceId
);
// Note: Cloud Spanner interprets Node.js numbers as FLOAT64s, so they
// must be converted to strings before being inserted as INT64s
const
request
=
{
schema
:
[
`CREATE TABLE Singers (
SingerId INT64 NOT NULL,
FirstName STRING(1024),
LastName STRING(1024),
SingerInfo BYTES(MAX),
FullName STRING(2048) AS (ARRAY_TO_STRING([FirstName, LastName], " ")) STORED,
) PRIMARY KEY (SingerId)`
,
`CREATE TABLE Albums (
SingerId INT64 NOT NULL,
AlbumId INT64 NOT NULL,
AlbumTitle STRING(MAX)
) PRIMARY KEY (SingerId, AlbumId),
INTERLEAVE IN PARENT Singers ON DELETE CASCADE`
,
],
};
// Creates a database
const
[
database
,
operation
]
=
await
instance
.
createDatabase
(
databaseId
,
request
);
console
.
log
(
`Waiting for operation on
${
database
.
id
}
to complete...`
);
await
operation
.
promise
();
console
.
log
(
`Created database
${
databaseId
}
on instance
${
instanceId
}
.`
);
createDatabase(name, callback)
createDatabase
(
name
:
string
,
callback
:
CreateDatabaseCallback
)
:
void
;
Parameters
Name
Description
name
string
callback
CreateDatabaseCallback
Returns
Type
Description
void
createDatabase(name, options, callback)
createDatabase
(
name
:
string
,
options
:
CreateDatabaseOptions
,
callback
:
CreateDatabaseCallback
)
:
void
;
Parameters
Name
Description
name
string
options
CreateDatabaseOptions
callback
CreateDatabaseCallback
Returns
Type
Description
void
database(name, poolOptions, queryOptions)
database
(
name
:
string
,
poolOptions
?:
SessionPoolOptions
|
SessionPoolConstructor
,
queryOptions
?:
spannerClient
.
spanner
.
v1
.
ExecuteSqlRequest
.
IQueryOptions
)
:
Database
;
Get a reference to a Database object.
Parameters
Name
Description
name
string
The name of the instance.
poolOptions
SessionPoolOptions
| SessionPoolConstructor
Session pool configuration options.
queryOptions
IQueryOptions
Default query options to use with the database. These options will be overridden by any query options set in environment variables or that are specified on a per-query basis. {Database} A Database object.
const
{
Spanner
}
=
require
(
' @google-cloud/spanner
'
);
const
spanner
=
new
Spanner
();
const
instance
=
spanner
.
instance
(
'my-instance'
);
const
database
=
instance
.
database
(
'my-database'
);
delete(gaxOptions)
delete
(
gaxOptions
?:
CallOptions
)
:
Promise<DeleteInstanceResponse>
;
Delete the instance.
Wrapper around .
Parameter
Name
Description
gaxOptions
Returns
Type
Description
Promise
< DeleteInstanceResponse
>
{Promise
const
{
Spanner
}
=
require
(
' @google-cloud/spanner
'
);
const
spanner
=
new
Spanner
();
const
instance
=
spanner
.
instance
(
'my-instance'
);
instance
.
delete
(
function
(
err
,
apiResponse
)
{
if
(
err
)
{
// Error handling omitted.
}
// Instance was deleted successfully.
});
//-
// If the callback is omitted, we'll return a Promise.
//-
instance
.
delete
().
then
(
function
(
data
)
{
const
apiResponse
=
data
[
0
];
});
delete(callback)
delete
(
callback
:
DeleteInstanceCallback
)
:
void
;
Parameter
Name
Description
callback
DeleteInstanceCallback
Returns
Type
Description
void
delete(gaxOptions, callback)
delete
(
gaxOptions
:
CallOptions
,
callback
:
DeleteInstanceCallback
)
:
void
;
Parameters
Name
Description
gaxOptions
CallOptions
callback
DeleteInstanceCallback
Returns
Type
Description
void
exists(gaxOptions)
exists
(
gaxOptions
?:
CallOptions
)
:
Promise<ExistsInstanceResponse>
;
Check if an instance exists.
Instance#exists
Parameter
Name
Description
gaxOptions
Returns
Type
Description
Promise
< ExistsInstanceResponse
>
{Promise
const
{
Spanner
}
=
require
(
' @google-cloud/spanner
'
);
const
spanner
=
new
Spanner
();
const
instance
=
spanner
.
instance
(
'my-instance'
);
instance
.
exists
(
function
(
err
,
exists
)
{});
//-
// If the callback is omitted, we'll return a Promise.
//-
instance
.
exists
().
then
(
function
(
data
)
{
const
exists
=
data
[
0
];
});
exists(callback)
exists
(
callback
:
ExistsInstanceCallback
)
:
void
;
Parameter
Name
Description
callback
ExistsInstanceCallback
Returns
Type
Description
void
exists(gaxOptions, callback)
exists
(
gaxOptions
:
CallOptions
,
callback
:
ExistsInstanceCallback
)
:
void
;
Parameters
Name
Description
gaxOptions
CallOptions
callback
ExistsInstanceCallback
Returns
Type
Description
void
formatName_(projectId, name)
static
formatName_
(
projectId
:
string
,
name
:
string
)
:
string
;
Format the instance name to include the project ID.
Parameters
Name
Description
projectId
string
The project ID.
name
string
The instance name.
Returns
Type
Description
string
{string}
Instance
.
formatName_
(
'grape-spaceship-123'
,
'my-instance'
);
// 'projects/grape-spaceship-123/instances/my-instance'
get(options)
get
(
options
?:
GetInstanceConfig
)
:
Promise<GetInstanceResponse>
;
Get an instance if it exists.
You may optionally use this to "get or create" an object by providing an object with autoCreate
set to true
. Any extra configuration that is normally required for the create
method must be contained within this object as well.
Parameter
Name
Description
options
GetInstanceConfig
Configuration object.
Returns
Type
Description
Promise
< GetInstanceResponse
>
{Promise
const
{
Spanner
}
=
require
(
' @google-cloud/spanner
'
);
const
spanner
=
new
Spanner
();
const
instance
=
spanner
.
instance
(
'my-instance'
);
instance
.
get
(
function
(
err
,
instance
,
apiResponse
)
{
// `instance.metadata` has been populated.
});
//-
// If the callback is omitted, we'll return a Promise.
//-
instance
.
get
().
then
(
function
(
data
)
{
const
instance
=
data
[
0
];
const
apiResponse
=
data
[
0
];
});
get(callback)
get
(
callback
:
GetInstanceCallback
)
:
void
;
Parameter
Name
Description
callback
GetInstanceCallback
Returns
Type
Description
void
get(options, callback)
get
(
options
:
GetInstanceConfig
,
callback
:
GetInstanceCallback
)
:
void
;
Parameters
Name
Description
options
GetInstanceConfig
callback
GetInstanceCallback
Returns
Type
Description
void
getBackupOperations(options)
getBackupOperations
(
options
?:
GetBackupOperationsOptions
)
:
Promise<GetBackupOperationsResponse>
;
GetBackupOperationsCallback
Parameter
Name
Description
options
GetBackupOperationsOptions
Returns
Type
Description
Promise
< GetBackupOperationsResponse
>
getBackupOperations(callback)
getBackupOperations
(
callback
:
GetBackupOperationsCallback
)
:
void
;
Parameter
Name
Description
callback
GetBackupOperationsCallback
Returns
Type
Description
void
getBackupOperations(options, callback)
getBackupOperations
(
options
:
GetBackupOperationsOptions
,
callback
:
GetBackupOperationsCallback
)
:
void
;
Parameters
Name
Description
options
GetBackupOperationsOptions
callback
GetBackupOperationsCallback
Returns
Type
Description
void
getBackups(options)
getBackups
(
options
?:
GetBackupsOptions
)
:
Promise<GetBackupsResponse>
;
List backups on the instance.
Both completed and in-progress backups are listed if no filter is supplied.
Parameter
Name
Description
options
GetBackupsOptions
The query object for listing backups.
Returns
Type
Description
Promise
< GetBackupsResponse
>
{Promise
const
{
Spanner
}
=
require
(
' @google-cloud/spanner
'
);
const
spanner
=
new
Spanner
();
const
instance
=
spanner
.
instance
(
'my-instance'
);
const
[
backups
]
=
await
instance
.
getBackups
();
//-
// To manually handle pagination, set autoPaginate:false in gaxOptions.
//-
let
pageToken
=
undefined
;
do
{
const
[
backups
,
,
response
]
=
await
instance
.
getBackups
({
pageSize
:
3
,
pageToken
,
gaxOptions
:
{
autoPaginate
:
false
},
});
backups
.
forEach
(
backup
=
>
{
// Do something with backup
});
pageToken
=
response
.
nextPageToken
;
}
while
(
pageToken
);
getBackups(callback)
getBackups
(
callback
:
GetBackupsCallback
)
:
void
;
Parameter
Name
Description
callback
GetBackupsCallback
Returns
Type
Description
void
getBackups(options, callback)
getBackups
(
options
:
GetBackupsOptions
,
callback
:
GetBackupsCallback
)
:
void
;
Parameters
Name
Description
options
GetBackupsOptions
callback
GetBackupsCallback
Returns
Type
Description
void
getBackupsStream(options)
getBackupsStream
(
options
?:
GetBackupsOptions
)
:
NodeJS
.
ReadableStream
;
Get a list of backups as a readable object stream.
Wrapper around .
Parameter
Name
Description
options
GetBackupsOptions
Query object for listing backups.
Returns
Type
Description
NodeJS.ReadableStream
{ReadableStream} A readable stream that emits Backup instances.
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
();
});
getDatabaseOperations(options)
getDatabaseOperations
(
options
?:
GetDatabaseOperationsOptions
)
:
Promise<GetDatabaseOperationsResponse>
;
GetDatabaseOperationsCallback
Parameter
Name
Description
options
GetDatabaseOperationsOptions
Returns
Type
Description
Promise
< GetDatabaseOperationsResponse
>
getDatabaseOperations(callback)
getDatabaseOperations
(
callback
:
GetDatabaseOperationsCallback
)
:
void
;
Parameter
Name
Description
callback
GetDatabaseOperationsCallback
Returns
Type
Description
void
getDatabaseOperations(options, callback)
getDatabaseOperations
(
options
:
GetDatabaseOperationsOptions
,
callback
:
GetDatabaseOperationsCallback
)
:
void
;
Parameters
Name
Description
options
GetDatabaseOperationsOptions
callback
GetDatabaseOperationsCallback
Returns
Type
Description
void
getDatabases(options)
getDatabases
(
options
?:
GetDatabasesOptions
)
:
Promise<GetDatabasesResponse>
;
Get a list of databases.
Wrapper around .
Parameter
Name
Description
options
GetDatabasesOptions
Query object for listing databases.
Returns
Type
Description
Promise
< GetDatabasesResponse
>
{Promise
const
{
Spanner
}
=
require
(
' @google-cloud/spanner
'
);
const
spanner
=
new
Spanner
();
const
instance
=
spanner
.
instance
(
'my-instance'
);
instance
.
getDatabases
(
function
(
err
,
databases
)
{
// `databases` is an array of `Database` objects.
});
//-
// To control how many API requests are made and page through the results
// manually, set `autoPaginate` to `false`.
//-
function
callback
(
err
,
databases
,
nextQuery
,
apiResponse
)
{
if
(
nextQuery
)
{
// More results exist.
instance
.
getDatabases
(
nextQuery
,
callback
);
}
}
instance
.
getDatabases
({
gaxOptions
:
{
autoPaginate
:
false
}
},
callback
);
//-
// If the callback is omitted, we'll return a Promise.
//-
instance
.
getDatabases
().
then
(
function
(
data
)
{
const
databases
=
data
[
0
];
});
getDatabases(callback)
getDatabases
(
callback
:
GetDatabasesCallback
)
:
void
;
Parameter
Name
Description
callback
GetDatabasesCallback
Returns
Type
Description
void
getDatabases(options, callback)
getDatabases
(
options
:
GetDatabasesOptions
,
callback
:
GetDatabasesCallback
)
:
void
;
Parameters
Name
Description
options
GetDatabasesOptions
callback
GetDatabasesCallback
Returns
Type
Description
void
getDatabasesStream(options)
getDatabasesStream
(
options
?:
GetDatabasesOptions
)
:
NodeJS
.
ReadableStream
;
Get a list of databases as a readable object stream.
Wrapper around .
Parameter
Name
Description
options
GetDatabasesOptions
Query object for listing databases.
Returns
Type
Description
NodeJS.ReadableStream
{ReadableStream} A readable stream that emits Database instances.
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
();
});
getMetadata(options)
getMetadata
(
options
?:
GetInstanceMetadataOptions
)
:
Promise<GetInstanceMetadataResponse>
;
Get the instance's metadata.
Wrapper around .
Parameter
Name
Description
options
GetInstanceMetadataOptions
Configuration object
Returns
Type
Description
Promise
< GetInstanceMetadataResponse
>
{Promise
const
{
Spanner
}
=
require
(
' @google-cloud/spanner
'
);
const
spanner
=
new
Spanner
();
const
instance
=
spanner
.
instance
(
'my-instance'
);
instance
.
getMetadata
(
function
(
err
,
metadata
,
apiResponse
)
{});
//-
// Request only `displayName`.
//-
instance
.
getMetadata
({
fieldNames
:
'displayName'
},
(
err
,
metadata
,
apiResponse
)
=
>
{
// metadata will only contain value for `displayName`
const
displayName
=
metadata
[
'displayName'
];
})
//-
// Request multiple specific field names.
//-
instance
.
getMetadata
({
fieldNames
:
[
'displayName'
,
'nodeCount'
]},
(
err
,
metadata
,
apiResponse
)
=
>
{
// metadata will only contain value for `displayName` and 'nodeCount'
const
displayName
=
metadata
[
'displayName'
];
const
nodeCount
=
metadata
[
'nodeCount'
];
});
//-
// If the callback is omitted, we'll return a Promise.
//-
instance
.
getMetadata
().
then
(
function
(
data
)
{
const
metadata
=
data
[
0
];
const
apiResponse
=
data
[
1
];
});
getMetadata(callback)
getMetadata
(
callback
:
GetInstanceMetadataCallback
)
:
void
;
Parameter
Name
Description
callback
GetInstanceMetadataCallback
Returns
Type
Description
void
getMetadata(options, callback)
getMetadata
(
options
:
GetInstanceMetadataOptions
,
callback
:
GetInstanceMetadataCallback
)
:
void
;
Parameters
Name
Description
options
GetInstanceMetadataOptions
callback
GetInstanceMetadataCallback
Returns
Type
Description
void
setMetadata(metadata, gaxOptions)
setMetadata
(
metadata
:
IInstance
,
gaxOptions
?:
CallOptions
)
:
Promise<SetInstanceMetadataResponse>
;
Update the metadata for this instance. Note that this method follows PATCH semantics, so previously-configured settings will persist.
Wrapper around .
Parameters
Name
Description
metadata
IInstance
The metadata you wish to set.
gaxOptions
Returns
Type
Description
Promise
< SetInstanceMetadataResponse
>
{Promise
const
{
Spanner
}
=
require
(
' @google-cloud/spanner
'
);
const
spanner
=
new
Spanner
();
const
instance
=
spanner
.
instance
(
'my-instance'
);
const
metadata
=
{
displayName
:
'My Instance'
};
instance
.
setMetadata
(
metadata
,
function
(
err
,
operation
,
apiResponse
)
{
if
(
err
)
{
// Error handling omitted.
}
operation
.
on
(
'error'
,
function
(
err
)
{})
.
on
(
'complete'
,
function
()
{
// Metadata updated successfully.
});
});
//-
// If the callback is omitted, we'll return a Promise.
//-
instance
.
setMetadata
(
metadata
).
then
(
function
(
data
)
{
const
operation
=
data
[
0
];
const
apiResponse
=
data
[
1
];
});
setMetadata(metadata, callback)
setMetadata
(
metadata
:
IInstance
,
callback
:
SetInstanceMetadataCallback
)
:
void
;
Parameters
Name
Description
metadata
IInstance
callback
SetInstanceMetadataCallback
Returns
Type
Description
void
setMetadata(metadata, gaxOptions, callback)
setMetadata
(
metadata
:
IInstance
,
gaxOptions
:
CallOptions
,
callback
:
SetInstanceMetadataCallback
)
:
void
;
Parameters
Name
Description
metadata
IInstance
gaxOptions
CallOptions
callback
SetInstanceMetadataCallback
Returns
Type
Description
void
