diff --git a/lib/sqlite3.d.ts b/lib/sqlite3.d.ts index 15e66230e..9b17fd8f4 100644 --- a/lib/sqlite3.d.ts +++ b/lib/sqlite3.d.ts @@ -139,6 +139,154 @@ export class Database extends events.EventEmitter { wait(callback?: (param: null) => void): this; interrupt(): void; + + + backup(path:string, callback?: ()=>void): Backup + backup(filename:string, destDbName:string, sourceDbName:string, filenameIsDest:boolean, callback?: ()=>void): Backup +} + +/** + * + * A class for managing an sqlite3_backup object. For consistency + * with other node-sqlite3 classes, it maintains an internal queue + * of calls. + * + * Intended usage from node: + * + * var db = new sqlite3.Database('live.db'); + * var backup = db.backup('backup.db'); + * ... + * // in event loop, move backup forward when we have time. + * if (backup.idle) { backup.step(NPAGES); } + * if (backup.completed) { ... success ... } + * if (backup.failed) { ... sadness ... } + * // do other work in event loop - fine to modify live.db + * ... + * + * Here is how sqlite's backup api is exposed: + * + * - `sqlite3_backup_init`: This is implemented as + * `db.backup(filename, [callback])` or + * `db.backup(filename, destDbName, sourceDbName, filenameIsDest, [callback])`. + * - `sqlite3_backup_step`: `backup.step(pages, [callback])`. + * - `sqlite3_backup_finish`: `backup.finish([callback])`. + * - `sqlite3_backup_remaining`: `backup.remaining`. + * - `sqlite3_backup_pagecount`: `backup.pageCount`. + * + * There are the following read-only properties: + * + * - `backup.completed` is set to `true` when the backup + * succeeeds. + * - `backup.failed` is set to `true` when the backup + * has a fatal error. + * - `backup.message` is set to the error string + * the backup has a fatal error. + * - `backup.idle` is set to `true` when no operation + * is currently in progress or queued for the backup. + * - `backup.remaining` is an integer with the remaining + * number of pages after the last call to `backup.step` + * (-1 if `step` not yet called). + * - `backup.pageCount` is an integer with the total number + * of pages measured during the last call to `backup.step` + * (-1 if `step` not yet called). + * + * There is the following writable property: + * + * - `backup.retryErrors`: an array of sqlite3 error codes + * that are treated as non-fatal - meaning, if they occur, + * backup.failed is not set, and the backup may continue. + * By default, this is `[sqlite3.BUSY, sqlite3.LOCKED]`. + * + * The `db.backup(filename, [callback])` shorthand is sufficient + * for making a backup of a database opened by node-sqlite3. If + * using attached or temporary databases, or moving data in the + * opposite direction, the more complete (but daunting) + * `db.backup(filename, destDbName, sourceDbName, filenameIsDest, [callback])` + * signature is provided. + * + * A backup will finish automatically when it succeeds or a fatal + * error occurs, meaning it is not necessary to call `db.finish()`. + * By default, SQLITE_LOCKED and SQLITE_BUSY errors are not + * treated as failures, and the backup will continue if they + * occur. The set of errors that are tolerated can be controlled + * by setting `backup.retryErrors`. To disable automatic + * finishing and stick strictly to sqlite's raw api, set + * `backup.retryErrors` to `[]`. In that case, it is necessary + * to call `backup.finish()`. + * + * In the same way as node-sqlite3 databases and statements, + * backup methods can be called safely without callbacks, due + * to an internal call queue. So for example this naive code + * will correctly back up a db, if there are no errors: + * + * var backup = db.backup('backup.db'); + * backup.step(-1); + * backup.finish(); + * + */ +export class Backup extends events.EventEmitter { + /** + * `true` when the backup is idle and ready for `step()` to + * be called, `false` when busy. + */ + readonly idle: boolean + + /** + * `true` when the backup has completed, `false` otherwise. + */ + readonly completed: boolean + + /** + * `true` when the backup has failed, `false` otherwise. `Backup.message` + * contains the error message. + */ + readonly failed: boolean + + /** + * Message failure string from sqlite3_errstr() if `Backup.failed` is `true` + */ + readonly message: boolean + + /** + * The number of remaining pages after the last call to `step()`, + * or `-1` if `step()` has never been called. + */ + readonly remaining: number + + /** + * The total number of pages measured during the last call to `step()`, + * or `-1` if `step()` has never been called. + */ + readonly pageCount: number + + + /** + * An array of sqlite3 error codes that are treated as non-fatal - + * meaning, if they occur, `Backup.failed` is not set, and the backup + * may continue. By default, this is `[sqlite3.BUSY, sqlite3.LOCKED]`. + */ + retryErrors: number[] + + /** + * Asynchronously finalize the backup (required). + * + * @param callback Called when the backup is finalized. + */ + finish(callback?: ()=>void): void + + /** + * Asynchronously perform an incremental segment of the backup. + * + * Example: + * + * ``` + * backup.step(5) + * ``` + * + * @param nPages Number of pages to process (5 recommended). + * @param callback Called when the step is completed. + */ + step(nPages: number,callback?: ()=>void): void } export function verbose(): sqlite3;