Session

Session

Create a Session object to interact with a Cloud Spanner session.

It is unlikely you will need to interact with sessions directly. By default, sessions are created and utilized for maximum performance automatically.

Constructor

new Session(database, nameopt)

Parameters:
Name Type Attributes Description
database Database

Parent Database instance.
name string <optional>

The name of the session. If not provided, it is assumed you are going to create it.
Example
const {Spanner} = require('@google-cloud/spanner');
const spanner = new Spanner();

const instance = spanner.instance('my-instance');
const database = instance.database('my-database');

//-
// To create a session manually, don't provide a name.
//-
const session = database.session();

session.create(function(err) {
  if (err) {
    // Error handling omitted.
  }

  // Session created successfully.
  // `session.id` = The name of the session.
});

//-
// To access a previously-created session, provide a name.
//-
const session = database.session('session-name');

Members

id

Methods

create(optionsopt, callbackopt) → {Promise.<CreateSessionResponse>}

Create a session.

Parameters:
Name Type Attributes Description
options object <optional>

See Database#createSession.
callback CreateSessionCallback <optional>

Callback function.
Returns:
Type Description
Promise.<CreateSessionResponse>
Example
session.create(function(err, session, apiResponse) {
  if (err) {
    // Error handling omitted.
  }

  // Session created successfully.
});

//-
//Returns a Promise if the callback is omitted.
//-
session.create()
  .then(function(data) {
    const session = data[0];
    const apiResponse = data[1];

    // Session created successfully.
  });

delete(gaxOptionsopt, callbackopt) → {Promise.<DeleteSessionResponse>}

Delete a session.

Wrapper around v1.SpannerClient#deleteSession.

Parameters:
Name Type Attributes Description
gaxOptions object <optional>

Request configuration options, See CallOptions for more details.
callback DeleteSessionCallback <optional>

Callback function.
Returns:
Type Description
Promise.<DeleteSessionResponse>
See:
Example
session.delete(function(err, apiResponse) {
  if (err) {
    // Error handling omitted.
  }

  // Session deleted successfully.
});

//-
//Returns a Promise if the callback is omitted.
//-
session.delete().then(function(data) {
  const apiResponse = data[0];
});

exists(callbackopt) → {Promise.<SessionExistsResponse>}

Check if a session exists.

Parameters:
Name Type Attributes Description
callback SessionExistsCallback <optional>

Callback function.
Returns:
Type Description
Promise.<SessionExistsResponse>
Example
session.exists(function(err, exists) {});

//-
//Returns a Promise if the callback is omitted.
//-
session.exists().then(function(data) {
  const exists = data[0];
});

get(optionsopt, callbackopt) → {Promise.<GetSessionResponse>}

Get a session 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.

Parameters:
Name Type Attributes Description
options options <optional>

Configuration object.

Properties
Name Type Attributes Default Description
autoCreate boolean <optional>
 false

Automatically create the object if it does not exist.
callback CreateSessionCallback <optional>

Callback function.
Returns:
Type Description
Promise.<GetSessionResponse>
Example
session.get(function(err, session, apiResponse) {
  // `session.metadata` has been populated.
});

//-
//Returns a Promise if the callback is omitted.
//-
session.get().then(function(data) {
  const session = data[0];
  const apiResponse = data[0];
});

getMetadata(gaxOptionsopt, callbackopt) → {Promise.<GetSessionMetadataResponse>}

Get the session's metadata.

Wrapper around v1.SpannerClient#getSession.

Parameters:
Name Type Attributes Description
gaxOptions object <optional>

Request configuration options, See CallOptions for more details.
callback GetSessionMetadataCallback <optional>

Callback function.
Returns:
Type Description
Promise.<GetSessionMetadataResponse>
See:
Example
session.getMetadata(function(err, metadata, apiResponse) {});

//-
//Returns a Promise if the callback is omitted.
//-
session.getMetadata().then(function(data) {
  const metadata = data[0];
  const apiResponse = data[1];
});

keepAlive(gaxOptionsopt, callbackopt) → {Promise.<BasicResponse>}

Ping the session with SELECT 1 to prevent it from expiring.

Parameters:
Name Type Attributes Description
gaxOptions object <optional>

Request configuration options, See CallOptions for more details.
callback BasicCallback <optional>

Callback function.
Returns:
Type Description
Promise.<BasicResponse>
Example
session.keepAlive(function(err) {
  if (err) {
    // An error occurred while trying to keep this session alive.
  }
});

partitionedDml() → {PartitionedDml}

Create a PartitionedDml transaction.

Returns:
Type Description
PartitionedDml
Example
const transaction = session.partitionedDml();

snapshot(optionsopt, queryOptionsopt) → {Snapshot}

Create a Snapshot transaction.

Parameters:
Name Type Attributes Description
options TimestampBounds <optional>

The timestamp bounds.
queryOptions google.spanner.v1.ExecuteSqlRequest.IQueryOptions <optional>

The default query options to use.
Returns:
Type Description
Snapshot
Example
const snapshot = session.snapshot({strong: false});

transaction(queryOptionsopt) → {Transaction}

Create a read write Transaction.

Parameters:
Name Type Attributes Description
queryOptions google.spanner.v1.ExecuteSqlRequest.IQueryOptions <optional>

The default query options to use.
Returns:
Type Description
Transaction
Example
const transaction = session.transaction();