Database

Database

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

Constructor

new Database(name, options, queryOptions)

Parameters:
Name Type Description
name string

Name of the database.
options SessionPoolOptions | SessionPoolInterface

Session pool configuration options or custom pool interface.
queryOptions google.spanner.v1.ExecuteSqlRequest.IQueryOptions

The default query options to use for queries on the database.
Example
```
const {Spanner} = require('@google-cloud/spanner');
const spanner = new Spanner();
const instance = spanner.instance('my-instance');
const database = instance.database('my-database');
```

Methods

batchTransaction(identifier, optionsopt) → {BatchTransaction}

Get a reference to a BatchTransaction object.

Parameters:
Name Type Attributes Description
identifier TransactionIdentifier

The transaction identifier.
options object <optional>

Transaction options.
Returns:
Type Description
BatchTransaction

A batch transaction object.
See:
Example
```
const {Spanner} = require('@google-cloud/spanner');
const spanner = new Spanner();

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

const transaction = database.batchTransaction({
  session: 'my-session',
  transaction: 'my-transaction',
  readTimestamp: 1518464696657
});
```

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

Create a database.

Parameters:
Name Type Attributes Description
options CreateDatabaseRequest <optional>

Configuration object.
callback CreateDatabaseCallback <optional>

Callback function.
Returns:
Type Description
Promise.<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.
  });
```

runStream(query, optionsopt) → {PartialResultStream}

Create a readable object stream to receive resulting rows from a SQL statement.

Wrapper around v1.SpannerClient#executeStreamingSql.

Parameters:
Name Type Attributes Description
query string | ExecuteSqlRequest

A SQL query or ExecuteSqlRequest object.
options TimestampBounds <optional>

Snapshot timestamp bounds.
Returns:
Type Description
PartialResultStream

A readable stream that emits rows.
See:
Fires:
  • PartialResultStream#event:response
Example
```
const {Spanner} = require('@google-cloud/spanner');
const spanner = new Spanner();

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

const query = 'SELECT * FROM Singers';

database.runStream(query)
  .on('error', function(err) {})
  .on('data', function(row) {
    // row = [
    //   {
    //     name: 'SingerId',
    //     value: '1'
    //   },
    //   {
    //     name: 'Name',
    //     value: 'Eddie Wilson'
    //   }
    // ]
  // ]
  })
  .on('end', function() {
    // All results retrieved.
  });

//-
// Rows are returned as an array of objects. Each object has a `name` and
// `value` property. To get a serialized object, call `toJSON()`.
//-
database.runStream(query)
  .on('error', function(err) {})
  .on('data', function(row) {
    // row.toJSON() = {
    //   SingerId: '1',
    //   Name: 'Eddie Wilson'
    // }
  })
  .on('end', function() {
    // All results retrieved.
  });

//-
// Alternatively, set `query.json` to `true`, and this step will be performed
// automatically.
//-
query.json = true;

database.runStream(query)
  .on('error', function(err) {})
  .on('data', function(row) {
    // row = {
    //   SingerId: '1',
    //   Name: 'Eddie Wilson'
    // }
  })
  .on('end', function() {
    // All results retrieved.
  });

//-
// The SQL query string can contain parameter placeholders. A parameter
// placeholder consists of '@' followed by the parameter name.
//-
const query = {
  sql: 'SELECT * FROM Singers WHERE name = @name',
  params: {
    name: 'Eddie Wilson'
  }
};

database.runStream(query)
  .on('error', function(err) {})
  .on('data', function(row) {})
  .on('end', function() {});

//-
// If you need to enforce a specific param type, a types map can be provided.
// This is typically useful if your param value can be null.
//-
const query = {
  sql: 'SELECT * FROM Singers WHERE name = @name',
  params: {
    name: 'Eddie Wilson'
  },
  types: {
    name: 'string'
  }
};

database.runStream(query)
  .on('error', function(err) {})
  .on('data', function(row) {})
  .on('end', function() {});

//-
// If you anticipate many results, you can end a stream early to prevent
// unnecessary processing and API requests.
//-
database.runStream(query)
  .on('data', function(row) {
    this.end();
  });
```

(async) runTransactionAsync(optionsopt, callback) → {Promise}

A transaction in Cloud Spanner is a set of reads and writes that execute atomically at a single logical point in time across columns, rows, and tables in a database.

Note that Cloud Spanner does not support nested transactions. If a new transaction is started inside of the run function, it will be an independent transaction.

The async function you provide will become the "run function". It will be executed with a Transaction object. The Transaction object will let you run queries and queue mutations until you are ready to Transaction#commit.

In the event that an aborted error occurs, we will re-run the runFn in its entirety. If you prefer to handle aborted errors for yourself please refer to Database#getTransaction.

NOTE: In the event that you encounter an error while reading/writing, if you decide to forgo calling Transaction#commit or Transaction#rollback, then you need to call Transaction#end to release the underlying Session object. Failure to do could result in a Session leak.

For a more complete listing of functionality available to a Transaction, see the Transaction API documentation. For a general overview of transactions within Cloud Spanner, see Transactions from the official Cloud Spanner documentation.

Parameters:
Name Type Attributes Description
options RunTransactionOptions <optional>

Transaction runner options.
callback AsyncRunTransactionCallback

A function to execute in the context of a transaction.
Returns:
Type Description
Promise
See:
Example
```
const {Spanner} = require('@google-cloud/spanner');
const spanner = new Spanner();

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

const data = await database.runTransactionAsync(async (transaction) => {
  const [rows] = await transaction.run('SELECT * FROM MyTable');
  const data = rows.map(row => row.thing);

  await transaction.commit();
  return data;
});
```

session(nameopt) → {Session}

Create a Session object.

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

Parameters:
Name Type Attributes Description
name string <optional>

The name of the session. If not provided, it is assumed you are going to create it.
Returns:
Type Description
Session

A Session object.
Example
```
var session = database.session('session-name');
```