@google-cloud/spanner
Version:
Cloud Spanner Client Library for Node.js
1,205 lines • 85.7 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.
*/
import { ExistsCallback, GetConfig } from '@google-cloud/common';
declare const common: any;
import * as r from 'teeny-request';
import { CallOptions, Operation as GaxOperation } from 'google-gax';
import { BatchTransaction, TransactionIdentifier } from './batch-transaction';
import { SessionFactoryInterface } from './session-factory';
import { google as databaseAdmin, google, google as spannerClient } from '../protos/protos';
import IsolationLevel = google.spanner.v1.TransactionOptions.IsolationLevel;
import { GetDatabaseOperationsOptions, GetDatabaseOperationsResponse, Instance, GetDatabaseOperationsCallback } from './instance';
import { PartialResultStream } from './partial-result-stream';
import { Session } from './session';
import { SessionPoolCloseCallback, SessionPoolInterface, SessionPoolOptions } from './session-pool';
import { CreateTableCallback, CreateTableResponse, Table } from './table';
import { BatchWriteOptions, CommitCallback, CommitResponse, ExecuteSqlRequest, MutationGroup, MutationSet, RunCallback, RunResponse, RunUpdateCallback, Snapshot, TimestampBounds, Transaction } from './transaction';
import { AsyncRunTransactionCallback, RunTransactionCallback, RunTransactionOptions } from './transaction-runner';
import { IOperation, LongRunningCallback, NormalCallback, PagedOptionsWithFilter, PagedResponse, RequestCallback, ResourceCallback, Schema } from './common';
import { Duplex, Readable } from 'stream';
import { EnumKey, RequestConfig, TranslateEnumKeys } from '.';
import IPolicy = google.iam.v1.IPolicy;
import Policy = google.iam.v1.Policy;
import FieldMask = google.protobuf.FieldMask;
import IDatabase = google.spanner.admin.database.v1.IDatabase;
import { ObservabilityOptions } from './instrument';
export type GetDatabaseRolesCallback = RequestCallback<IDatabaseRole, databaseAdmin.spanner.admin.database.v1.IListDatabaseRolesResponse>;
export type GetDatabaseRolesResponse = PagedResponse<IDatabaseRole, databaseAdmin.spanner.admin.database.v1.IListDatabaseRolesResponse>;
type SetDatabaseMetadataCallback = ResourceCallback<GaxOperation, IOperation>;
type SetDatabaseMetadataResponse = [GaxOperation, IOperation];
type IDatabaseRole = databaseAdmin.spanner.admin.database.v1.IDatabaseRole;
type CreateBatchTransactionCallback = ResourceCallback<BatchTransaction, google.spanner.v1.ITransaction | google.spanner.v1.ISession>;
type CreateBatchTransactionResponse = [
BatchTransaction,
google.spanner.v1.ITransaction | google.spanner.v1.ISession
];
type DatabaseResponse = [Database, r.Response];
type DatabaseCallback = ResourceCallback<Database, r.Response>;
type GetSnapshotCallback = NormalCallback<Snapshot>;
type GetTransactionCallback = NormalCallback<Transaction>;
export interface SessionPoolConstructor {
new (database: Database, options?: SessionPoolOptions | null): SessionPoolInterface;
}
export type GetDatabaseDialectCallback = NormalCallback<EnumKey<typeof google.spanner.admin.database.v1.DatabaseDialect>>;
export interface SetIamPolicyRequest {
policy: Policy | null;
updateMask?: FieldMask | null;
}
export interface RunPartitionedUpdateOptions extends ExecuteSqlRequest {
excludeTxnFromChangeStreams?: boolean;
}
export type UpdateSchemaCallback = ResourceCallback<GaxOperation, databaseAdmin.longrunning.IOperation>;
export type UpdateSchemaResponse = [
GaxOperation,
databaseAdmin.longrunning.IOperation
];
type PoolRequestCallback = RequestCallback<Session>;
export type GetSessionsOptions = PagedOptionsWithFilter;
export type GetDatabaseRolesOptions = PagedOptionsWithFilter;
/**
* IDatabase structure with database state enum translated to string form.
*/
type IDatabaseTranslatedEnum = Omit<TranslateEnumKeys<databaseAdmin.spanner.admin.database.v1.IDatabase, 'state', typeof databaseAdmin.spanner.admin.database.v1.Database.State>, 'restoreInfo'> & Omit<TranslateEnumKeys<databaseAdmin.spanner.admin.database.v1.IDatabase, 'databaseDialect', typeof databaseAdmin.spanner.admin.database.v1.DatabaseDialect>, 'restoreInfo'> & {
restoreInfo?: IRestoreInfoTranslatedEnum | null;
};
/**
* IRestoreInfo structure with restore source type enum translated to string form.
*/
type IRestoreInfoTranslatedEnum = TranslateEnumKeys<databaseAdmin.spanner.admin.database.v1.IRestoreInfo, 'sourceType', typeof databaseAdmin.spanner.admin.database.v1.RestoreSourceType>;
type GetDatabaseMetadataResponse = [IDatabaseTranslatedEnum];
type GetDatabaseMetadataCallback = RequestCallback<IDatabaseTranslatedEnum>;
type GetSchemaCallback = RequestCallback<string, databaseAdmin.spanner.admin.database.v1.IGetDatabaseDdlResponse>;
type GetSchemaResponse = [
string[],
databaseAdmin.spanner.admin.database.v1.IGetDatabaseDdlResponse
];
type GetIamPolicyResponse = IPolicy;
type GetIamPolicyCallback = RequestCallback<IPolicy>;
type SetIamPolicyResponse = IPolicy;
type SetIamPolicyCallback = RequestCallback<IPolicy>;
type GetSessionsCallback = RequestCallback<Session, google.spanner.v1.IListSessionsResponse>;
type GetSessionsResponse = PagedResponse<Session, google.spanner.v1.IListSessionsResponse>;
export type GetDatabaseConfig = GetConfig & databaseAdmin.spanner.admin.database.v1.IGetDatabaseRequest & {
gaxOptions?: CallOptions;
};
type DatabaseCloseResponse = [google.protobuf.IEmpty];
export type CreateSessionResponse = [
Session,
spannerClient.spanner.v1.ISession
];
export interface CreateSessionOptions {
labels?: {
[k: string]: string;
} | null;
databaseRole?: string | null;
gaxOptions?: CallOptions;
multiplexed?: boolean;
}
export interface GetIamPolicyOptions {
requestedPolicyVersion?: number | null;
gaxOptions?: CallOptions;
}
/**
* @typedef {object} GetTransactionOptions
* * @property {boolean} [optimisticLock] The optimistic lock a
* {@link Transaction} should use while running.
*/
export type GetTransactionOptions = Omit<RunTransactionOptions, 'timeout'>;
export type CreateSessionCallback = ResourceCallback<Session, spannerClient.spanner.v1.ISession>;
export interface BatchCreateSessionsOptions extends CreateSessionOptions {
count: number;
}
export type BatchCreateSessionsResponse = [
Session[],
spannerClient.spanner.v1.IBatchCreateSessionsResponse
];
export type BatchCreateSessionsCallback = ResourceCallback<Session[], spannerClient.spanner.v1.IBatchCreateSessionsResponse>;
export type DatabaseDeleteResponse = [databaseAdmin.protobuf.IEmpty];
export type DatabaseDeleteCallback = NormalCallback<databaseAdmin.protobuf.IEmpty>;
export interface CancelableDuplex extends Duplex {
cancel(): void;
}
export type RestoreDatabaseCallback = LongRunningCallback<Database>;
export type RestoreDatabaseResponse = [
Database,
GaxOperation,
databaseAdmin.longrunning.IOperation
];
export type GetRestoreInfoCallback = NormalCallback<IRestoreInfoTranslatedEnum>;
export type GetStateCallback = NormalCallback<EnumKey<typeof databaseAdmin.spanner.admin.database.v1.Database.State>>;
interface DatabaseRequest {
(config: RequestConfig, callback: ResourceCallback<GaxOperation, IOperation>): void;
<T>(config: RequestConfig, callback: RequestCallback<T>): void;
<T, R>(config: RequestConfig, callback: RequestCallback<T, R>): void;
}
export interface RestoreOptions {
encryptionConfig?: databaseAdmin.spanner.admin.database.v1.IRestoreDatabaseEncryptionConfig;
gaxOptions?: CallOptions;
}
export interface WriteAtLeastOnceOptions extends CallOptions {
isolationLevel?: IsolationLevel;
}
/**
* Create a Database object to interact with a Cloud Spanner database.
*
* @class
*
* @param {string} name Name of the database.
* @param {SessionPoolOptions|SessionPoolInterface} options Session pool
* configuration options or custom pool interface.
* @param {google.spanner.v1.ExecuteSqlRequest.IQueryOptions} queryOptions
* 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');
* ```
*/
declare class Database extends common.GrpcServiceObject {
private instance;
formattedName_: string;
pool_: SessionPoolInterface;
sessionFactory_: SessionFactoryInterface;
queryOptions_?: spannerClient.spanner.v1.ExecuteSqlRequest.IQueryOptions;
commonHeaders_: {
[k: string]: string;
};
request: DatabaseRequest;
databaseRole?: string | null;
labels?: {
[k: string]: string;
} | null;
databaseDialect?: EnumKey<typeof databaseAdmin.spanner.admin.database.v1.DatabaseDialect> | null;
_observabilityOptions?: ObservabilityOptions;
private _traceConfig;
private _nthRequest;
_clientId: number;
constructor(instance: Instance, name: string, poolOptions?: SessionPoolConstructor | SessionPoolOptions, queryOptions?: spannerClient.spanner.v1.ExecuteSqlRequest.IQueryOptions);
_nextNthRequest(): number;
/**
* @typedef {array} SetDatabaseMetadataResponse
* @property {object} 0 The {@link Database} metadata.
* @property {object} 1 The full API response.
*/
/**
* @callback SetDatabaseMetadataCallback
* @param {?Error} err Request error, if any.
* @param {object} metadata The {@link Database} metadata.
* @param {object} apiResponse The full API response.
*/
/**
* Update the metadata for this database. Note that this method follows PATCH
* semantics, so previously-configured settings will persist.
*
* Wrapper around {@link v1.DatabaseAdminClient#updateDatabase}.
*
* @see {@link v1.DatabaseAdminClient#updateDatabase}
* @see [UpdateDatabase API Documentation](https://cloud.google.com/spanner/docs/reference/rpc/google.spanner.admin.database.v1#google.spanner.admin.database.v1.DatabaseAdmin.UpdateDatabase)
*
* @param {object} metadata The metadata you wish to set.
* @param {object} [gaxOptions] Request configuration options,
* See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions}
* for more details.
* @param {SetDatabaseMetadataCallback} [callback] Callback function.
* @returns {Promise<SetDatabaseMetadataResponse>}
*
* @example
* ```
* const {Spanner} = require('@google-cloud/spanner');
* const spanner = new Spanner();
*
* const instance = spanner.instance('my-instance');
* const database = instance.database('my-database');
*
* const metadata = {
* enableDropProtection: true
* };
*
* database.setMetadata(metadata, function(err, operation, apiResponse) {
* if (err) {
* // Error handling omitted.
* }
*
* operation
* .on('error', function(err) {})
* .on('complete', function() {
* // Metadata updated successfully.
* });
* });
*
* //-
* // If the callback is omitted, we'll return a Promise.
* //-
* database.setMetadata(metadata).then(function(data) {
* const operation = data[0];
* const apiResponse = data[1];
* });
* ```
*/
setMetadata(metadata: IDatabase, gaxOptions?: CallOptions): Promise<SetDatabaseMetadataResponse>;
setMetadata(metadata: IDatabase, callback: SetDatabaseMetadataCallback): void;
setMetadata(metadata: IDatabase, gaxOptions: CallOptions, callback: SetDatabaseMetadataCallback): void;
static getEnvironmentQueryOptions(): databaseAdmin.spanner.v1.ExecuteSqlRequest.IQueryOptions;
/**
* @typedef {object} BatchCreateSessionsOptions
* @property {number} count The number of sessions to create.
* @property {object.<string, string>} [labels] Labels to apply to each
* session.
* @property {object} [gaxOptions] Request configuration options,
* See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions}
* for more details.
*/
/**
* @typedef {array} BatchCreateSessionsResponse
* @property {Session[]} 0 The newly created sessions.
* @property {object} 1 The full API response.
*/
/**
* @callback BatchCreateSessionsCallback
* @param {?Error} err Request error, if any.
* @param {Session[]} sessions The newly created sessions.
* @param {object} apiResponse The full API response.
*/
/**
* Create a batch of sessions, which can be used to perform transactions that
* read and/or modify data.
*
* **It is unlikely you will need to interact with sessions directly. By
* default, sessions are created and utilized for maximum performance
* automatically.**
*
* Wrapper around {@link v1.SpannerClient#batchCreateSessions}.
*
* @see {@link v1.SpannerClient#batchCreateSessions}
* @see [BatchCreateSessions API Documentation](https://cloud.google.com/spanner/docs/reference/rpc/google.spanner.v1#google.spanner.v1.Spanner.BatchCreateSessions)
*
* @param {number|BatchCreateSessionsOptions} options Desired session count or
* a configuration object.
* @param {BatchCreateSessionsCallback} [callback] Callback function.
* @returns {Promise<BatchCreateSessionsResponse>}
*
* @example
* ```
* const {Spanner} = require('@google-cloud/spanner');
* const spanner = new Spanner();
*
* const instance = spanner.instance('my-instance');
* const database = instance.database('my-database');
*
* const count = 5;
*
* database.batchCreateSession(count, (err, sessions, response) => {
* if (err) {
* // Error handling omitted.
* }
*
* // `sessions` is an array of Session objects.
* });
*
* ```
* @example If the callback is omitted, we'll return a Promise.
* ```
* const [sessions, response] = await database.batchCreateSessions(count);
* ```
*/
batchCreateSessions(options: number | BatchCreateSessionsOptions): Promise<BatchCreateSessionsResponse>;
batchCreateSessions(options: number | BatchCreateSessionsOptions, callback: BatchCreateSessionsCallback): void;
_metadataWithRequestId(nthRequest: number, attempt: number, priorMetadata?: {
[k: string]: string;
}): {
[k: string]: string;
};
/**
* Get a reference to a {@link BatchTransaction} object.
*
* @see {@link BatchTransaction#identifier} to generate an identifier.
*
* @param {TransactionIdentifier} identifier The transaction identifier.
* @param {object} [options] [Transaction options](https://cloud.google.com/spanner/docs/timestamp-bounds).
* @returns {BatchTransaction} A batch transaction object.
*
* @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
* });
* ```
*/
batchTransaction(identifier: TransactionIdentifier, options?: TimestampBounds): BatchTransaction;
/**
* @callback CloseDatabaseCallback
* @param {?Error} err Request error, if any.
*/
/**
* Close the database connection and destroy all sessions associated with it.
*
* @param {CloseDatabaseCallback} [callback] 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.
* }
* });
*
* //-
* // In the event of a session leak, the error object will contain a
* // `messages` field.
* //-
* database.close(function(err) {
* if (err && err.messages) {
* err.messages.forEach(function(message) {
* console.error(message);
* });
* }
* });
* ```
*/
close(callback: SessionPoolCloseCallback): void;
close(): Promise<DatabaseCloseResponse>;
/**
* @typedef {array} CreateTransactionResponse
* @property {BatchTransaction} 0 The {@link BatchTransaction}.
* @property {object} 1 The full API response.
*/
/**
* @callback CreateTransactionCallback
* @param {?Error} err Request error, if any.
* @param {BatchTransaction} transaction The {@link BatchTransaction}.
* @param {object} apiResponse The full API response.
*/
/**
* Create a transaction that can be used for batch querying.
*
* @param {object} [options] [Transaction options](https://cloud.google.com/spanner/docs/timestamp-bounds).
* @param {CreateTransactionCallback} [callback] Callback function.
* @returns {Promise<CreateTransactionResponse>}
*/
createBatchTransaction(options?: TimestampBounds): Promise<CreateBatchTransactionResponse>;
createBatchTransaction(callback: CreateBatchTransactionCallback): void;
createBatchTransaction(options: TimestampBounds, callback: CreateBatchTransactionCallback): void;
/**
* Create a new session.
*
* @typedef {object} CreateSessionOptions
* @property {Object.<string, string>} [labels] The labels for the session.
*
* * Label keys must be between 1 and 63 characters long and must conform to
* the following regular expression: `[a-z]([-a-z0-9]*[a-z0-9])?`.
* * Label values must be between 0 and 63 characters long and must conform
* to the regular expression `([a-z]([-a-z0-9]*[a-z0-9])?)?`.
* * No more than 64 labels can be associated with a given session.
* @property {object} [gaxOptions] Request configuration options,
* See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions}
* for more details.
*/
/**
* @typedef {array} CreateSessionResponse
* @property {Session} 0 The newly created session.
* @property {object} 1 The full API response.
*/
/**
* @callback CreateSessionCallback
* @param {?Error} err Request error, if any.
* @param {Session} session The newly created session.
* @param {object} apiResponse The full API response.
*/
/**
* 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 {@link v1.SpannerClient#createSession}.
*
* @see {@link v1.SpannerClient#createSession}
* @see [CreateSession API Documentation](https://cloud.google.com/spanner/docs/reference/rpc/google.spanner.v1#google.spanner.v1.Spanner.CreateSession)
*
* @param {CreateSessionOptions} [options] Configuration object.
* @param {CreateSessionCallback} [callback] Callback function.
* @returns {Promise<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];
* });
* ```
*/
createSession(options: CreateSessionOptions): Promise<CreateSessionResponse>;
createSession(callback: CreateSessionCallback): void;
createSession(options: CreateSessionOptions, callback: CreateSessionCallback): void;
/**
* @typedef {array} CreateTableResponse
* @property {Table} 0 The new {@link Table}.
* @property {google.longrunning.Operation} 1 An {@link Operation} object that can be used to check
* the status of the request.
* @property {object} 2 The full API response.
*/
/**
* @callback CreateTableCallback
* @param {?Error} err Request error, if any.
* @param {Table} table The new {@link Table}.
* @param {google.longrunning.Operation} operation An {@link Operation} object that can be used to
* check the status of the request.
* @param {object} apiResponse The full API response.
*/
/**
* Create a table.
*
* Wrapper around {@link Database#updateSchema}.
*
* @see {@link Database#updateSchema}
*
* @param {string} schema A DDL CREATE statement describing the table.
* @param {object} [gaxOptions] Request configuration options,
* See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions}
* for more details.
* @param {CreateTableCallback} [callback] Callback function.
* @returns {Promise<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.
* });
* ```
*/
createTable(schema: Schema, gaxOptions?: CallOptions): Promise<CreateTableResponse>;
createTable(schema: Schema, callback: CreateTableCallback): void;
createTable(schema: Schema, gaxOptions: CallOptions, callback: CreateTableCallback): void;
/**
* Decorates transaction so that when end() is called it will return the session
* back into the pool.
*
* @private
*
* @param {Session} session The session to release.
* @param {Transaction} transaction The transaction to observe.
* @returns {Transaction}
*/
private _releaseOnEnd;
/**
* @typedef {array} DatabaseDeleteResponse
* @property {object} 0 The full API response.
*/
/**
* @callback DatabaseDeleteCallback
* @param {?Error} err Request error, if any.
* @param {object} apiResponse The full API response.
*/
/**
* Delete the database.
*
* Wrapper around {@link v1.DatabaseAdminClient#dropDatabase}.
*
* @see {@link v1.DatabaseAdminClient#dropDatabase}
* @see [DropDatabase API Documentation](https://cloud.google.com/spanner/docs/reference/rpc/google.spanner.admin.database.v1#google.spanner.admin.database.v1.DatabaseAdmin.DropDatabase)
*
* @param {object} [gaxOptions] Request configuration options,
* See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions}
* for more details.
* @param {DatabaseDeleteCallback} [callback] Callback function.
* @returns {Promise<DatabaseDeleteResponse>}
*
* @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) {
* const apiResponse = data[0];
* });
* ```
*/
delete(gaxOptions?: CallOptions): Promise<DatabaseDeleteResponse>;
delete(callback: DatabaseDeleteCallback): void;
delete(gaxOptions: CallOptions, callback: DatabaseDeleteCallback): void;
/**
* @typedef {array} DatabaseExistsResponse
* @property {boolean} 0 Whether the {@link Database} exists.
*/
/**
* @callback DatabaseExistsCallback
* @param {?Error} err Request error, if any.
* @param {boolean} exists Whether the {@link Database} exists.
*/
/**
* Check if a database exists.
*
* @method Database#exists
* @param {object} [gaxOptions] Request configuration options,
* See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions}
* for more details.
* @param {DatabaseExistsCallback} [callback] Callback function.
* @returns {Promise<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];
* });
* ```
*/
exists(gaxOptions?: CallOptions): Promise<[boolean]>;
exists(callback: ExistsCallback): void;
exists(gaxOptions: CallOptions, callback: ExistsCallback): void;
/**
* @typedef {array} GetDatabaseResponse
* @property {Database} 0 The {@link Database}.
* @property {object} 1 The full API response.
*/
/**
* @callback GetDatabaseCallback
* @param {?Error} err Request error, if any.
* @param {Database} database The {@link Database}.
* @param {object} apiResponse The full API response.
*/
/**
* 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.
*
* @param {options} [options] Configuration object.
* @param {boolean} [options.autoCreate=false] Automatically create the
* object if it does not exist.
* @param {object} [options.gaxOptions] Request configuration options,
* See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions}
* for more details.
* @param {GetDatabaseCallback} [callback] Callback function.
* @returns {Promise<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) {
* const database = data[0];
* const apiResponse = data[0];
* });
* ```
*/
get(options?: GetDatabaseConfig): Promise<DatabaseResponse>;
get(callback: DatabaseCallback): void;
get(options: GetDatabaseConfig, callback: DatabaseCallback): void;
/**
* @typedef {array} GetDatabaseMetadataResponse
* @property {object} 0 The {@link Database} metadata.
* @property {object} 1 The full API response.
*/
/**
* @callback GetDatabaseMetadataCallback
* @param {?Error} err Request error, if any.
* @param {object} metadata The {@link Database} metadata.
* @param {object} apiResponse The full API response.
*/
/**
* Get the database's metadata.
*
* Wrapper around {@link v1.DatabaseAdminClient#getDatabase}.
*
* @see {@link v1.DatabaseAdminClient#getDatabase}
* @see [GetDatabase API Documentation](https://cloud.google.com/spanner/docs/reference/rpc/google.spanner.admin.database.v1#google.spanner.admin.database.v1.DatabaseAdmin.GetDatabase)
* @param {object} [gaxOptions] Request configuration options,
* See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions}
* for more details.
* @param {GetDatabaseMetadataCallback} [callback] Callback function.
* @returns {Promise<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) {
* 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];
* });
* ```
*/
getMetadata(gaxOptions?: CallOptions): Promise<GetDatabaseMetadataResponse>;
getMetadata(callback: GetDatabaseMetadataCallback): void;
getMetadata(gaxOptions: CallOptions, callback: GetDatabaseMetadataCallback): void;
/**
* {@link google.spanner.admin.database.v1#RestoreInfo} structure with restore
* source type enum translated to string form.
*
* @typedef {object} IRestoreInfoTranslatedEnum
*/
/**
* @callback GetRestoreInfoCallback
* @param {?Error} err Request error, if any.
* @param {IRestoreInfoTranslatedEnum | undefined} restoreInfo Contains the restore
* information for the database if it was restored from a backup.
*/
/**
* Retrieves the restore information of the database.
*
* @see {@link #getMetadata}
*
* @method Database#getRestoreInfo
* @param {object} [gaxOptions] Request configuration options,
* See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions}
* for more details.
* @param {GetRestoreInfoCallback} [callback] Callback function.
* @returns {Promise<IRestoreInfoTranslatedEnum | undefined>} When resolved,
* contains the restore information for the database if it was restored
* from a backup.
*
* @example
* ```
* const {Spanner} = require('@google-cloud/spanner');
* const spanner = new Spanner();
* const instance = spanner.instance('my-instance');
* const database = instance.database('my-database');
* const restoreInfo = await database.getRestoreInfo();
* console.log(`Database restored from ${restoreInfo.backupInfo.backup}`);
* ```
*/
getRestoreInfo(options?: CallOptions): Promise<IRestoreInfoTranslatedEnum | undefined>;
getRestoreInfo(callback: GetRestoreInfoCallback): void;
getRestoreInfo(options: CallOptions, callback: GetRestoreInfoCallback): void;
/**
* @callback GetStateCallback
* @param {?Error} err Request error, if any.
* @param {EnumKey<typeof, google.spanner.admin.database.v1.Database.State> | undefined} state
* Contains the current state of the database if the state is defined.
*/
/**
* Retrieves the state of the database.
*
* The database state indicates if the database is ready after creation or
* after being restored from a backup.
*
* @see {@link #getMetadata}
*
* @method Database#getState
* @param {object} [gaxOptions] Request configuration options,
* See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions}
* for more details.
* @param {GetStateCallback} [callback] Callback function.
* @returns {Promise<EnumKey<typeof, google.spanner.admin.database.v1.Database.State> | undefined>}
* When resolved, contains the current state of the database if the state
* is defined.
*
* @example
* ```
* const {Spanner} = require('@google-cloud/spanner');
* const spanner = new Spanner();
* const instance = spanner.instance('my-instance');
* const database = instance.database('my-database');
* const state = await database.getState();
* const isReady = (state === 'READY');
* ```
*/
getState(options?: CallOptions): Promise<EnumKey<typeof databaseAdmin.spanner.admin.database.v1.Database.State> | undefined>;
getState(callback: GetStateCallback): void;
getState(options: CallOptions, callback: GetStateCallback): void;
/**
* Retrieves the dialect of the database
*
* @see {@link #getMetadata}
*
* @method Database#getDatabaseDialect
*
* @param {object} [gaxOptions] Request configuration options,
* See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions}
* for more details.
* @param {GetDatabaseDialectCallback} [callback] Callback function.
* @returns {Promise<EnumKey<typeof, databaseAdmin.spanner.admin.database.v1.DatabaseDialect> | undefined>}
* When resolved, contains the database dialect of the database if the dialect is defined.
* @example
* const {Spanner} = require('@google-cloud/spanner');
* const spanner = new Spanner();
* const instance = spanner.instance('my-instance');
* const database = instance.database('my-database');
* const dialect = await database.getDatabaseDialect();
* const isGoogleSQL = (dialect === 'GOOGLE_STANDARD_SQL');
* const isPostgreSQL = (dialect === 'POSTGRESQL');
*/
getDatabaseDialect(options?: CallOptions): Promise<EnumKey<typeof databaseAdmin.spanner.admin.database.v1.DatabaseDialect> | undefined>;
getDatabaseDialect(callback: GetDatabaseDialectCallback): void;
getDatabaseDialect(options: CallOptions, callback: GetDatabaseDialectCallback): void;
/**
* @typedef {array} GetSchemaResponse
* @property {string[]} 0 An array of database DDL statements.
* @property {object} 1 The full API response.
*/
/**
* @callback GetSchemaCallback
* @param {?Error} err Request error, if any.
* @param {string[]} statements An array of database DDL statements.
* @param {object} apiResponse The full API response.
*/
/**
* Get this database's schema as a list of formatted DDL statements.
*
* Wrapper around {@link v1.DatabaseAdminClient#getDatabaseDdl}.
*
* @see {@link v1.DatabaseAdminClient#getDatabaseDdl}
* @see [Data Definition Language (DDL)](https://cloud.google.com/spanner/docs/data-definition-language)
* @see [GetDatabaseDdl API Documentation](https://cloud.google.com/spanner/docs/reference/rpc/google.spanner.admin.database.v1#google.spanner.admin.database.v1.DatabaseAdmin.GetDatabaseDdl)
*
* @param {object} [gaxOptions] Request configuration options,
* See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions}
* for more details.
* @param {GetSchemaCallback} [callback] Callback function.
* @returns {Promise<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];
* });
* ```
*/
getSchema(options?: CallOptions): Promise<GetSchemaResponse>;
getSchema(callback: GetSchemaCallback): void;
getSchema(options: CallOptions, callback: GetSchemaCallback): void;
/**
* Options object for requested policy version.
*
* @typedef {object} GetIamPolicyOptions
* @property {number|null} [requestedPolicyVersion] policy version requested, possible values are 0, 1 and 3,
* See {@link https://cloud.google.com/iam/docs/policies#versions} for more details
* @property {object} [gaxOptions] Request configuration options,
* See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions}
* for more details.
*/
/**
* @callback GetIamPolicyCallback
* @param {?Error} err Request error, if any.
* @param {google.iam.v1.Policy| undefined} policy Returns policy for the give database
*/
/**
* Retrieves the policy of the database.
*
* A Policy is a collection of bindings. A binding binds one or more members, or principals,
* to a single role. Principals can be user accounts, service accounts, Google groups, and
* domains (such as G Suite). A role is a named list of permissions; each role can be an IAM
* predefined role or a user-created custom role.
*
* @see {@link #getIamPolicy}
*
* @method Database#getIamPolicy
* @param {object} [options] requestedPolicyVersion and gax options(configuration options)
* See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html}
* for more details on gax options.
* @param {GetIamPolicyCallback} [callback] Callback function.
* @returns {Promise<Policy | undefined>}
* When resolved, contains the current policy of 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');
* const policy = await database.getIamPolicy();
* console.log(policy.bindings, policy.version, policy.etag, policy.auditConfigs)
* const policyWithVersion specified = await database.getIamPolicy({requestedPolicyVersion: 3});
* ```
*/
getIamPolicy(options?: GetIamPolicyOptions): Promise<GetIamPolicyResponse>;
getIamPolicy(callback: GetIamPolicyCallback): void;
getIamPolicy(options: GetIamPolicyOptions, callback: GetIamPolicyCallback): void;
/**
* Options object for listing sessions.
*
* @typedef {object} GetSessionsOptions
* @property {string} [filter] An expression for filtering the results of the
* request. Filter rules are case insensitive. The fields eligible for
* filtering are:
* - **`name`**
* - **`display_name`**
* - **`labels.key`** where key is the name of a label
*
* Some examples of using filters are:
* - **`name:*`** The instance has a name.
* - **`name:Howl`** The instance's name is howl.
* - **`labels.env:*`** The instance has the label env.
* - **`labels.env:dev`** The instance's label env has the value dev.
* - **`name:howl labels.env:dev`** The instance's name is howl and it has
* the label env with value dev.
* @property {number} [pageSize] Maximum number of results per page.
* @property {string} [pageToken] A previously-returned page token
* representing part of the larger set of results to view.
* @property {object} [gaxOptions] Request configuration options,
* See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions}
* for more details.
*/
/**
* @typedef {array} GetSessionsResponse
* @property {Session[]} 0 Array of {@link Session} instances.
* @property {object} 1 A query object to receive more results.
* @property {object} 2 The full API response.
*/
/**
* @callback GetSessionsCallback
* @param {?Error} err Request error, if any.
* @param {Session[]} instances Array of {@link Session} instances.
* @param {object} nextQuery A query object to receive more results.
* @param {object} apiResponse The full API response.
*/
/**
* Gets a list of sessions.
*
* Wrapper around {@link v1.SpannerClient#listSessions}
*
* @see {@link v1.SpannerClient#listSessions}
* @see [ListSessions API Documentation](https://cloud.google.com/spanner/docs/reference/rpc/google.spanner.v1#google.spanner.v1.Spanner.ListSessions)
*
* @param {GetSessionsOptions} [options] Options object for listing sessions.
* @param {GetSessionsCallback} [callback] Callback function.
* @returns {Promise<GetSessionsResponse>}
*
* @example
* ```
* const {Spanner} = require('@google-cloud/spanner');
* const spanner = new Spanner();
*
* const instance = spanner.instance('my-instance');
* const database = instance.database('my-database');
*
* database.getSessions(function(err, sessions) {
* // `sessions` is an array of `Session` objects.
* });
*
* //-
* // To control how many API requests are made and page through the results
* // manually, set `autoPaginate` to `false`.
* //-
* function callback(err, sessions, nextQuery, apiResponse) {
* if (nextQuery) {
* // More results exist.
* database.getSessions(nextQuery, callback);
* }
* }
*
* database.getInstances({
* gaxOptions: {autoPaginate: false}
* }, callback);
*
* //-
* // If the callback is omitted, we'll return a Promise.
* //-
* database.getInstances().then(function(data) {
* const sessions = data[0];
* });
* ```
*/
getSessions(options?: GetSessionsOptions): Promise<GetSessionsResponse>;
getSessions(callback: GetSessionsCallback): void;
getSessions(options: GetSessionsOptions, callback: GetSessionsCallback): void;
/**
* Get a list of sessions as a readable object stream.
*
* Wrapper around {@link v1.SpannerClient#listSessions}
*
* @see {@link v1.SpannerClient#listSessions}
* @see [ListSessions API Documentation](https://cloud.google.com/spanner/docs/reference/rpc/google.spanner.v1#google.spanner.v1.Spanner.ListSessions)
*
* @method Spanner#getSessionsStream
* @param {GetSessionsOptions} [options] Options object for listing sessions.
* @returns {ReadableStream} A readable stream that emits {@link Session}
* instances.
*
* @example
* ```
* const {Spanner} = require('@google-cloud/spanner');
* const spanner = new Spanner();
*
* const instance = spanner.instance('my-instance');
* const database = instance.database('my-database');
*
* database.getSessionsStream()
* .on('error', console.error)
* .on('data', function(database) {
* // `sessions` is a `Session` object.
* })
* .on('end', function() {
* // All sessions retrieved.
* });
*
* //-
* // If you anticipate many results, you can end a stream early to prevent
* // unnecessary processing and API requests.
* //-
* database.getSessionsStream()
* .on('data', function(session) {
* this.end();
* });
* ```
*/
getSessionsStream(options?: GetSessionsOptions): NodeJS.ReadableStream;
/**
* @typedef {array} GetSnapshotResponse
* @property {Snapshot} 0 The snapshot object.
*/
/**
* @callback GetSnapshotCallback
* @param {?Error} err Request error, if any.
* @param {Snapshot} snapshot The snapshot object.
*/
/**
* Get a read only {@link Snapshot} transaction.
*
* Wrapper around {@link v1.SpannerClient#beginTransaction}.
*
* **NOTE:** When finished with the Snapshot, {@link Snapshot#end} should be
* called to release the underlying {@link Session}. **Failure to do could
* result in a Session leak.**
*
* **NOTE:** Since the returned {@link Snapshot} transaction is not a
* single-use transaction, it is invalid to set the `minReadTimestamp` and
* `maxStaleness` parameters in {@link TimestampBounds} as those parameters
* can only be set for single-use transactions.
* https://cloud.google.com/spanner/docs/reference/rest/v1/TransactionOptions#bounded-staleness
*
* @see {@link v1.SpannerClient#beginTransaction}
*
* @param {TimestampBounds} [options] Timestamp bounds.
* @param {GetSnapshotCallback} [callback] Callback function.
* @returns {Promise<GetSnapshotResponse>}
*
* @example
* ```
* const {Spanner} = require('@google-cloud/spanner');
* const spanner = new Spanner();
*
* const instance = spanner.instance('my-instance');
* const database = instance.database('my-database');
*
* database.getSnapshot(function(err, transaction) {
* if (err) {
* // Error handling omitted.
* }
*
* // Should be called when finished with Snapshot.
* transaction.end();
* });
* ```
*
* @example If the callback is omitted, we'll return a Promise.
* ```
* database.getSnapshot().then(function(data) {
* const transaction = data[0];
* });
* ```
*
* @example <caption>include:samples/transaction.js</caption>
* region_tag:spanner_read_only_transaction
* Read-only transaction:
*/
getSnapshot(options?: TimestampBounds): Promise<[Snapshot]>;
getSnapshot(callback: GetSnapshotCallback): void;
getSnapshot(options: TimestampBounds, callback: GetSnapshotCallback): void;
/**
* @typedef {array} GetTransactionResponse
* @property {Transaction} 0 The transaction object.
*/
/**
* @callback GetTransactionCallback
* @param {?Error} err Request error, if any.
* @param {Transaction} transaction The transaction object.
*/
/**
* Get a read/write ready {@link Transaction} object.
*
* **NOTE:** In the event that you encounter an error while reading/writing,
* if you decide to forgo calling {@link Transaction#commit} or
* {@link Transaction#rollback}, then you need to call
* {@link Transaction#end} to release the underlying {@link Session} object.
* **Failure to do could result in a Session leak.**
*
* Wrapper around {@link v1.SpannerClient#beginTransaction}.
*
* @see {@link v1.SpannerClient#beginTransaction}
*
* @param {GetTransactionCallback} [callback] Callback function.
* @returns {Promise<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) {});
*
* ```
* @example If the callback is omitted, we'll return a Promise.
* ```
* database.getTransaction().then(function(data) {
* const transaction = data[0];
* });
* ```
*/
getTransaction(optionsOrCallback?: GetTransactionOptions): Promise<[Transaction]>;
getTransaction(callback: GetTransactionCallback): void;
/**
* Query object for listing database operations.
*
* @typedef {object} GetDatabaseOperationsOptions
* @property {string} [filter] An expression for filtering the results of the
* reque