@@ -508,6 +508,63 @@ exception.
508508| ` TEXT ` | {string} |
509509| ` BLOB ` | {TypedArray} or {DataView} |
510510
511+ ## ` sqlite.backup(sourceDb, destination[, options]) `
512+
513+ <!-- YAML
514+ added: REPLACEME
515+ -->
516+
517+ * ` sourceDb ` {DatabaseSync} The database to backup. The source database must be open.
518+ * ` destination ` {string} The path where the backup will be created. If the file already exists, the contents will be
519+ overwritten.
520+ * ` options ` {Object} Optional configuration for the backup. The
521+ following properties are supported:
522+ * ` source ` {string} Name of the source database. This can be ` 'main' ` (the default primary database) or any other
523+ database that have been added with [ ` ATTACH DATABASE ` ] [ ] ** Default:** ` 'main' ` .
524+ * ` target ` {string} Name of the target database. This can be ` 'main' ` (the default primary database) or any other
525+ database that have been added with [ ` ATTACH DATABASE ` ] [ ] ** Default:** ` 'main' ` .
526+ * ` rate ` {number} Number of pages to be transmitted in each batch of the backup. ** Default:** ` 100 ` .
527+ * ` progress ` {Function} Callback function that will be called with the number of pages copied and the total number of
528+ pages.
529+ * Returns: {Promise} A promise that resolves when the backup is completed and rejects if an error occurs.
530+
531+ This method makes a database backup. This method abstracts the [ ` sqlite3_backup_init() ` ] [ ] , [ ` sqlite3_backup_step() ` ] [ ]
532+ and [ ` sqlite3_backup_finish() ` ] [ ] functions.
533+
534+ The backed-up database can be used normally during the backup process. Mutations coming from the same connection - same
535+ {DatabaseSync} - object will be reflected in the backup right away. However, mutations from other connections will cause
536+ the backup process to restart.
537+
538+ ``` cjs
539+ const { backup , DatabaseSync } = require (' node:sqlite'
540+
541+ (async () => {
542+ const sourceDb = new DatabaseSync (' source.db'
543+ const totalPagesTransferred = await backup (sourceDb, ' backup.db'
544+ rate: 1 , // Copy one page at a time.
545+ progress : ({ totalPages, remainingPages }) => {
546+ console .log (' Backup in progress'
547+ },
548+ });
549+
550+ console .log (' Backup completed'
551+ })();
552+ ```
553+
554+ ``` mjs
555+ import { backup , DatabaseSync } from ' node:sqlite'
556+
557+ const sourceDb = new DatabaseSync (' source.db'
558+ const totalPagesTransferred = await backup (sourceDb, ' backup.db'
559+ rate: 1 , // Copy one page at a time.
560+ progress : ({ totalPages, remainingPages }) => {
561+ console .log (' Backup in progress'
562+ },
563+ });
564+
565+ console .log (' Backup completed'
566+ ```
567+
511568## ` sqlite.constants `
512569
513570<!-- YAML
@@ -589,6 +646,9 @@ resolution handler passed to [`database.applyChangeset()`][]. See also
589646[ `SQLITE_DIRECTONLY` ] : https://www.sqlite.org/c3ref/c_deterministic.html
590647[ `SQLITE_MAX_FUNCTION_ARG` ] : https://www.sqlite.org/limits.html#max_function_arg
591648[ `database.applyChangeset()` ] : #databaseapplychangesetchangeset-options
649+ [ `sqlite3_backup_finish()` ] : https://www.sqlite.org/c3ref/backup_finish.html#sqlite3backupfinish
650+ [ `sqlite3_backup_init()` ] : https://www.sqlite.org/c3ref/backup_finish.html#sqlite3backupinit
651+ [ `sqlite3_backup_step()` ] : https://www.sqlite.org/c3ref/backup_finish.html#sqlite3backupstep
592652[ `sqlite3_changes64()` ] : https://www.sqlite.org/c3ref/changes.html
593653[ `sqlite3_close_v2()` ] : https://www.sqlite.org/c3ref/close.html
594654[ `sqlite3_create_function_v2()` ] : https://www.sqlite.org/c3ref/create_function.html
0 commit comments