`createDurableObjectSqlStoragePersister`

The createDurableObjectSqlStoragePersister function creates a DurableObjectSqlStoragePersister object that can persist the Store to and from Cloudflare Durable Object SQLite storage.

createDurableObjectSqlStoragePersister(
  store: MergeableStore,
  sqlStorage: SqlStorage,
  configOrStoreTableName?: string | DurableObjectSqlDatabasePersisterConfig,
  onSqlCommand?: (sql: string, params?: any[]) => void,
  onIgnoredError?: (error: any) => void,
): DurableObjectSqlStoragePersister

	Type	Description
`store`	`MergeableStore`	The `Store` or `MergeableStore` to persist.
`sqlStorage`	`SqlStorage`	The Durable Object SQL storage to persist the `Store` to.
`configOrStoreTableName?`	`string \| DurableObjectSqlDatabasePersisterConfig`	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	`DurableObjectSqlStoragePersister`	A reference to the new `DurableObjectSqlStoragePersister` object.

You will mostly use this within the createPersister method of a WsServerDurableObject.

This persister uses Cloudflare's SQLite storage backend, which provides better pricing and performance compared to the legacy Key-value storage backend.

Important Prerequisites: Before using this persister, you must configure your Durable Object class to use SQLite storage by adding a migration to your Wrangler configuration file. In your wrangler.toml, add the following.

[[migrations]]
tag = "v1"
new_sqlite_classes = ["YourDurableObjectClass"]

Or in your wrangler.json, add:

{
  "migrations": [
    {
      "tag": "v1",
      "new_sqlite_classes": ["YourDurableObjectClass"]
    }
  ]
}

For more details on Durable Object migrations, see the Cloudflare documentation.

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), a fragmented mode that stores each piece of data separately to avoid Cloudflare's 2MB row limit.

JSON Mode (Default): Stores the entire Store as JSON in a single database row. This is efficient for smaller stores but may hit Cloudflare's 2MB row limit for very large stores and uses fewer database writes.
Fragmented Mode: Stores each table, row, cell, and value as separate database rows. Use this mode if you're concerned about hitting Cloudflare's 2MB row limit with large stores in JSON mode. This mode creates more database writes but avoids row size limitations.

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. If it is the string 'fragmented', it enables fragmented mode.

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

As well as providing a reference to the Store or MergeableStore to persist, you must provide a sqlStorage parameter which identifies the Durable Object SQLite storage to persist it to.

Examples

This example creates a DurableObjectSqlStoragePersister object and persists the Store to Durable Object SQLite storage as a JSON serialization into the default tinybase table. It uses this within the createPersister method of a WsServerDurableObject instance.

import {createMergeableStore} from 'tinybase';
import {createDurableObjectSqlStoragePersister} from 'tinybase/persisters/persister-durable-object-sql-storage';
import {WsServerDurableObject} from 'tinybase/synchronizers/synchronizer-ws-server-durable-object';

export class MyDurableObject extends WsServerDurableObject {
  createPersister() {
    const store = createMergeableStore();
    const persister = createDurableObjectSqlStoragePersister(
      store,
      this.ctx.storage.sql,
    );
    return persister;
  }
}

This example creates a DurableObjectSqlStoragePersister object with a custom table name and SQL command logging for debugging.

import {createMergeableStore} from 'tinybase';
import {createDurableObjectSqlStoragePersister} from 'tinybase/persisters/persister-durable-object-sql-storage';
import {WsServerDurableObject} from 'tinybase/synchronizers/synchronizer-ws-server-durable-object';

export class MyDurableObject extends WsServerDurableObject {
  createPersister() {
    const store = createMergeableStore();
    const persister = createDurableObjectSqlStoragePersister(
      store,
      this.ctx.storage.sql,
      'my_app_store',
      (sql, params) => console.log('SQL:', sql, params),
      (error) => console.error('Persistence error:', error),
    );
    return persister;
  }
}

This example creates a DurableObjectSqlStoragePersister object using fragmented mode to avoid Cloudflare's 2MB row limit for large stores.

import {createMergeableStore} from 'tinybase';
import {createDurableObjectSqlStoragePersister} from 'tinybase/persisters/persister-durable-object-sql-storage';
import {WsServerDurableObject} from 'tinybase/synchronizers/synchronizer-ws-server-durable-object';

export class MyDurableObject extends WsServerDurableObject {
  createPersister() {
    const store = createMergeableStore();
    const persister = createDurableObjectSqlStoragePersister(
      store,
      this.ctx.storage.sql,
      {mode: 'fragmented'},
    );
    return persister;
  }
}

This example creates a DurableObjectSqlStoragePersister object using fragmented mode with a custom storage prefix.

import {createMergeableStore} from 'tinybase';
import {createDurableObjectSqlStoragePersister} from 'tinybase/persisters/persister-durable-object-sql-storage';
import {WsServerDurableObject} from 'tinybase/synchronizers/synchronizer-ws-server-durable-object';

export class MyDurableObject extends WsServerDurableObject {
  createPersister() {
    const store = createMergeableStore();
    const persister = createDurableObjectSqlStoragePersister(
      store,
      this.ctx.storage.sql,
      {mode: 'fragmented', storagePrefix: 'my_app_'},
    );
    return persister;
  }
}

Since

v6.3.0