Constructor

Database

new Database(name, options)

Create a Database object to interact with a Cloud Spanner database.

Parameter

name

string

Name of the database.

options

SessionPoolOptions

Session pool configuration options.

Example

const Spanner = require('@google-cloud/spanner');
const spanner = new Spanner();
const instance = spanner.instance('my-instance');
const database = instance.database('my-database');

Methods

close

close(callback) returns Promise

Close the database connection and destroy all sessions associated with it.

Parameter

callback

Optional

CloseDatabaseCallback

Callback function.

Returns

Promise 

Example

const Spanner = require('@google-cloud/spanner');
const spanner = new Spanner();

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

database.close(function(err) {
  if (err) {
    // Error handling omitted.
  }
});

create

create(options, callback) returns Promise containing CreateDatabaseResponse

Create a database.

Parameter

options

Optional

CreateDatabaseRequest

Configuration object.

callback

Optional

CreateDatabaseCallback

Callback function.

Returns

Promise containing CreateDatabaseResponse 

Example

const Spanner = require('@google-cloud/spanner');
const spanner = new Spanner();
const instance = spanner.instance('my-instance');
const database = instance.database('my-database');

database.create(function(err, database, operation, apiResponse) {
  if (err) {
    // Error handling omitted.
  }

  operation
    .on('error', function(err) {})
    .on('complete', function() {
      // Database created successfully.
    });
});

//-
// If the callback is omitted, we'll return a Promise.
//-
database.create()
  .then(function(data) {
    const operation = data[0];
    const apiResponse = data[1];

    return operation.promise();
  })
  .then(function() {
    // Database created successfully.
  });

createSession

createSession(options, callback) returns Promise containing CreateSessionResponse

Create a new session, which can be used to perform transactions that read and/or modify data.

Sessions can only execute one transaction at a time. To execute multiple concurrent read-write/write-only transactions, create multiple sessions. Note that standalone reads and queries use a transaction internally, and count toward the one transaction limit.

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

Wrapper around v1.SpannerClient#createSession.

Parameter

options

Optional

object

Configuration object.

callback

Optional

CreateSessionCallback

Callback function.

See also
v1.SpannerClient#createSession

CreateSession API Documentation

Returns

Promise containing CreateSessionResponse 

Example

const Spanner = require('@google-cloud/spanner');
const spanner = new Spanner();

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

database.createSession(function(err, session, apiResponse) {
  if (err) {
    // Error handling omitted.
  }

  // `session` is a Session object.
});

//-
// If the callback is omitted, we'll return a Promise.
//-
database.createSession().then(function(data) {
  const session = data[0];
  const apiResponse = data[1];
});

createTable

createTable(schema, callback) returns Promise containing CreateTableResponse

Create a table.

Wrapper around Database#updateSchema.

Parameter

schema

string

A DDL CREATE statement describing the table.

callback

Optional

CreateTableCallback

Callback function.

See also
Database#updateSchema
Returns

Promise containing CreateTableResponse 

Example

const Spanner = require('@google-cloud/spanner');
const spanner = new Spanner();

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

const schema =
  'CREATE TABLE Singers (' +
  '  SingerId INT64 NOT NULL,' +
  '  FirstName STRING(1024),' +
  '  LastName STRING(1024),' +
  '  SingerInfo BYTES(MAX),' +
  ') PRIMARY KEY(SingerId)';

database.createTable(schema, function(err, table, operation, apiResponse) {
  if (err) {
    // Error handling omitted.
  }

  operation
    .on('error', function(err) {})
    .on('complete', function() {
      // Table created successfully.
    });
});

//-
// If the callback is omitted, we'll return a Promise.
//-
database.createTable(schema)
  .then(function(data) {
    const table = data[0];
    const operation = data[1];

    return operation.promise();
  })
  .then(function() {
    // Table created successfully.
  });

delete

delete(callback) returns Promise containing BasicResponse

Delete the database.

Wrapper around v1.DatabaseAdminClient#dropDatabase.

Parameter

callback

Optional

BasicCallback

Callback function.

See also
v1.DatabaseAdminClient#dropDatabase

DropDatabase API Documentation

Returns

Promise containing BasicResponse 

Example

const Spanner = require('@google-cloud/spanner');
const spanner = new Spanner();

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

database.delete(function(err, apiResponse) {
  if (err) {
    // Error handling omitted.
  }

  // Database was deleted successfully.
});

//-
// If the callback is omitted, we'll return a Promise.
//-
database.delete().then(function(data) {
  var apiResponse = data[0];
});

exists

exists(callback) returns Promise containing DatabaseExistsResponse

Check if a database exists.

Parameter

callback

Optional

DatabaseExistsCallback

Callback function.

Returns

Promise containing DatabaseExistsResponse 

Example

const Spanner = require('@google-cloud/spanner');
const spanner = new Spanner();

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

database.exists(function(err, exists) {});

//-
// If the callback is omitted, we'll return a Promise.
//-
database.exists().then(function(data) {
  const exists = data[0];
});

get

get(options, callback) returns Promise containing GetDatabaseResponse

Get a database 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

options

Optional

options

Configuration object.

Values in options have the following properties:

Parameter

autoCreate

Optional

boolean

Automatically create the object if it does not exist.

callback

Optional

GetDatabaseCallback

Callback function.

Returns

Promise containing GetDatabaseResponse 

Example

const Spanner = require('@google-cloud/spanner');
const spanner = new Spanner();

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

database.get(function(err, database, apiResponse) {
  // `database.metadata` has been populated.
});

//-
// If the callback is omitted, we'll return a Promise.
//-
database.get().then(function(data) {
  var database = data[0];
  var apiResponse = data[0];
});

getMetadata

getMetadata(callback) returns Promise containing GetDatabaseMetadataResponse

Get the database's metadata.

Wrapper around v1.DatabaseAdminClient#getDatabase.

Parameter

callback

Optional

GetDatabaseMetadataCallback

Callback function.

See also
v1.DatabaseAdminClient#getDatabase

GetDatabase API Documentation

Returns

Promise containing GetDatabaseMetadataResponse 

Example

const Spanner = require('@google-cloud/spanner');
const spanner = new Spanner();

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

database.getMetadata(function(err, metadata, apiResponse) {
  if (err) {
    // Error handling omitted.
  }

  // Database was deleted successfully.
});

//-
// If the callback is omitted, we'll return a Promise.
//-
database.getMetadata().then(function(data) {
  const metadata = data[0];
  const apiResponse = data[1];
});

getSchema

getSchema(callback) returns Promise containing GetSchemaResponse

Get this database's schema as a list of formatted DDL statements.

Wrapper around v1.DatabaseAdminClient#getDatabaseDdl.

Parameter

callback

Optional

GetSchemaCallback

Callback function.

See also
v1.DatabaseAdminClient#getDatabaseDdl

Data Definition Language (DDL)

GetDatabaseDdl API Documentation

Returns

Promise containing GetSchemaResponse 

Example

const Spanner = require('@google-cloud/spanner');
const spanner = new Spanner();

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

database.getSchema(function(err, statements, apiResponse) {});

//-
// If the callback is omitted, we'll return a Promise.
//-
database.getSchema().then(function(data) {
  const statements = data[0];
  const apiResponse = data[1];
});

getTransaction

getTransaction(options, callback) returns Promise containing GetTransactionResponse

Get a read/write ready Transaction object.

Wrapper around v1.SpannerClient#beginTransaction.

Parameter

options

Optional

TransactionOptions

Transaction options.

callback

Optional

GetTransactionCallback

Callback function.

See also
v1.SpannerClient#beginTransaction
Returns

Promise containing GetTransactionResponse 

Example

const Spanner = require('@google-cloud/spanner');
const spanner = new Spanner();

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

database.getTransaction(function(err, transaction) {});

//-
// If the callback is omitted, we'll return a Promise.
//-
database.getTransaction().then(function(data) {
  const transaction = data[0];
});

run

run(query, options, callback) returns Promise containing RunResponse

Execute a SQL statement on this database.

Wrapper around v1.SpannerClient#executeStreamingSql.

Parameter

query

(string or object)

A SQL query or query object. See an ExecuteSqlRequest object.

Values in query have the following properties:

Parameter

params

Optional

object

A map of parameter name to values.

types

Optional

object

A map of parameter types.

options

Optional

DatabaseRunRequest

Transaction options.