@@ -155,6 +155,70 @@ added: v22.5.0
155
155
Compiles a SQL statement into a [ prepared statement] [ ] . This method is a wrapper
156
156
around [ ` sqlite3_prepare_v2() ` ] [ ] .
157
157
158
+ ### ` database.createSession([options]) `
159
+
160
+ * ` options ` {Object} The configuration options for the session.
161
+ * ` table ` {string} A specific table to track changes for. By default, changes to all tables are tracked.
162
+ * ` db ` {string} Name of the database to track. This is useful when multiple databases have been added using [ ` ATTACH DATABASE ` ] [ ] . ** Default** : ` 'main' ` .
163
+ * Returns: {Session} A session handle.
164
+
165
+ Creates and attaches a session to the database. This method is a wrapper around [ ` sqlite3session_create() ` ] [ ] and [ ` sqlite3session_attach() ` ] [ ] .
166
+
167
+ ### ` database.applyChangeset(changeset[, options]) `
168
+
169
+ * ` changeset ` {Uint8Array} A binary changeset or patchset.
170
+ * ` options ` {Object} The configuration options for how the changes will be applied.
171
+ * ` filter ` {Function} Skip changes that, when targeted table name is supplied to this function, return a truthy value.
172
+ By default, all changes are attempted.
173
+ * ` onConflict ` {number} Determines how conflicts are handled. ** Default** : ` SQLITE_CHANGESET_ABORT ` .
174
+ * ` SQLITE_CHANGESET_OMIT ` : conflicting changes are omitted.
175
+ * ` SQLITE_CHANGESET_REPLACE ` : conflicting changes replace existing values.
176
+ * ` SQLITE_CHANGESET_ABORT ` : abort on conflict and roll back databsase.
177
+ * Returns: {boolean} Whether the changeset was applied succesfully without being aborted.
178
+
179
+ An exception is thrown if the database is not
180
+ open. This method is a wrapper around [ ` sqlite3changeset_apply() ` ] [ ] .
181
+
182
+ ``` js
183
+ const sourceDb = new DatabaseSync (' :memory:' );
184
+ const targetDb = new DatabaseSync (' :memory:' );
185
+
186
+ sourceDb .exec (' CREATE TABLE data(key INTEGER PRIMARY KEY, value TEXT)' );
187
+ targetDb .exec (' CREATE TABLE data(key INTEGER PRIMARY KEY, value TEXT)' );
188
+
189
+ const session = sourceDb .createSession ();
190
+
191
+ const insert = sourceDb .prepare (' INSERT INTO data (key, value) VALUES (?, ?)' );
192
+ insert .run (1 , ' hello' );
193
+ insert .run (2 , ' world' );
194
+
195
+ const changeset = session .changeset ();
196
+ targetDb .applyChangeset (changeset);
197
+ // Now that the changeset has been applied, targetDb contains the same data as sourceDb.
198
+ ```
199
+
200
+ ## Class: ` Session `
201
+
202
+ ### ` session.changeset() `
203
+
204
+ * Returns: {Uint8Array} Binary changeset that can be applied to other databases.
205
+
206
+ Retrieves a changeset containing all changes since the changeset was created. Can be called multiple times.
207
+ An exception is thrown if the database or the session is not open. This method is a wrapper around [ ` sqlite3session_changeset() ` ] [ ] .
208
+
209
+ ### ` session.patchset() `
210
+
211
+ * Returns: {Uint8Array} Binary patchset that can be applied to other databases.
212
+
213
+ Similar to the method above, but generates a more compact patchset. See [ Changesets and Patchsets] [ ]
214
+ in the documentation of SQLite. An exception is thrown if the database or the session is not open. This method is a
215
+ wrapper around [ ` sqlite3session_patchset() ` ] [ ] .
216
+
217
+ ### ` session.close() ` .
218
+
219
+ Closes the session. An exception is thrown if the database or the session is not open. This method is a
220
+ wrapper around [ ` sqlite3session_delete() ` ] [ ] .
221
+
158
222
## Class: ` StatementSync `
159
223
160
224
<!-- YAML
@@ -317,8 +381,39 @@ exception.
317
381
| ` TEXT ` | {string} |
318
382
| ` BLOB ` | {Uint8Array} |
319
383
384
+ ## SQLite constants
385
+
386
+ The following constants are exported by the ` node:sqlite ` module.
387
+
388
+ ### SQLite Session constants
389
+
390
+ #### Conflict-resolution constants
391
+
392
+ The following constants are meant for use with [ ` database.applyChangeset() ` ] ( #databaseapplychangesetchangeset-options ) .
393
+
394
+ <table >
395
+ <tr >
396
+ <th>Constant</th>
397
+ <th>Description</th>
398
+ </tr >
399
+ <tr >
400
+ <td><code>SQLITE_CHANGESET_OMIT</code></td>
401
+ <td>Conflicting changes are omitted.</td>
402
+ </tr >
403
+ <tr >
404
+ <td><code>SQLITE_CHANGESET_REPLACE</code></td>
405
+ <td>Conflicting changes replace existing values.</td>
406
+ </tr >
407
+ <tr >
408
+ <td><code>SQLITE_CHANGESET_ABORT</code></td>
409
+ <td>Abort when a change encounters a conflict and roll back databsase.</td>
410
+ </tr >
411
+ </table >
412
+
413
+ [ Changesets and Patchsets ] : https://www.sqlite.org/sessionintro.html#changesets_and_patchsets
320
414
[ SQL injection ] : https://en.wikipedia.org/wiki/SQL_injection
321
415
[ `--experimental-sqlite` ] : cli.md#--experimental-sqlite
416
+ [ `ATTACH DATABASE` ] : https://www.sqlite.org/lang_attach.html
322
417
[ `PRAGMA foreign_keys` ] : https://www.sqlite.org/pragma.html#pragma_foreign_keys
323
418
[ `sqlite3_changes64()` ] : https://www.sqlite.org/c3ref/changes.html
324
419
[ `sqlite3_close_v2()` ] : https://www.sqlite.org/c3ref/close.html
@@ -327,6 +422,12 @@ exception.
327
422
[ `sqlite3_last_insert_rowid()` ] : https://www.sqlite.org/c3ref/last_insert_rowid.html
328
423
[ `sqlite3_prepare_v2()` ] : https://www.sqlite.org/c3ref/prepare.html
329
424
[ `sqlite3_sql()` ] : https://www.sqlite.org/c3ref/expanded_sql.html
425
+ [ `sqlite3changeset_apply()` ] : https://www.sqlite.org/session/sqlite3changeset_apply.html
426
+ [ `sqlite3session_attach()` ] : https://www.sqlite.org/session/sqlite3session_attach.html
427
+ [ `sqlite3session_changeset()` ] : https://www.sqlite.org/session/sqlite3session_changeset.html
428
+ [ `sqlite3session_create()` ] : https://www.sqlite.org/session/sqlite3session_create.html
429
+ [ `sqlite3session_delete()` ] : https://www.sqlite.org/session/sqlite3session_delete.html
430
+ [ `sqlite3session_patchset()` ] : https://www.sqlite.org/session/sqlite3session_patchset.html
330
431
[ connection ] : https://www.sqlite.org/c3ref/sqlite3.html
331
432
[ data types ] : https://www.sqlite.org/datatype3.html
332
433
[ double-quoted string literals ] : https://www.sqlite.org/quirks.html#dblquote
0 commit comments