Node.js Reference ยท node:sqlite and Runtime Services
Node.js sqlite.backup() function
Reference for sqlite.backup() in node:sqlite: copy a live database to a file with a promise, track progress, choose attached databases and tune the page rate.
backup() copies the contents of an open DatabaseSync into a file on disk. It is exported by the node:sqlite module (not a method of the database object) and returns a promise. The copy runs in steps, so the source database stays usable while it is being backed up, and the backup file is a complete, consistent SQLite database when the promise resolves.
Use it for snapshots, for saving an in-memory database to disk, or for taking a safe copy of a database that your program is still writing to. Copying the file with fs.copyFile() while writers are active can produce a broken copy; backup() cannot.
import { DatabaseSync, backup } from 'node:sqlite'; const db = new DatabaseSync(':memory:'); const pages = await backup(db, '/tmp/copy.db');
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
backup(sourceDb: DatabaseSync, path: string | Buffer | URL, options?: { source?: string, target?: string, rate?: number, progress?: (info: { totalPages: number, remainingPages: number }) => void, }): Promise<number>
| Name | Description |
|---|---|
sourceDb |
The open DatabaseSync to copy from. |
path |
Destination file. It is created if it does not exist; an existing database is overwritten. |
options.source |
Name of the database to copy from, such as an attached one. Default 'main'. |
options.target |
Name of the database in the destination file to write to. Default 'main'. |
options.rate |
Number of pages copied per step. Default 100. |
options.progress |
Called after each step with the total number of pages and how many remain. |
Returns: a promise for the total number of pages in the source database at the end of the copy.
Errors: the promise rejects if the destination cannot be opened or written, or if the source database is closed. Invalid option types throw a TypeError synchronously with a code such as ERR_INVALID_ARG_TYPE.
Usage notes
- It is a function of the module, not a method:
backup(db, path), imported fromnode:sqlite. The source stays open and usable afterwards. - Steps let the event loop breathe. Between steps the copy yields, so other promise work and timers keep running. A smaller
ratemeans more steps and more responsiveness, a larger one finishes sooner. - Writes during a backup are safe. If the source is changed by the same connection while the copy is running, the copy is kept consistent. Changes made by other connections can make SQLite restart the copy, so progress may go backwards.
- Backing up an in-memory database is the standard way to persist it: open
:memory:, work, thenbackup()to a file. - Restoring is just opening the file. Create a new
DatabaseSync(path), or copy it back into memory by opening:memory:, attaching the file and using SQL. - Close the destination before copying it elsewhere. The promise resolving means the file is complete; do not open it for writing while the backup runs.
- Added in Node.js 23.8.0 as part of
node:sqlite, which is a built-in module that needs no flag in Node 24.