`createSqliteNodePersister`

The createSqliteNodePersister function creates a SqliteNodePersister object that can persist a Store to a local SQLite database.

createSqliteNodePersister<StoreType>(
  store: StoreType,
  db: DatabaseSync,
  configOrStoreTableName?: string | NoInfer<StoreType> extends MergeableStore ? DpcJson : DatabasePersisterConfig,
  onSqlCommand?: (sql: string, params?: any[]) => void,
  onIgnoredError?: (error: any) => void,
): SqliteNodePersister

	Type	Description
`store`	`StoreType`	The `Store` or `MergeableStore` to persist.
`db`	`DatabaseSync`	The database that was returned from `new DatabaseSync(...)`.
`configOrStoreTableName?`	`string \| NoInfer<StoreType> extends MergeableStore ? DpcJson : DatabasePersisterConfig`	A `DatabasePersisterConfig` to configure the persistence mode (or a string to set the `storeTableName` property of the JSON serialization).
`onSqlCommand?`	`(sql: string, params?: any[]) => void`	An optional handler called every time the `Persister` executes a SQL command or query. This is suitable for logging persistence behavior in a development environment.
`onIgnoredError?`	`(error: any) => void`	An optional handler for the errors that the `Persister` would otherwise ignore when trying to save or load data. This is suitable for debugging persistence issues in a development environment.
returns	`SqliteNodePersister`	A reference to the new `SqliteNodePersister` object.

A SqliteNodePersister supports regular Store objects, and can also be used to persist the metadata of a MergeableStore when using the JSON serialization mode, as described below.

As well as providing a reference to the Store to persist, you must provide a db parameter which is the database returned from new DatabaseSync(...).

Since the node:sqlite module is built into Node.js, this is the only SQLite-based Persister that requires no additional dependency at all. Note that the module is only available in newer versions of Node.js, and that it is still marked as experimental, so its API may change.

A database Persister uses one of two modes: either a JSON serialization of the whole Store stored in a single row of a table (the default), or a tabular mapping of Table Ids to database table names and vice-versa).

The third argument is a DatabasePersisterConfig object that configures which of those modes to use, and settings for each. If the third argument is simply a string, it is used as the storeTableName property of the JSON serialization.

See the documentation for the DpcJson and DpcTabular types for more information on how both of those modes can be configured.

Note that node:sqlite does not signal when the database changes, so if you enable automatic loading with the startAutoLoad method, it polls the database for changes. The Sqlite3Persister, which uses the asynchronous sqlite3 module, is notified of changes as they happen, and may suit you better if that matters.

Examples

This example creates a SqliteNodePersister object and persists the Store to a local SQLite database as a JSON serialization into the my_tinybase table. It makes a change to the database directly and then reloads it back into the Store.

import {DatabaseSync} from 'node:sqlite';
import {createStore} from 'tinybase';
import {createSqliteNodePersister} from 'tinybase/persisters/persister-sqlite-node';

const db = new DatabaseSync(':memory:');
const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
const persister = createSqliteNodePersister(store, db, 'my_tinybase');

await persister.save();
// Store will be saved to the database.

console.log(db.prepare('SELECT * FROM my_tinybase;').all());
// -> [{_id: '_', store: '[{"pets":{"fido":{"species":"dog"}}},{}]'}]

db.prepare('UPDATE my_tinybase SET store = ? WHERE _id = ?;').run(
  '[{"pets":{"felix":{"species":"cat"}}},{}]',
  '_',
);
await persister.load();
console.log(store.getTables());
// -> {pets: {felix: {species: 'cat'}}}

await persister.destroy();
db.close();

This example creates a SqliteNodePersister object and persists the Store to a local SQLite database with tabular mapping.

import {DatabaseSync} from 'node:sqlite';
import {createStore} from 'tinybase';
import {createSqliteNodePersister} from 'tinybase/persisters/persister-sqlite-node';

const db = new DatabaseSync(':memory:');
const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
const persister = createSqliteNodePersister(store, db, {
  mode: 'tabular',
  tables: {load: {pets: 'pets'}, save: {pets: 'pets'}},
});

await persister.save();
console.log(db.prepare('SELECT * FROM pets;').all());
// -> [{_id: 'fido', species: 'dog'}]

db.prepare(
  `INSERT INTO pets (_id, species) VALUES ('felix', 'cat')`,
).run();
await persister.load();
console.log(store.getTables());
// -> {pets: {fido: {species: 'dog'}, felix: {species: 'cat'}}}

await persister.destroy();
db.close();

Since

9.7.0