src: add support for AbortSignal in backup method

This adds support for passing an AbortSignal to the database backup
function. If the signal is aborted during the backup process, the
operation is interrupted and a rejection is returned with an
AbortError.

The signal is optionally passed through the options object. Internally,
the signal is stored and periodically checked between backup steps to
respond quickly to abort requests.

This improves integration with modern web APIs and aligns with how
abortable operations are handled elsewhere in the Node.js ecosystem.

Fixes: #58888

Author: lluisemper

doc/api/sqlite.md

@@ -774,6 +774,8 @@ changes:
   * `rate` {number} Number of pages to be transmitted in each batch of the backup. **Default:** `100`.
   * `progress` {Function} Callback function that will be called with the number of pages copied and the total number of
     pages.
+  * `signal` {AbortSignal} An optional AbortSignal that can be used to abort the backup operation. If the signal is
+    aborted, the backup operation will be cancelled and the Promise will reject with an `AbortError`.
 * Returns: {Promise} A promise that resolves when the backup is completed and rejects if an error occurs.
 
 This method makes a database backup. This method abstracts the [`sqlite3_backup_init()`][], [`sqlite3_backup_step()`][]
@@ -813,6 +815,40 @@ const totalPagesTransferred = await backup(sourceDb, 'backup.db', {
 console.log('Backup completed', totalPagesTransferred);
 ```
 
+### Aborting a backup
+
+The backup operation can be cancelled using an `AbortSignal`:
+
+```cjs
+const { backup, DatabaseSync } = require('node:sqlite');
+
+(async () => {
+  const sourceDb = new DatabaseSync('source.db');
+  const controller = new AbortController();
+
+  // Cancel the backup after 5 seconds
+  setTimeout(() => {
+    controller.abort('Backup cancelled by user');
+  }, 5000);
+
+  try {
+    await backup(sourceDb, 'backup.db', {
+      signal: controller.signal,
+      progress: ({ totalPages, remainingPages }) => {
+        console.log('Backup in progress', { totalPages, remainingPages });
+      },
+    });
+    console.log('Backup completed successfully');
+  } catch (error) {
+    if (error.name === 'AbortError') {
+      console.log('Backup was cancelled:', error.message);
+    } else {
+      console.error('Backup failed:', error.message);
+    }
+  }
+})();
+```
+
 ## `sqlite.constants`
 
 <!-- YAML

lib/sqlite.js

@@ -1,6 +1,40 @@
 'use strict';
+const {
+  PromiseReject,
+} = primordials;
+const {
+  AbortError,
+  codes: {
+    ERR_INVALID_STATE,
+  },
+} = require('internal/errors');
 const { emitExperimentalWarning } = require('internal/util');
 
 emitExperimentalWarning('SQLite');
 
-module.exports = internalBinding('sqlite');
+const binding = internalBinding('sqlite');
+
+function backup(sourceDb, path, options = {}) {
+  if (typeof sourceDb !== 'object' || sourceDb === null) {
+    throw new ERR_INVALID_STATE.TypeError('The "sourceDb" argument must be an object.');
+  }
+
+  if (typeof path !== 'string') {
+    throw new ERR_INVALID_STATE.TypeError('The "path" argument must be a string.');
+  }
+
+  if (options.signal !== undefined) {
+    if (typeof options.signal !== 'object' || options.signal === null) {
+      throw new ERR_INVALID_STATE.TypeError('The "options.signal" argument must be an AbortSignal.');
+    }
+    if (options.signal.aborted) {
+      return PromiseReject(new AbortError(undefined, { cause: options.signal.reason }));
+    }
+  }
+  return binding.backup(sourceDb, path, options);
+}
+
+module.exports = {
+  ...binding,
+  backup,
+};

src/node_sqlite.cc

@@ -12,6 +12,7 @@
 #include "threadpoolwork-inl.h"
 #include "util-inl.h"
 
+#include <atomic>
 #include <cinttypes>
 
 namespace node {
@@ -433,16 +434,21 @@ class BackupJob : public ThreadPoolWork {
                      std::string destination_name,
                      std::string dest_db,
                      int pages,
-                     Local<Function> progressFunc)
+                     Local<Function> progressFunc,
+                     Local<Object> abort_signal = Local<Object>())
       : ThreadPoolWork(env, "node_sqlite3.BackupJob"),
         env_(env),
         source_(source),
         pages_(pages),
         source_db_(std::move(source_db)),
         destination_name_(std::move(destination_name)),
-        dest_db_(std::move(dest_db)) {
+        dest_db_(std::move(dest_db)),
+        is_aborted_(false) {
     resolver_.Reset(env->isolate(), resolver);
     progressFunc_.Reset(env->isolate(), progressFunc);
+    if (!abort_signal.IsEmpty()) {
+      abort_signal_.Reset(env->isolate(), abort_signal);
+    }
   }
 
   void ScheduleBackup() {
@@ -471,6 +477,10 @@ class BackupJob : public ThreadPoolWork {
   }
 
   void DoThreadPoolWork() override {
+    if (is_aborted_.load()) {
+      backup_status_ = SQLITE_INTERRUPT;
+      return;
+    }
     backup_status_ = sqlite3_backup_step(backup_, pages_);
   }
 
@@ -479,6 +489,11 @@ class BackupJob : public ThreadPoolWork {
     Local<Promise::Resolver> resolver =
         Local<Promise::Resolver>::New(env()->isolate(), resolver_);
 
+    if (is_aborted_.load() || backup_status_ == SQLITE_INTERRUPT) {
+      HandleAbortError(resolver);
+      return;
+    }
+
     if (!(backup_status_ == SQLITE_OK || backup_status_ == SQLITE_DONE ||
           backup_status_ == SQLITE_BUSY || backup_status_ == SQLITE_LOCKED)) {
       HandleBackupError(resolver, backup_status_);
@@ -515,6 +530,10 @@ class BackupJob : public ThreadPoolWork {
           return;
         }
       }
+      if (CheckAbortSignal()) {
+        HandleAbortError(resolver);
+        return;
+      }
 
       // There's still work to do
       this->ScheduleWork();
@@ -548,8 +567,14 @@ class BackupJob : public ThreadPoolWork {
       sqlite3_close_v2(dest_);
       dest_ = nullptr;
     }
+
+    if (!abort_signal_.IsEmpty()) {
+      abort_signal_.Reset();
+    }
   }
 
+  void AbortBackup() { is_aborted_.store(true); }
+
  private:
   void HandleBackupError(Local<Promise::Resolver> resolver) {
     Local<Object> e;
@@ -573,19 +598,62 @@ class BackupJob : public ThreadPoolWork {
     resolver->Reject(env()->context(), e).ToChecked();
   }
 
+  void HandleAbortError(Local<Promise::Resolver> resolver) {
+    Isolate* isolate = env()->isolate();
+    Local<String> message =
+        String::NewFromUtf8(isolate, "The operation was aborted")
+            .ToLocalChecked();
+    Local<String> name =
+        String::NewFromUtf8(isolate, "AbortError").ToLocalChecked();
+
+    Local<Object> error = Exception::Error(message).As<Object>();
+    error
+        ->Set(env()->context(),
+              String::NewFromUtf8(isolate, "name").ToLocalChecked(),
+              name)
+        .ToChecked();
+
+    Finalize();
+    resolver->Reject(env()->context(), error).ToChecked();
+  }
+
+  bool CheckAbortSignal() {
+    if (abort_signal_.IsEmpty()) {
+      return false;
+    }
+
+    Isolate* isolate = env()->isolate();
+    HandleScope scope(isolate);
+    Local<Object> signal = abort_signal_.Get(isolate);
+
+    Local<String> aborted_key =
+        String::NewFromUtf8(isolate, "aborted").ToLocalChecked();
+    Local<Value> aborted_value;
+    if (signal->Get(env()->context(), aborted_key).ToLocal(&aborted_value)) {
+      if (aborted_value->BooleanValue(isolate)) {
+        is_aborted_.store(true);
+        return true;
+      }
+    }
+
+    return false;
+  }
+
   Environment* env() const { return env_; }
 
   Environment* env_;
   DatabaseSync* source_;
   Global<Promise::Resolver> resolver_;
   Global<Function> progressFunc_;
+  Global<Object> abort_signal_;
   sqlite3* dest_ = nullptr;
   sqlite3_backup* backup_ = nullptr;
   int pages_;
   int backup_status_ = SQLITE_OK;
   std::string source_db_;
   std::string destination_name_;
   std::string dest_db_;
+  std::atomic<bool> is_aborted_;
 };
 
 UserDefinedFunction::UserDefinedFunction(Environment* env,
@@ -1539,6 +1607,7 @@ void Backup(const FunctionCallbackInfo<Value>& args) {
   std::string source_db = "main";
   std::string dest_db = "main";
   Local<Function> progressFunc = Local<Function>();
+  Local<Object> abort_signal = Local<Object>();
 
   if (args.Length() > 2) {
     if (!args[2]->IsObject()) {
@@ -1612,6 +1681,23 @@ void Backup(const FunctionCallbackInfo<Value>& args) {
       }
       progressFunc = progress_v.As<Function>();
     }
+
+    Local<Value> signal_v;
+    if (!options->Get(env->context(), env->signal_string())
+             .ToLocal(&signal_v)) {
+      THROW_ERR_INVALID_ARG_VALUE(env->isolate(), "options.signal");
+      return;
+    }
+
+    if (!signal_v->IsUndefined()) {
+      if (!signal_v->IsObject()) {
+        THROW_ERR_INVALID_ARG_TYPE(
+            env->isolate(),
+            "The \"options.signal\" argument must be an AbortSignal.");
+        return;
+      }
+      abort_signal = signal_v.As<Object>();
+    }
   }
 
   Local<Promise::Resolver> resolver;
@@ -1627,7 +1713,8 @@ void Backup(const FunctionCallbackInfo<Value>& args) {
                                  dest_path.value(),
                                  std::move(dest_db),
                                  rate,
-                                 progressFunc);
+                                 progressFunc,
+                                 abort_signal);
   db->AddBackup(job);
   job->ScheduleBackup();
 }

test/parallel/test-sqlite-backup-abort.js

@@ -0,0 +1,99 @@
+'use strict';
+const { skipIfSQLiteMissing } = require('../common');
+skipIfSQLiteMissing();
+const tmpdir = require('../common/tmpdir');
+const { join } = require('node:path');
+const { DatabaseSync, backup } = require('node:sqlite');
+const { test } = require('node:test');
+const assert = require('node:assert');
+let cnt = 0;
+
+tmpdir.refresh();
+
+function nextDb() {
+  return join(tmpdir.path, `database-${cnt++}.db`);
+}
+
+test('backup with AbortSignal - abort during operation', async (t) => {
+  const sourceDbPath = nextDb();
+  const destDbPath = nextDb();
+
+  const sourceDb = new DatabaseSync(sourceDbPath);
+  t.after(() => { sourceDb.close(); });
+
+  // Create a larger table to make backup take longer
+  sourceDb.exec(`
+    CREATE TABLE test_table (id INTEGER PRIMARY KEY, data TEXT);
+  `);
+
+  const stmt = sourceDb.prepare('INSERT INTO test_table (data) VALUES (?)');
+  for (let i = 0; i < 10000; i++) {
+    stmt.run(`Test data ${i}`);
+  }
+
+  const controller = new AbortController();
+
+  // Abort after a short delay
+  const abortTimer = setTimeout(() => {
+    controller.abort('Test cancellation');
+  }, 10);
+
+  try {
+    await backup(sourceDb, destDbPath, {
+      signal: controller.signal,
+      rate: 1 // Very slow to increase chance of abort
+    });
+
+    // If we get here, the backup completed before abort
+    clearTimeout(abortTimer);
+    // This is acceptable - the backup might finish before abort triggers
+  } catch (error) {
+    clearTimeout(abortTimer);
+    assert.strictEqual(error.name, 'AbortError');
+    assert.strictEqual(error.cause, 'Test cancellation');
+  }
+});
+
+test('backup with AbortSignal - pre-aborted signal', async (t) => {
+  const sourceDbPath = nextDb();
+  const destDbPath = nextDb();
+
+  const sourceDb = new DatabaseSync(sourceDbPath);
+  t.after(() => { sourceDb.close(); });
+
+  sourceDb.exec(`
+    CREATE TABLE test_table (id INTEGER PRIMARY KEY, data TEXT);
+    INSERT INTO test_table (data) VALUES ('test');
+  `);
+
+  const controller = new AbortController();
+  controller.abort('Already aborted');
+
+  await assert.rejects(
+    backup(sourceDb, destDbPath, { signal: controller.signal }),
+    {
+      name: 'AbortError',
+      cause: 'Already aborted'
+    }
+  );
+});
+
+test('backup with AbortSignal - invalid signal type', (t) => {
+  const sourceDbPath = nextDb();
+  const destDbPath = nextDb();
+
+  const sourceDb = new DatabaseSync(sourceDbPath);
+  t.after(() => { sourceDb.close(); });
+
+  sourceDb.exec(`
+    CREATE TABLE test_table (id INTEGER PRIMARY KEY, data TEXT);
+  `);
+
+  assert.throws(
+    () => backup(sourceDb, destDbPath, { signal: 'not-a-signal' }),
+    {
+      name: 'TypeError',
+      message: /The "options\.signal" argument must be an AbortSignal/
+    }
+  );
+});