@google-cloud/spanner
Version:
Cloud Spanner Client Library for Node.js
261 lines (260 loc) • 8.94 kB
TypeScript
/*!
* Copyright 2016 Google Inc. All Rights Reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/*!
* @module spanner/session
*/
declare const common: any;
import * as r from 'teeny-request';
import { Snapshot, Transaction, PartitionedDml, TimestampBounds } from './transaction';
import { google } from '../protos/protos';
import { Database } from './database';
import { NormalCallback } from './common';
import { ObservabilityOptions } from './instrument';
import { grpc, CallOptions } from 'google-gax';
import IRequestOptions = google.spanner.v1.IRequestOptions;
export type GetSessionResponse = [Session, r.Response];
/**
* @deprecated. enum to capture the possible session types
*/
export declare const enum types {
ReadOnly = "readonly",
ReadWrite = "readwrite"
}
export interface GetSessionMetadataResponse {
name?: string | null;
labels?: {
[k: string]: string;
} | null;
createTime?: google.protobuf.ITimestamp | null;
approximateLastUseTime?: google.protobuf.ITimestamp | null;
databaseRole?: string | null;
}
export type GetSessionMetadataCallback = NormalCallback<GetSessionMetadataResponse>;
export type KeepAliveCallback = NormalCallback<google.spanner.v1.IResultSet>;
export type KeepAliveResponse = [google.spanner.v1.IResultSet];
export type DeleteSessionResponse = [google.protobuf.IEmpty];
export type DeleteSessionCallback = NormalCallback<google.protobuf.IEmpty>;
/**
* 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.**
*
* @class
* @param {Database} database Parent {@link Database} instance.
* @param {string} [name] 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');
* ```
*/
export declare class Session extends common.GrpcServiceObject {
formattedName_?: string;
txn?: Transaction;
lastUsed?: number;
lastError?: grpc.ServiceError;
commonHeaders_: {
[k: string]: string;
};
_observabilityOptions?: ObservabilityOptions;
constructor(database: Database, name?: string);
/**
* Delete a session.
*
* Wrapper around {@link v1.SpannerClient#deleteSession}.
*
* @see {@link v1.SpannerClient#deleteSession}
* @see [DeleteSession API Documentation](https://cloud.google.com/spanner/docs/reference/rpc/google.spanner.v1#google.spanner.v1.Spanner.DeleteSession)
*
* @param {object} [gaxOptions] Request configuration options,
* See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions}
* for more details.
* @param {DeleteSessionCallback} [callback] Callback function.
* @returns {Promise<DeleteSessionResponse>}
*
* @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];
* });
* ```
*/
delete(gaxOptions?: CallOptions): Promise<DeleteSessionResponse>;
delete(callback: DeleteSessionCallback): void;
delete(gaxOptions: CallOptions, callback: DeleteSessionCallback): void;
/**
* @typedef {array} GetSessionMetadataResponse
* @property {object} 0 The session's metadata.
* @property {object} 1 The full API response.
*/
/**
* @callback GetSessionMetadataCallback
* @param {?Error} err Request error, if any.
* @param {object} metadata The session's metadata.
* @param {object} apiResponse The full API response.
*/
/**
* Get the session's metadata.
*
* Wrapper around {@link v1.SpannerClient#getSession}.
*
* @see {@link v1.SpannerClient#getSession}
* @see [GetSession API Documentation](https://cloud.google.com/spanner/docs/reference/rpc/google.spanner.v1#google.spanner.v1.Spanner.GetSession)
*
* @param {object} [gaxOptions] Request configuration options,
* See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions}
* for more details.
* @param {GetSessionMetadataCallback} [callback] Callback function.
* @returns {Promise<GetSessionMetadataResponse>}
*
* @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];
* });
* ```
*/
getMetadata(gaxOptions?: CallOptions): Promise<GetSessionMetadataResponse>;
getMetadata(callback: GetSessionMetadataCallback): void;
getMetadata(gaxOptions: CallOptions, callback: GetSessionMetadataCallback): void;
/**
* Ping the session with `SELECT 1` to prevent it from expiring.
*
* @param {object} [gaxOptions] Request configuration options,
* See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions}
* for more details.
* @param {BasicCallback} [callback] Callback function.
* @returns {Promise<BasicResponse>}
*
* @example
* ```
* session.keepAlive(function(err) {
* if (err) {
* // An error occurred while trying to keep this session alive.
* }
* });
* ```
*/
keepAlive(gaxOptions?: CallOptions): Promise<KeepAliveResponse>;
keepAlive(callback: KeepAliveCallback): void;
keepAlive(gaxOptions: CallOptions, callback: KeepAliveCallback): void;
/**
* Create a PartitionedDml transaction.
*
* @returns {PartitionedDml}
*
* @example
* ```
* const transaction = session.partitionedDml();
* ```
*/
partitionedDml(): PartitionedDml;
/**
* Create a Snapshot transaction.
*
* @param {TimestampBounds} [options] The timestamp bounds.
* @param {google.spanner.v1.ExecuteSqlRequest.IQueryOptions} [queryOptions] The default query options to use.
* @returns {Snapshot}
*
* @example
* ```
* const snapshot = session.snapshot({strong: false});
* ```
*/
snapshot(options?: TimestampBounds, queryOptions?: google.spanner.v1.ExecuteSqlRequest.IQueryOptions): Snapshot;
/**
* Create a read write Transaction.
*
* @param {google.spanner.v1.ExecuteSqlRequest.IQueryOptions} [queryOptions] The default query options to use.
* @return {Transaction}
*
* @example
* ```
* const transaction = session.transaction();
* ```
*/
transaction(queryOptions?: google.spanner.v1.ExecuteSqlRequest.IQueryOptions, requestOptions?: Pick<IRequestOptions, 'transactionTag'>): Transaction;
/**
* Format the session name to include the parent database's name.
*
* @private
*
* @param {string} databaseName The parent database's name.
* @param {string} name The instance name.
* @returns {string}
*
* @example
* ```
* Session.formatName_('my-database', 'my-session');
* // 'projects/grape-spaceship-123/instances/my-instance/' +
* // 'databases/my-database/sessions/my-session'
* ```
*/
static formatName_(databaseName: string, name: string): string;
/**
* Gets the Spanner object
*
* @private
*
* @returns {Spanner}
*/
private _getSpanner;
private channelId;
}
export {};