@google-cloud/spanner
Version:
Cloud Spanner Client Library for Node.js
350 lines (349 loc) • 14.9 kB
TypeScript
/**
* Copyright 2020 Google LLC
* 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 { Instance } from './instance';
import { IOperation, LongRunningCallback, RequestCallback, ResourceCallback, NormalCallback } from './common';
import { EnumKey, RequestConfig, TranslateEnumKeys } from '.';
import { CallOptions, Metadata, Operation as GaxOperation } from 'google-gax';
import { PreciseDate } from '@google-cloud/precise-date';
import { google as databaseAdmin } from '../protos/protos';
import { common as p } from 'protobufjs';
export type CreateBackupCallback = LongRunningCallback<Backup>;
export type CopyBackupCallback = LongRunningCallback<Backup>;
export interface CreateBackupGaxOperation extends GaxOperation {
metadata: Metadata & databaseAdmin.spanner.admin.database.v1.ICreateBackupMetadata;
}
export type CreateBackupResponse = [
Backup,
CreateBackupGaxOperation,
IOperation
];
export interface CreateBackupOptions {
databasePath: string;
expireTime: string | number | p.ITimestamp | PreciseDate;
versionTime?: string | number | p.ITimestamp | PreciseDate;
encryptionConfig?: databaseAdmin.spanner.admin.database.v1.ICreateBackupEncryptionConfig;
gaxOptions?: CallOptions;
}
export interface CopyBackupGaxOperation extends GaxOperation {
metadata: Metadata & databaseAdmin.spanner.admin.database.v1.ICopyBackupMetadata;
}
export type CopyBackupResponse = [Backup, CopyBackupGaxOperation, IOperation];
export interface CopyBackupOptions extends databaseAdmin.spanner.admin.database.v1.ICopyBackupRequest {
gaxOptions?: CallOptions;
}
/**
* IBackup structure with backup state enum translated to string form.
*/
type IBackupTranslatedEnum = TranslateEnumKeys<databaseAdmin.spanner.admin.database.v1.IBackup, 'state', typeof databaseAdmin.spanner.admin.database.v1.Backup.State>;
export type GetMetadataResponse = [IBackupTranslatedEnum];
type GetMetadataCallback = RequestCallback<IBackupTranslatedEnum>;
type UpdateExpireTimeCallback = RequestCallback<databaseAdmin.spanner.admin.database.v1.IBackup>;
type DeleteCallback = RequestCallback<databaseAdmin.protobuf.IEmpty>;
interface BackupRequest {
(config: RequestConfig, callback: ResourceCallback<GaxOperation, IOperation>): void;
<T>(config: RequestConfig, callback: RequestCallback<T>): void;
}
export type GetStateCallback = NormalCallback<EnumKey<typeof databaseAdmin.spanner.admin.database.v1.Backup.State>>;
export type GetExpireTimeCallback = NormalCallback<PreciseDate>;
export type ExistsCallback = NormalCallback<boolean>;
/**
* The {@link Backup} class represents a Cloud Spanner backup.
*
* Create a `Backup` object to interact with or create a Cloud Spanner backup or copy a backup.
*
* @class
*
* @example
* ```
* const {Spanner} = require('@google-cloud/spanner');
* const spanner = new Spanner();
* const instance = spanner.instance('my-instance');
* const backup = instance.backup('my-backup');
* ```
*
* ```
* * @example
* const {Spanner} = require('@google-cloud/spanner');
* const spanner = new Spanner();
* const instance = spanner.instance('my-instance');
* const sourceBackup = instance.backup('my-source-backup');
* const copyBackup = instance.copyBackup('my-copy-backup', 'my-source-backup');
* ```
*/
declare class Backup {
id: string;
formattedName_: string;
instanceFormattedName_: string;
resourceHeader_: {
[k: string]: string;
};
request: BackupRequest;
metadata?: databaseAdmin.spanner.admin.database.v1.IBackup;
sourceName: string | undefined;
constructor(instance: Instance, name: string, sourceName?: string);
/**
* @typedef {object} CreateBackupOptions
* @property {string} databasePath The database path.
* @property {string|number|google.protobuf.Timestamp|external:PreciseDate}
* expireTime The expire time of the backup.
* @property {string|number|google.protobuf.Timestamp|external:PreciseDate}
* versionTime Take a backup of the state of the database at this time.
* @property {google.spanner.admin.database.v1.ICreateBackupEncryptionConfig}
* encryptionConfig An encryption configuration describing the
* encryption type and key resources in Cloud KMS to be used to encrypt
* the backup.
* @property {object} [gaxOptions] The request configuration options,
* See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions}
* for more details.
*/
/**
* @typedef {array} CreateBackupResponse
* @property {Backup} 0 The new {@link Backup}.
* @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 CreateBackupCallback
* @param {?Error} err Request error, if any.
* @param {Backup} backup The new {@link Backup}.
* @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 backup.
*
* @method Backup#create
* @param {CreateBackupOptions} options Parameters for creating a backup.
* @param {CallOptions} [options.gaxOptions] The request configuration
* options, See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions}
* for more details.
* @param {CreateBackupCallback} [callback] Callback function.
* @returns {Promise<CreateBackupResponse>} When resolved, the backup
* operation will have started, but will not have necessarily completed.
*
* @example
* ```
* const {Spanner} = require('@google-cloud/spanner');
* const spanner = new Spanner();
* const instance = spanner.instance('my-instance');
* const oneDay = 1000 * 60 * 60 * 24;
* const expireTime = Date.now() + oneDay;
* const versionTime = Date.now() - oneDay;
* const backup = instance.backup('my-backup');
* const [, backupOperation] = await backup.create({
* databasePath: 'projects/my-project/instances/my-instance/databases/my-database',
* expireTime: expireTime,
* versionTime: versionTime,
* encryptionConfig: {
* encryptionType: 'CUSTOMER_MANAGED_ENCRYPTION',
* kmsKeyName: 'projects/my-project-id/my-region/keyRings/my-key-ring/cryptoKeys/my-key',
* },
* });
* // Await completion of the backup operation.
* await backupOperation.promise();
* ```
*/
create(options: CreateBackupOptions | CopyBackupOptions): Promise<CreateBackupResponse> | Promise<CopyBackupResponse>;
create(options: CreateBackupOptions | CopyBackupOptions, callback: CreateBackupCallback | CopyBackupCallback): void;
/**
* @typedef {array} GetMetadataResponse
* @property {object} 0 The {@link Backup} metadata.
* @property {object} 1 The full API response.
*/
/**
* @callback GetMetadataCallback
* @param {?Error} err Request error, if any.
* @param {object} metadata The {@link Backup} metadata.
* @param {object} apiResponse The full API response.
*/
/**
* Retrieves backup's metadata.
*
* @see {@link #getState}
* @see {@link #getExpireTime}
*
* @method Backup#getMetadata
* @param {object} [gaxOptions] Request configuration options,
* See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions}
* for more details.
* @param {GetMetadataCallback} [callback] Callback function.
* @returns {Promise<GetMetadataResponse>}
*
* @example
* ```
* const {Spanner} = require('@google-cloud/spanner');
* const spanner = new Spanner();
* const instance = spanner.instance('my-instance');
* const backup = instance.backup('my-backup');
* const [backupInfo] = await backup.getMetadata();
* console.log(`${backupInfo.name}: size=${backupInfo.sizeBytes}`);
* ```
*/
getMetadata(gaxOptions?: CallOptions): Promise<GetMetadataResponse>;
getMetadata(callback: GetMetadataCallback): void;
getMetadata(gaxOptions: CallOptions, callback: GetMetadataCallback): void;
/**
* Retrieves the state of the backup.
*
* The backup state indicates if the backup has completed.
*
* @see {@link #getMetadata}
*
* @method Backup#getState
* @param {GetStateCallback} [callback] Callback function.
* @returns {Promise<EnumKey<typeof, databaseAdmin.spanner.admin.database.v1.Backup.State> | undefined>}
* When resolved, contains the current state of the backup if it exists.
*
* @example
* ```
* const {Spanner} = require('@google-cloud/spanner');
* const spanner = new Spanner();
* const instance = spanner.instance('my-instance');
* const backup = instance.backup('my-backup');
* const state = await backup.getState();
* const backupCompleted = (state === 'READY');
* ```
*/
getState(): Promise<EnumKey<typeof databaseAdmin.spanner.admin.database.v1.Backup.State> | undefined | null>;
getState(callback: GetStateCallback): void;
/**
* Retrieves the expiry time of the backup.
*
* @see {@link #updateExpireTime}
* @see {@link #getMetadata}
*
* @method Backup#getExpireTime
* @returns {Promise<external:PreciseDate>} When resolved, contains the
* current expire time of the backup if it exists.
*
* @example
* ```
* const {Spanner} = require('@google-cloud/spanner');
* const spanner = new Spanner();
* const instance = spanner.instance('my-instance');
* const backup = instance.backup('my-backup');
* const expireTime = await backup.getExpireTime();
* console.log(`Backup expires on ${expireTime.toISOString()}`);
* ```
*/
getExpireTime(): Promise<PreciseDate | undefined>;
getExpireTime(callback: GetExpireTimeCallback): void;
/**
* Checks whether the backup exists.
*
* @see {@link #getMetadata}
*
* @method Backup#exists
* @returns {Promise<boolean>} When resolved, contains true if the backup
* exists and false if it does not exist.
*
* @example
* ```
* const {Spanner} = require('@google-cloud/spanner');
* const spanner = new Spanner();
* const instance = spanner.instance('my-instance');
* const backup = instance.backup('my-backup');
* const alreadyExists = await backup.exists();
* console.log(`Does backup exist? ${alreadyExists}`);
* ```
*/
exists(): Promise<boolean>;
exists(callback: ExistsCallback): void;
/**
* @callback UpdateExpireTimeCallback
* @param {?Error} err Request error, if any.
* @param {google.spanner.admin.database.v1.IBackup} backup The updated
* backup.
*/
/**
* Sets the expiry time of a backup.
*
* @see {@link #getExpireTime}
*
* @method Backup#updateExpireTime
* @param {string|number|google.protobuf.Timestamp|external:PreciseDate}
* expireTime The expiry time to update with.
* @param {object} [gaxOptions] Request configuration options,
* See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions}
* for more details.
* @param {UpdateExpireTimeCallback} [callback] Callback function.
* @returns {Promise<google.spanner.admin.database.v1.IBackup>} When resolved,
* the backup's expire time will have been updated.
*
* @example
* ```
* const {Spanner} = require('@google-cloud/spanner');
* const spanner = new Spanner();
* const instance = spanner.instance('my-instance');
* const backup = instance.backup('my-backup');
* const oneDay = 1000 * 60 * 60 * 24;
* const newExpireTime = Spanner.timestamp(Date.now() + oneDay);
* await backup.updateExpireTime(newExpireTime);
* ```
*/
updateExpireTime(expireTime: string | number | p.ITimestamp | PreciseDate): Promise<databaseAdmin.spanner.admin.database.v1.IBackup>;
updateExpireTime(expireTime: string | number | p.ITimestamp | PreciseDate, gaxOptions?: CallOptions): Promise<databaseAdmin.spanner.admin.database.v1.IBackup>;
updateExpireTime(expireTime: string | number | p.ITimestamp | PreciseDate, callback: UpdateExpireTimeCallback): void;
updateExpireTime(expireTime: string | number | p.ITimestamp | PreciseDate, gaxOptions: CallOptions, callback: UpdateExpireTimeCallback): void;
/**
* Deletes a backup.
*
* @method Backup#delete
* @param {object} [gaxOptions] Request configuration options,
* See {@link https://googleapis.dev/nodejs/google-gax/latest/interfaces/CallOptions.html|CallOptions}
* for more details.
* @param {DeleteBackupCallback} [callback] Callback function.
* @returns {Promise<void>} When resolved, the backup will have been deleted.
*
* @example
* ```
* const {Spanner} = require('@google-cloud/spanner');
* const spanner = new Spanner();
* const instance = spanner.instance('my-instance');
* const backup = instance.backup('my-backup');
* await backup.delete();
* ```
*/
delete(gaxOptions?: CallOptions): Promise<databaseAdmin.protobuf.IEmpty>;
delete(callback: DeleteCallback): void;
delete(gaxOptions: CallOptions, callback: DeleteCallback): void;
/**
* Format the backup name to include the instance name.
*
* @private
*
* @param {string} instanceName The formatted instance name.
* @param {string} name The table name.
* @returns {string}
*
* @example
* ```
* Backup.formatName_(
* 'projects/grape-spaceship-123/instances/my-instance',
* 'my-backup'
* );
* // 'projects/grape-spaceship-123/instances/my-instance/backups/my-backup'
* ```
*/
static formatName_(instanceName: string, name: string): string;
}
/**
* Reference to the {@link Backup} class.
* @name module:@google-cloud/spanner.Backup
* @see Backup
*/
export { Backup };