add backup api that can be run incrementally (#1116)

This exposes the sqlite3 backup api as described at https://sqlite.org/backup.html.

This implementation draws on https://github.com/mapbox/node-sqlite3/pull/883,
extending it to create a backup object that can be used in the background,
without leaving the database locked for an extended period of time.  This is
crucial for making backups of large live databases in a non-disruptive manner.
Example usage:

```
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! backup made */  }
if (backup.failed)    { /* sadness! backup broke */ }
// 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`: This is implemented as `backup.step(pages, [callback])`.
 * `sqlite3_backup_finish`: This is implemented as `backup.finish([callback])`.
 * `sqlite3_backup_remaining`: This is implemented as a `backup.remaining` getter.
 * `sqlite3_backup_pagecount`: This is implemented as a `backup.pageCount` getter.

Some conveniences are added in the node api.

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.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();
```

binding.gyp

@@ -32,6 +32,7 @@
         ]
       ],
       "sources": [
+        "src/backup.cc",
         "src/database.cc",
         "src/node_sqlite3.cc",
         "src/statement.cc"

lib/sqlite3.js

@@ -59,9 +59,11 @@ sqlite3.cached = {
 
 var Database = sqlite3.Database;
 var Statement = sqlite3.Statement;
+var Backup = sqlite3.Backup;
 
 inherits(Database, EventEmitter);
 inherits(Statement, EventEmitter);
+inherits(Backup, EventEmitter);
 
 // Database#prepare(sql, [bind1, bind2, ...], [callback])
 Database.prototype.prepare = normalizeMethod(function(statement, params) {
@@ -99,6 +101,23 @@ Database.prototype.map = normalizeMethod(function(statement, params) {
     return this;
 });
 
+// Database#backup(filename, [callback])
+// Database#backup(filename, destName, sourceName, filenameIsDest, [callback])
+Database.prototype.backup = function() {
+    var backup;
+    if (arguments.length <= 2) {
+        // By default, we write the main database out to the main database of the named file.
+        // This is the most likely use of the backup api.
+        backup = new Backup(this, arguments[0], 'main', 'main', true, arguments[1]);
+    } else {
+        // Otherwise, give the user full control over the sqlite3_backup_init arguments.
+        backup = new Backup(this, arguments[0], arguments[1], arguments[2], arguments[3], arguments[4]);
+    }
+    // Per the sqlite docs, exclude the following errors as non-fatal by default.
+    backup.retryErrors = [sqlite3.BUSY, sqlite3.LOCKED];
+    return backup;
+};
+
 Statement.prototype.map = function() {
     var params = Array.prototype.slice.call(arguments);
     var callback = params.pop();

src/backup.cc

+#include <string.h>
+#include <node.h>
+#include <node_buffer.h>
+#include <node_version.h>
+
+#include "macros.h"
+#include "database.h"
+#include "backup.h"
+
+using namespace node_sqlite3;
+
+Nan::Persistent<FunctionTemplate> Backup::constructor_template;
+
+
+NAN_MODULE_INIT(Backup::Init) {
+    Nan::HandleScope scope;
+
+    Local<FunctionTemplate> t = Nan::New<FunctionTemplate>(New);
+
+    t->InstanceTemplate()->SetInternalFieldCount(1);
+    t->SetClassName(Nan::New("Backup").ToLocalChecked());
+
+    Nan::SetPrototypeMethod(t, "step", Step);
+    Nan::SetPrototypeMethod(t, "finish", Finish);
+
+    NODE_SET_GETTER(t, "idle", IdleGetter);
+    NODE_SET_GETTER(t, "completed", CompletedGetter);
+    NODE_SET_GETTER(t, "failed", FailedGetter);
+    NODE_SET_GETTER(t, "remaining", RemainingGetter);
+    NODE_SET_GETTER(t, "pageCount", PageCountGetter);
+
+    NODE_SET_SETTER(t, "retryErrors", RetryErrorGetter, RetryErrorSetter);
+
+    constructor_template.Reset(t);
+    Nan::Set(target, Nan::New("Backup").ToLocalChecked(),
+        Nan::GetFunction(t).ToLocalChecked());
+}
+
+void Backup::Process() {
+    if (finished && !queue.empty()) {
+        return CleanQueue();
+    }
+
+    while (inited && !locked && !queue.empty()) {
+        Call* call = queue.front();
+        queue.pop();
+
+        call->callback(call->baton);
+        delete call;
+    }
+}
+
+void Backup::Schedule(Work_Callback callback, Baton* baton) {
+    if (finished) {
+        queue.push(new Call(callback, baton));
+        CleanQueue();
+    }
+    else if (!inited || locked || !queue.empty()) {
+        queue.push(new Call(callback, baton));
+    }
+    else {
+        callback(baton);
+    }
+}
+
+template <class T> void Backup::Error(T* baton) {
+    Nan::HandleScope scope;
+
+    Backup* backup = baton->backup;
+    // Fail hard on logic errors.
+    assert(backup->status != 0);
+    EXCEPTION(backup->message, backup->status, exception);
+
+    Local<Function> cb = Nan::New(baton->callback);
+
+    if (!cb.IsEmpty() && cb->IsFunction()) {
+        Local<Value> argv[] = { exception };
+        TRY_CATCH_CALL(backup->handle(), cb, 1, argv);
+    }
+    else {
+        Local<Value> argv[] = { Nan::New("error").ToLocalChecked(), exception };
+        EMIT_EVENT(backup->handle(), 2, argv);
+    }
+}
+
+void Backup::CleanQueue() {
+    Nan::HandleScope scope;
+
+    if (inited && !queue.empty()) {
+        // This backup has already been initialized and is now finished.
+        // Fire error for all remaining items in the queue.
+        EXCEPTION("Backup is already finished", SQLITE_MISUSE, exception);
+        Local<Value> argv[] = { exception };
+        bool called = false;
+
+        // Clear out the queue so that this object can get GC'ed.
+        while (!queue.empty()) {
+            Call* call = queue.front();
+            queue.pop();
+
+            Local<Function> cb = Nan::New(call->baton->callback);
+
+            if (inited && !cb.IsEmpty() &&
+                cb->IsFunction()) {
+                TRY_CATCH_CALL(handle(), cb, 1, argv);
+                called = true;
+            }
+
+            // We don't call the actual callback, so we have to make sure that
+            // the baton gets destroyed.
+            delete call->baton;
+            delete call;
+        }
+
+        // When we couldn't call a callback function, emit an error on the
+        // Backup object.
+        if (!called) {
+            Local<Value> info[] = { Nan::New("error").ToLocalChecked(), exception };
+            EMIT_EVENT(handle(), 2, info);
+        }
+    }
+    else while (!queue.empty()) {
+        // Just delete all items in the queue; we already fired an event when
+        // initializing the backup failed.
+        Call* call = queue.front();
+        queue.pop();
+
+        // We don't call the actual callback, so we have to make sure that
+        // the baton gets destroyed.
+        delete call->baton;
+        delete call;
+    }
+}
+
+NAN_METHOD(Backup::New) {
+    if (!info.IsConstructCall()) {
+        return Nan::ThrowTypeError("Use the new operator to create new Backup objects");
+    }
+
+    int length = info.Length();
+
+    if (length <= 0 || !Database::HasInstance(info[0])) {
+        return Nan::ThrowTypeError("Database object expected");
+    }
+    else if (length <= 1 || !info[1]->IsString()) {
+        return Nan::ThrowTypeError("Filename expected");
+    }
+    else if (length <= 2 || !info[2]->IsString()) {
+        return Nan::ThrowTypeError("Source database name expected");
+    }
+    else if (length <= 3 || !info[3]->IsString()) {
+        return Nan::ThrowTypeError("Destination database name expected");
+    }
+    else if (length <= 4 || !info[4]->IsBoolean()) {
+        return Nan::ThrowTypeError("Direction flag expected");
+    }
+    else if (length > 5 && !info[5]->IsUndefined() && !info[5]->IsFunction()) {
+        return Nan::ThrowTypeError("Callback expected");
+    }
+
+    Database* db = Nan::ObjectWrap::Unwrap<Database>(info[0].As<Object>());
+    Local<String> filename = Local<String>::Cast(info[1]);
+    Local<String> sourceName = Local<String>::Cast(info[2]);
+    Local<String> destName = Local<String>::Cast(info[3]);
+    Local<Boolean> filenameIsDest = Local<Boolean>::Cast(info[4]);
+
+    Nan::ForceSet(info.This(), Nan::New("filename").ToLocalChecked(), filename, ReadOnly);
+    Nan::ForceSet(info.This(), Nan::New("sourceName").ToLocalChecked(), sourceName, ReadOnly);
+    Nan::ForceSet(info.This(), Nan::New("destName").ToLocalChecked(), destName, ReadOnly);
+    Nan::ForceSet(info.This(), Nan::New("filenameIsDest").ToLocalChecked(), filenameIsDest, ReadOnly);
+
+    Backup* backup = new Backup(db);
+    backup->Wrap(info.This());
+
+    InitializeBaton* baton = new InitializeBaton(db, Local<Function>::Cast(info[5]), backup);
+    baton->filename = std::string(*Nan::Utf8String(filename));
+    baton->sourceName = std::string(*Nan::Utf8String(sourceName));
+    baton->destName = std::string(*Nan::Utf8String(destName));
+    baton->filenameIsDest = Nan::To<bool>(filenameIsDest).FromJust();
+    db->Schedule(Work_BeginInitialize, baton);
+
+    info.GetReturnValue().Set(info.This());
+}
+
+void Backup::Work_BeginInitialize(Database::Baton* baton) {
+    assert(baton->db->open);
+    baton->db->pending++;
+    int status = uv_queue_work(uv_default_loop(),
+        &baton->request, Work_Initialize, (uv_after_work_cb)Work_AfterInitialize);
+    assert(status == 0);
+}
+
+void Backup::Work_Initialize(uv_work_t* req) {
+    BACKUP_INIT(InitializeBaton);
+
+    // In case stepping fails, we use a mutex to make sure we get the associated
+    // error message.
+    sqlite3_mutex* mtx = sqlite3_db_mutex(baton->db->_handle);
+    sqlite3_mutex_enter(mtx);
+
+    backup->status = sqlite3_open(baton->filename.c_str(), &backup->_otherDb);
+
+    if (backup->status == SQLITE_OK) {
+        backup->_handle = sqlite3_backup_init(
+            baton->filenameIsDest ? backup->_otherDb : backup->db->_handle,
+            baton->destName.c_str(),
+            baton->filenameIsDest ? backup->db->_handle : backup->_otherDb,
+            baton->sourceName.c_str());
+    }
+    backup->_destDb = baton->filenameIsDest ? backup->_otherDb : backup->db->_handle;
+
+    if (backup->status != SQLITE_OK) {
+        backup->message = std::string(sqlite3_errmsg(backup->_destDb));
+        sqlite3_close(backup->_otherDb);
+        backup->_otherDb = NULL;
+        backup->_destDb = NULL;
+    }
+
+    sqlite3_mutex_leave(mtx);
+}
+
+void Backup::Work_AfterInitialize(uv_work_t* req) {
+    Nan::HandleScope scope;
+
+    BACKUP_INIT(InitializeBaton);
+
+    if (backup->status != SQLITE_OK) {
+        Error(baton);
+        backup->FinishAll();
+    }
+    else {
+        backup->inited = true;
+        Local<Function> cb = Nan::New(baton->callback);
+        if (!cb.IsEmpty() && cb->IsFunction()) {
+            Local<Value> argv[] = { Nan::Null() };
+            TRY_CATCH_CALL(backup->handle(), cb, 1, argv);
+        }
+    }
+    BACKUP_END();
+}
+
+NAN_METHOD(Backup::Step) {
+    Backup* backup = Nan::ObjectWrap::Unwrap<Backup>(info.This());
+
+    REQUIRE_ARGUMENT_INTEGER(0, pages);
+    OPTIONAL_ARGUMENT_FUNCTION(1, callback);
+
+    StepBaton* baton = new StepBaton(backup, callback, pages);
+    backup->GetRetryErrors(baton->retryErrorsSet);
+    backup->Schedule(Work_BeginStep, baton);
+    info.GetReturnValue().Set(info.This());
+}
+
+void Backup::Work_BeginStep(Baton* baton) {
+    BACKUP_BEGIN(Step);
+}
+
+void Backup::Work_Step(uv_work_t* req) {
+    BACKUP_INIT(StepBaton);
+    if (backup->_handle) {
+        backup->status = sqlite3_backup_step(backup->_handle, baton->pages);
+        backup->remaining = sqlite3_backup_remaining(backup->_handle);
+        backup->pageCount = sqlite3_backup_pagecount(backup->_handle);
+    }
+    if (backup->status != SQLITE_OK) {
+        // Text of message is a little awkward to get, since the error is not associated
+        // with a db connection.
+#if SQLITE_VERSION_NUMBER >= 3007015
+        // sqlite3_errstr is a relatively new method
+        backup->message = std::string(sqlite3_errstr(backup->status));
+#else
+        backup->message = "Sqlite error";
+#endif
+        if (baton->retryErrorsSet.size() > 0) {
+            if (baton->retryErrorsSet.find(backup->status) == baton->retryErrorsSet.end()) {
+                backup->FinishSqlite();
+            }
+        }
+    }
+}
+
+void Backup::Work_AfterStep(uv_work_t* req) {
+    Nan::HandleScope scope;
+
+    BACKUP_INIT(StepBaton);
+
+    if (backup->status == SQLITE_DONE) {
+        backup->completed = true;
+    } else if (!backup->_handle) {
+        backup->failed = true;
+    }
+
+    if (backup->status != SQLITE_OK && backup->status != SQLITE_DONE) {
+        Error(baton);
+    }
+    else {
+        // Fire callbacks.
+        Local<Function> cb = Nan::New(baton->callback);
+        if (!cb.IsEmpty() && cb->IsFunction()) {
+            Local<Value> argv[] = { Nan::Null(), Nan::New(backup->status == SQLITE_DONE) };
+            TRY_CATCH_CALL(backup->handle(), cb, 2, argv);
+        }
+    }
+
+    BACKUP_END();
+}
+
+NAN_METHOD(Backup::Finish) {
+    Backup* backup = Nan::ObjectWrap::Unwrap<Backup>(info.This());
+
+    OPTIONAL_ARGUMENT_FUNCTION(0, callback);
+
+    Baton* baton = new Baton(backup, callback);
+    backup->Schedule(Work_BeginFinish, baton);
+    info.GetReturnValue().Set(info.This());
+}
+
+void Backup::Work_BeginFinish(Baton* baton) {
+    BACKUP_BEGIN(Finish);
+}
+
+void Backup::Work_Finish(uv_work_t* req) {
+    BACKUP_INIT(Baton);
+    backup->FinishSqlite();
+}
+
+void Backup::Work_AfterFinish(uv_work_t* req) {
+    Nan::HandleScope scope;
+
+    BACKUP_INIT(Baton);
+    backup->FinishAll();
+
+    // Fire callback in case there was one.
+    Local<Function> cb = Nan::New(baton->callback);
+    if (!cb.IsEmpty() && cb->IsFunction()) {
+        TRY_CATCH_CALL(backup->handle(), cb, 0, NULL);
+    }
+
+    BACKUP_END();
+}
+
+void Backup::FinishAll() {
+    assert(!finished);
+    if (!completed && !failed) {
+        failed = true;
+    }
+    finished = true;
+    CleanQueue();
+    FinishSqlite();
+    db->Unref();
+}
+
+void Backup::FinishSqlite() {
+    if (_handle) {
+        sqlite3_backup_finish(_handle);
+        _handle = NULL;
+    }
+    if (_otherDb) {
+        sqlite3_close(_otherDb);
+        _otherDb = NULL;
+    }
+    _destDb = NULL;
+}
+
+NAN_GETTER(Backup::IdleGetter) {
+    Backup* backup = Nan::ObjectWrap::Unwrap<Backup>(info.This());
+    bool idle = backup->inited && !backup->locked && backup->queue.empty();
+    info.GetReturnValue().Set(idle);
+}
+
+NAN_GETTER(Backup::CompletedGetter) {
+    Backup* backup = Nan::ObjectWrap::Unwrap<Backup>(info.This());
+    info.GetReturnValue().Set(backup->completed);
+}
+
+NAN_GETTER(Backup::FailedGetter) {
+    Backup* backup = Nan::ObjectWrap::Unwrap<Backup>(info.This());
+    info.GetReturnValue().Set(backup->failed);
+}
+
+NAN_GETTER(Backup::RemainingGetter) {
+    Backup* backup = Nan::ObjectWrap::Unwrap<Backup>(info.This());
+    info.GetReturnValue().Set(backup->remaining);
+}
+
+NAN_GETTER(Backup::PageCountGetter) {
+    Backup* backup = Nan::ObjectWrap::Unwrap<Backup>(info.This());
+    info.GetReturnValue().Set(backup->pageCount);
+}
+
+NAN_GETTER(Backup::RetryErrorGetter) {
+    Backup* backup = Nan::ObjectWrap::Unwrap<Backup>(info.This());
+    info.GetReturnValue().Set(Nan::New(backup->retryErrors));
+}
+
+NAN_SETTER(Backup::RetryErrorSetter) {
+    Backup* backup = Nan::ObjectWrap::Unwrap<Backup>(info.This());
+    if (!value->IsArray()) {
+        return Nan::ThrowError("retryErrors must be an array");
+    }
+    Local<Array> array = Local<Array>::Cast(value);
+    backup->retryErrors.Reset(array);
+}
+
+void Backup::GetRetryErrors(std::set<int>& retryErrorsSet) {
+    retryErrorsSet.clear();
+    Local<Array> array = Nan::New(retryErrors);
+    int length = array->Length();
+    for (int i = 0; i < length; i++) {
+        Local<Value> code = Nan::Get(array, i).ToLocalChecked();
+        if (code->IsInt32()) {
+            retryErrorsSet.insert(Nan::To<int32_t>(code).FromJust());
+        }
+    }
+}
+

src/backup.h

+#ifndef NODE_SQLITE3_SRC_BACKUP_H
+#define NODE_SQLITE3_SRC_BACKUP_H
+
+#include "database.h"
+
+#include <string>
+#include <queue>
+#include <set>
+
+#include <sqlite3.h>
+#include <nan.h>
+
+using namespace v8;
+using namespace node;
+
+namespace node_sqlite3 {
+
+/**
+ *
+ * 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.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();
+ *
+ */
+class Backup : public Nan::ObjectWrap {
+public:
+    static Nan::Persistent<FunctionTemplate> constructor_template;
+
+    static NAN_MODULE_INIT(Init);
+    static NAN_METHOD(New);
+
+    struct Baton {
+        uv_work_t request;
+        Backup* backup;
+        Nan::Persistent<Function> callback;
+
+        Baton(Backup* backup_, Local<Function> cb_) : backup(backup_) {
+            backup->Ref();
+            request.data = this;
+            callback.Reset(cb_);
+        }
+        virtual ~Baton() {
+            backup->Unref();
+            callback.Reset();
+        }
+    };
+
+    struct InitializeBaton : Database::Baton {
+        Backup* backup;
+        std::string filename;
+        std::string sourceName;
+        std::string destName;
+        bool filenameIsDest;
+        InitializeBaton(Database* db_, Local<Function> cb_, Backup* backup_) :
+            Baton(db_, cb_), backup(backup_), filenameIsDest(true) {
+            backup->Ref();
+        }
+        virtual ~InitializeBaton() {
+            backup->Unref();
+            if (!db->IsOpen() && db->IsLocked()) {
+                // The database handle was closed before the backup could be opened.
+                backup->FinishAll();
+            }
+        }
+    };
+
+    struct StepBaton : Baton {
+        int pages;
+        std::set<int> retryErrorsSet;
+        StepBaton(Backup* backup_, Local<Function> cb_, int pages_) :
+            Baton(backup_, cb_), pages(pages_) {}
+    };
+
+    typedef void (*Work_Callback)(Baton* baton);
+
+    struct Call {
+        Call(Work_Callback cb_, Baton* baton_) : callback(cb_), baton(baton_) {};
+        Work_Callback callback;
+        Baton* baton;
+    };
+
+    Backup(Database* db_) : Nan::ObjectWrap(),
+           db(db_),
+           _handle(NULL),
+           _otherDb(NULL),
+           _destDb(NULL),
+           inited(false),
+           locked(true),
+           completed(false),
+           failed(false),
+           remaining(-1),
+           pageCount(-1),
+           finished(false) {
+        db->Ref();
+    }
+
+    ~Backup() {
+        if (!finished) {
+            FinishAll();
+        }
+        retryErrors.Reset();
+    }
+
+    WORK_DEFINITION(Step);
+    WORK_DEFINITION(Finish);
+    static NAN_GETTER(IdleGetter);
+    static NAN_GETTER(CompletedGetter);
+    static NAN_GETTER(FailedGetter);
+    static NAN_GETTER(PageCountGetter);
+    static NAN_GETTER(RemainingGetter);
+    static NAN_GETTER(FatalErrorGetter);
+    static NAN_GETTER(RetryErrorGetter);
+
+    static NAN_SETTER(FatalErrorSetter);
+    static NAN_SETTER(RetryErrorSetter);
+
+protected:
+    static void Work_BeginInitialize(Database::Baton* baton);
+    static void Work_Initialize(uv_work_t* req);
+    static void Work_AfterInitialize(uv_work_t* req);
+
+    void Schedule(Work_Callback callback, Baton* baton);
+    void Process();
+    void CleanQueue();
+    template <class T> static void Error(T* baton);
+
+    void FinishAll();
+    void FinishSqlite();
+    void GetRetryErrors(std::set<int>& retryErrorsSet);
+
+    Database* db;
+
+    sqlite3_backup* _handle;
+    sqlite3* _otherDb;
+    sqlite3* _destDb;
+    int status;
+    std::string message;
+
+    bool inited;
+    bool locked;
+    bool completed;
+    bool failed;
+    int remaining;
+    int pageCount;
+    bool finished;
+    std::queue<Call*> queue;
+
+    Nan::Persistent<Array> retryErrors;
+};
+
+}
+
+#endif

src/database.h

@@ -98,6 +98,7 @@ public:
     typedef Async<UpdateInfo, Database> AsyncUpdate;
 
     friend class Statement;
+    friend class Backup;
 
 protected:
     Database() : Nan::ObjectWrap(),

src/macros.h

@@ -31,6 +31,11 @@ const char* sqlite_authorizer_string(int type);
     }                                                                          \
     Nan::Utf8String var(info[i]);
 
+#define REQUIRE_ARGUMENT_INTEGER(i, var)                                        \
+    if (info.Length() <= (i) || !info[i]->IsInt32()) {                        \
+        return Nan::ThrowTypeError("Argument " #i " must be an integer");        \
+    }                                                                          \
+    int var(Nan::To<int32_t>(info[i]).FromJust());
 
 #define OPTIONAL_ARGUMENT_FUNCTION(i, var)                                     \
     Local<Function> var;                                                       \
@@ -74,6 +79,10 @@ const char* sqlite_authorizer_string(int type);
     Nan::SetAccessor((target)->InstanceTemplate(),                             \
         Nan::New(name).ToLocalChecked(), (function));
 
+#define NODE_SET_SETTER(target, name, getter, setter)                          \
+    Nan::SetAccessor((target)->InstanceTemplate(),                             \
+        Nan::New(name).ToLocalChecked(), getter, setter);
+
 #define GET_STRING(source, name, property)                                     \
     Nan::Utf8String name(Nan::Get(source,                                      \
         Nan::New(prop).ToLocalChecked()).ToLocalChecked());
@@ -134,6 +143,32 @@ const char* sqlite_authorizer_string(int type);
     stmt->db->Process();                                                       \
     delete baton;
 
+#define BACKUP_BEGIN(type)                                                     \
+    assert(baton);                                                             \
+    assert(baton->backup);                                                     \
+    assert(!baton->backup->locked);                                            \
+    assert(!baton->backup->finished);                                          \
+    assert(baton->backup->inited);                                             \
+    baton->backup->locked = true;                                              \
+    baton->backup->db->pending++;                                              \
+    int status = uv_queue_work(uv_default_loop(),                              \
+        &baton->request,                                                       \
+        Work_##type, reinterpret_cast<uv_after_work_cb>(Work_After##type));    \
+    assert(status == 0);
+
+#define BACKUP_INIT(type)                                                      \
+    type* baton = static_cast<type*>(req->data);                               \
+    Backup* backup = baton->backup;
+
+#define BACKUP_END()                                                           \
+    assert(backup->locked);                                                    \
+    assert(backup->db->pending);                                               \
+    backup->locked = false;                                                    \
+    backup->db->pending--;                                                     \
+    backup->Process();                                                         \
+    backup->db->Process();                                                     \
+    delete baton;
+
 #define DELETE_FIELD(field)                                                    \
     if (field != NULL) {                                                       \
         switch ((field)->type) {                                               \

src/node_sqlite3.cc

@@ -7,6 +7,7 @@
 #include "macros.h"
 #include "database.h"
 #include "statement.h"
+#include "backup.h"
 
 using namespace node_sqlite3;
 
@@ -17,6 +18,7 @@ NAN_MODULE_INIT(RegisterModule) {
 
     Database::Init(target);
     Statement::Init(target);
+    Backup::Init(target);
 
     DEFINE_CONSTANT_INTEGER(target, SQLITE_OPEN_READONLY, OPEN_READONLY);
     DEFINE_CONSTANT_INTEGER(target, SQLITE_OPEN_READWRITE, OPEN_READWRITE);

test/backup.test.js

+var sqlite3 = require('..');
+var assert = require('assert');
+var fs = require('fs');
+var helper = require('./support/helper');
+
+// Check that the number of rows in two tables matches.
+function assertRowsMatchDb(db1, table1, db2, table2, done) {
+    db1.get("SELECT COUNT(*) as count FROM " + table1, function(err, row) {
+        if (err) throw err;
+        db2.get("SELECT COUNT(*) as count FROM " + table2, function(err, row2) {
+            if (err) throw err;
+            assert.equal(row.count, row2.count);
+            done();
+        });
+    });
+}
+
+// Check that the number of rows in the table "foo" is preserved in a backup.
+function assertRowsMatchFile(db, backupName, done) {
+    var db2 = new sqlite3.Database(backupName, sqlite3.OPEN_READONLY, function(err) {
+        if (err) throw err;
+        assertRowsMatchDb(db, 'foo', db2, 'foo', function() {
+            db2.close(done);
+        });
+    });
+}
+
+describe('backup', function() {
+    before(function() {
+        helper.ensureExists('test/tmp');
+    });
+
+    var db;
+    beforeEach(function(done) {
+        helper.deleteFile('test/tmp/backup.db');
+        helper.deleteFile('test/tmp/backup2.db');
+        db = new sqlite3.Database('test/support/prepare.db', sqlite3.OPEN_READONLY, done);
+    });
+
+    afterEach(function(done) {
+        if (!db) { done(); }
+        db.close(done);
+    });
+
+    it ('output db created once step is called', function(done) {
+        var backup = db.backup('test/tmp/backup.db', function(err) {
+            if (err) throw err;
+            backup.step(1, function(err) {
+                if (err) throw err;
+                assert.fileExists('test/tmp/backup.db');
+                backup.finish(done);
+            });
+        });
+    });
+
+    it ('copies source fully with step(-1)', function(done) {
+        var backup = db.backup('test/tmp/backup.db');
+        backup.step(-1, function(err) {
+            if (err) throw err;
+            assert.fileExists('test/tmp/backup.db');
+            backup.finish(function(err) {
+                if (err) throw err;
+                assertRowsMatchFile(db, 'test/tmp/backup.db', done);
+            });
+        });
+    });
+
+    it ('backup db not created if finished immediately', function(done) {
+        var backup = db.backup('test/tmp/backup.db');
+        backup.finish(function(err) {
+            if (err) throw err;
+            assert.fileDoesNotExist('test/tmp/backup.db');
+            done();
+        });
+    });
+
+    it ('error closing db if backup not finished', function(done) {
+        var backup = db.backup('test/tmp/backup.db');
+        db.close(function(err) {
+            db = null;
+            if (!err) throw new Error('should have an error');
+            if (err.errno == sqlite3.BUSY) {
+                done();
+            }
+            else throw err;
+        });
+    });
+
+    it ('using the backup after finished is an error', function(done) {
+        var backup = db.backup('test/tmp/backup.db');
+        backup.finish(function(err) {
+            if (err) throw err;
+            backup.step(1, function(err) {
+                if (!err) throw new Error('should have an error');
+                if (err.errno == sqlite3.MISUSE &&
+                    err.message === 'SQLITE_MISUSE: Backup is already finished') {
+                    done();
+                }
+                else throw err;
+            });
+        });
+    });
+
+    it ('remaining/pageCount are available after call to step', function(done) {
+        var backup = db.backup('test/tmp/backup.db');
+        backup.step(0, function(err) {
+            if (err) throw err;
+            assert.equal(typeof this.pageCount, 'number');
+            assert.equal(typeof this.remaining, 'number');
+            assert.equal(this.remaining, this.pageCount);
+            var prevRemaining = this.remaining;
+            var prevPageCount = this.pageCount;
+            backup.step(1, function(err) {
+                if (err) throw err;
+                assert.notEqual(this.remaining, prevRemaining);
+                assert.equal(this.pageCount, prevPageCount);
+                backup.finish(done);
+            });
+        });
+    });
+
+    it ('backup works if database is modified half-way through', function(done) {
+        var backup = db.backup('test/tmp/backup.db');
+        backup.step(-1, function(err) {
+            if (err) throw err;
+            backup.finish(function(err) {
+                if (err) throw err;
+                var db2 = new sqlite3.Database('test/tmp/backup.db', function(err) {
+                    if (err) throw err;
+                    var backup2 = db2.backup('test/tmp/backup2.db');
+                    backup2.step(1, function(err, completed) {
+                        if (err) throw err;
+                        assert.equal(completed, false);  // Page size for the test db
+                        // should not be raised to high.
+                        db2.exec("insert into foo(txt) values('hello')", function(err) {
+                            if (err) throw err;
+                            backup2.step(-1, function(err, completed) {
+                                if (err) throw err;
+                                assert.equal(completed, true);
+                                assertRowsMatchFile(db2, 'test/tmp/backup2.db', function() {
+                                    backup2.finish(function(err) {
+                                        if (err) throw err;
+                                        db2.close(done);
+                                    });
+                                });
+                            });
+                        });
+                    });
+                });
+            });
+        });
+    });
+
+    (sqlite3.VERSION_NUMBER < 3007011 ? it.skip : it) ('can backup from temp to main', function(done) {
+        db.exec("CREATE TEMP TABLE space (txt TEXT)", function(err) {
+            if (err) throw err;
+            db.exec("INSERT INTO space(txt) VALUES('monkey')", function(err) {
+                if (err) throw err;
+                var backup = db.backup('test/tmp/backup.db', 'temp', 'main', true, function(err) {
+                    if (err) throw err;
+                    backup.step(-1);
+                    backup.finish(function(err) {
+                        if (err) throw err;
+                        var db2 = new sqlite3.Database('test/tmp/backup.db', function(err) {
+                            if (err) throw err;
+                            db2.get("SELECT * FROM space", function(err, row) {
+                                if (err) throw err;
+                                assert.equal(row.txt, 'monkey');
+                                db2.close(done);
+                            });
+                        });
+                    });
+                });
+            });
+        });
+    });
+
+    (sqlite3.VERSION_NUMBER < 3007011 ? it.skip : it) ('can backup from main to temp', function(done) {
+        var backup = db.backup('test/support/prepare.db', 'main', 'temp', false, function(err) {
+            if (err) throw err;
+            backup.step(-1);
+            backup.finish(function(err) {
+                if (err) throw err;
+                assertRowsMatchDb(db, 'temp.foo', db, 'main.foo', done);
+            });
+        });
+    });
+
+    it ('cannot backup to a locked db', function(done) {
+        var db2 = new sqlite3.Database('test/tmp/backup.db', function(err) {
+            db2.exec("PRAGMA locking_mode = EXCLUSIVE");
+            db2.exec("BEGIN EXCLUSIVE", function(err) {
+                if (err) throw err;
+                var backup = db.backup('test/tmp/backup.db');
+                backup.step(-1, function(stepErr) {
+                    db2.close(function(err) {
+                        if (err) throw err;
+                        if (stepErr.errno == sqlite3.BUSY) {
+                            backup.finish(done);
+                        }
+                        else throw stepErr;
+                    });
+                });
+            });
+        });
+    });
+
+    it ('fuss-free incremental backups work', function(done) {
+        var backup = db.backup('test/tmp/backup.db');
+        var timer;
+        function makeProgress() {
+            if (backup.idle) {
+                backup.step(1);
+            }
+            if (backup.completed || backup.failed) {
+                clearInterval(timer);
+                assert.equal(backup.completed, true);
+                assert.equal(backup.failed, false);
+                done();
+            }
+        }
+        timer = setInterval(makeProgress, 2);
+    });
+
+    it ('setting retryErrors to empty disables automatic finishing', function(done) {
+        var backup = db.backup('test/tmp/backup.db');
+        backup.retryErrors = [];
+        backup.step(-1, function(err) {
+            if (err) throw err;
+            db.close(function(err) {
+                db = null;
+                if (!err) throw new Error('should have an error');
+                assert.equal(err.errno, sqlite3.BUSY);
+                done();
+            });
+        });
+    });
+
+    it ('setting retryErrors enables automatic finishing', function(done) {
+        var backup = db.backup('test/tmp/backup.db');
+        backup.retryErrors = [sqlite3.OK];
+        backup.step(-1, function(err) {
+            if (err) throw err;
+            db.close(function(err) {
+                if (err) throw err;
+                db = null;
+                done();
+            });
+        });
+    });
+
+    it ('default retryErrors will retry on a locked/busy db', function(done) {
+        var db2 = new sqlite3.Database('test/tmp/backup.db', function(err) {
+            db2.exec("PRAGMA locking_mode = EXCLUSIVE");
+            db2.exec("BEGIN EXCLUSIVE", function(err) {
+                if (err) throw err;
+                var backup = db.backup('test/tmp/backup.db');
+                backup.step(-1, function(stepErr) {
+                    db2.close(function(err) {
+                        if (err) throw err;
+                        assert.equal(stepErr.errno, sqlite3.BUSY);
+                        assert.equal(backup.completed, false);
+                        assert.equal(backup.failed, false);
+                        backup.step(-1, function(err) {
+                            if (err) throw err;
+                            assert.equal(backup.completed, true);
+                            assert.equal(backup.failed, false);
+                            done();
+                        });
+                    });
+                });
+            });
+        });
+    });
+});