8000 sqlite, test: expose sqlite online backup api · nodejs/node@8dc6376 · GitHub
[go: up one dir, main page]
Skip to content

Commit 8dc6376

Browse files
geeksilva97targos
geeksilva97
authored and
targos
committed
sqlite, test: expose sqlite online backup api
PR-URL: #56253 Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Vinícius Lourenço Claro Cardoso <contact@viniciusl.com.br>
1 parent 3c082d4 commit 8dc6376

File tree

6 files changed

+626
-0
lines changed

6 files changed

+626
-0
lines changed

‎doc/api/sqlite.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -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', { totalPages, remainingPages });
547+
},
548+
});
549+
550+
console.log('Backup completed', totalPagesTransferred);
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', { totalPages, remainingPages });
562+
},
563+
});
564+
565+
console.log('Backup completed', totalPagesTransferred);
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

‎src/env_properties.h‎

Lines changed: 4 additions & 0 deletions
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)
0