Skip to content

Commit 16dc29d

Browse files
geeksilva97geeksilva97
authored
sqlite, test: expose sqlite online backup api
PR-URL: #56253 Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Vinícius Lourenço Claro Cardoso <[email protected]>
1 parent 4367232 commit 16dc29d

File tree

6 files changed

+626
-0
lines changed

6 files changed

+626
-0
lines changed

‎doc/api/sqlite.md

+60
Original file line numberDiff line numberDiff line change
@@ -526,6 +526,63 @@ exception.
526526
| `TEXT` | {string} |
527527
| `BLOB` | {TypedArray} or {DataView} |
528528

529+
## `sqlite.backup(sourceDb, destination[, options])`
530+
531+
<!-- YAML
532+
added: REPLACEME
533+
-->
534+
535+
* `sourceDb` {DatabaseSync} The database to backup. The source database must be open.
536+
* `destination` {string} The path where the backup will be created. If the file already exists, the contents will be
537+
overwritten.
538+
* `options` {Object} Optional configuration for the backup. The
539+
following properties are supported:
540+
* `source` {string} Name of the source database. This can be `'main'` (the default primary database) or any other
541+
database that have been added with [`ATTACH DATABASE`][] **Default:** `'main'`.
542+
* `target` {string} Name of the target database. This can be `'main'` (the default primary database) or any other
543+
database that have been added with [`ATTACH DATABASE`][] **Default:** `'main'`.
544+
* `rate` {number} Number of pages to be transmitted in each batch of the backup. **Default:** `100`.
545+
* `progress` {Function} Callback function that will be called with the number of pages copied and the total number of
546+
pages.
547+
* Returns: {Promise} A promise that resolves when the backup is completed and rejects if an error occurs.
548+
549+
This method makes a database backup. This method abstracts the [`sqlite3_backup_init()`][], [`sqlite3_backup_step()`][]
550+
and [`sqlite3_backup_finish()`][] functions.
551+
552+
The backed-up database can be used normally during the backup process. Mutations coming from the same connection - same
553+
{DatabaseSync} - object will be reflected in the backup right away. However, mutations from other connections will cause
554+
the backup process to restart.
555+
556+
```cjs
557+
const { backup, DatabaseSync } = require('node:sqlite');
558+
559+
(async () => {
560+
const sourceDb = new DatabaseSync('source.db');
561+
const totalPagesTransferred = await backup(sourceDb, 'backup.db', {
562+
rate: 1, // Copy one page at a time.
563+
progress: ({ totalPages, remainingPages }) => {
564+
console.log('Backup in progress', { totalPages, remainingPages });
565+
},
566+
});
567+
568+
console.log('Backup completed', totalPagesTransferred);
569+
})();
570+
```
571+
572+
```mjs
573+
import { backup, DatabaseSync } from 'node:sqlite';
574+
575+
const sourceDb = new DatabaseSync('source.db');
576+
const totalPagesTransferred = await backup(sourceDb, 'backup.db', {
577+
rate: 1, // Copy one page at a time.
578+
progress: ({ totalPages, remainingPages }) => {
579+
console.log('Backup in progress', { totalPages, remainingPages });
580+
},
581+
});
582+
583+
console.log('Backup completed', totalPagesTransferred);
584+
```
585+
529586
## `sqlite.constants`
530587

531588
<!-- YAML
@@ -609,6 +666,9 @@ resolution handler passed to [`database.applyChangeset()`][]. See also
609666
[`SQLITE_DIRECTONLY`]: https://www.sqlite.org/c3ref/c_deterministic.html
610667
[`SQLITE_MAX_FUNCTION_ARG`]: https://www.sqlite.org/limits.html#max_function_arg
611668
[`database.applyChangeset()`]: #databaseapplychangesetchangeset-options
669+
[`sqlite3_backup_finish()`]: https://www.sqlite.org/c3ref/backup_finish.html#sqlite3backupfinish
670+
[`sqlite3_backup_init()`]: https://www.sqlite.org/c3ref/backup_finish.html#sqlite3backupinit
671+
[`sqlite3_backup_step()`]: https://www.sqlite.org/c3ref/backup_finish.html#sqlite3backupstep
612672
[`sqlite3_changes64()`]: https://www.sqlite.org/c3ref/changes.html
613673
[`sqlite3_close_v2()`]: https://www.sqlite.org/c3ref/close.html
614674
[`sqlite3_create_function_v2()`]: https://www.sqlite.org/c3ref/create_function.html

‎src/env_properties.h

+4
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,7 @@
7777
V(asn1curve_string, "asn1Curve") \
7878
V(async_ids_stack_string, "async_ids_stack") \
7979
V(attributes_string, "attributes") \
80+
V(backup_string, "backup") \
8081
V(base_string, "base") \
8182
V(base_url_string, "baseURL") \
8283
V(bits_string, "bits") \
@@ -302,6 +303,7 @@
302303
V(primordials_string, "primordials") \
303304
V(priority_string, "priority") \
304305
V(process_string, "process") \
306+
V(progress_string, "progress") \
305307
V(promise_string, "promise") \
306308
V(protocol_string, "protocol") \
307309
V(prototype_string, "prototype") \
@@ -316,6 +318,7 @@
316318
V(reason_string, "reason") \
317319
V(refresh_string, "refresh") \
318320
V(regexp_string, "regexp") \
321+
V(remaining_pages_string, "remainingPages") \
319322
V(rename_string, "rename") \
320323
V(replacement_string, "replacement") \
321324
V(required_module_facade_url_string, \
@@ -369,6 +372,7 @@
369372
V(time_to_first_byte_sent_string, "timeToFirstByteSent") \
370373
V(time_to_first_header_string, "timeToFirstHeader") \
371374
V(tls_ticket_string, "tlsTicket") \
375+
V(total_pages_string, "totalPages") \
372376
V(transfer_string, "transfer") \
373377
V(transfer_unsupported_type_str, \
374378
"Cannot transfer object of unsupported type.") \

0 commit comments

Comments
 (0)