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'); ```