FAQ
Frequently asked questions about Evolu.
Questions
- What is the SQLite database size limit?
- Will my data stay on the device?
- How can I check the current database filesize?
- How to delete OPFS Sqlite in browser?
- How do I create ORM-like relations (nest related rows in queries)?
- How do I store device-specific data that shouldn't sync?
- How do I store owner-specific data that shouldn't sync?
- How do I integrate with external systems that have their own IDs?
- How do I seed initial data like country lists or default categories?
What is the SQLite database size limit?
The size limit depends on the storage quotas and eviction criteria of the browser or platform in use. For detailed information, refer to the Storage quotas and eviction criteria documentation.
Will my data stay on the device?
It depends on the platform, and a browser never promises it. Each Evolu instance
tells what it knows for sure with evolu.devicePersistence:
Persisted: the database is the app's own file, as in React Native.NotPersisted: the database is kept in memory, because thememoryOnlyoption asks for it or the browser refuses storage, as private browsing does in Safari and the other WebKit browsers and in Firefox, or as a storage failure does. Each instance has its own memory database, even for the same app and owner. WithcreateEvoluApp, that includes the device database, so each tab has its own accounts. Its data lasts until the instance ends: closing, reloading, or navigating away from its tab, including entering the back-forward cache, ends it. Where storage is available, Evolu may reload the tab, for example when another tab loads a new version of the app. Data synced with a relay comes back, as on a new device, but changes that have not synced are lost when the instance ends. On the web, a memory instance exchanges changes with every other instance, stored instances of the same owner included, only through relays, so not offline. When the browser refuses storage, a database it stored earlier stays untouched and opens again when the app loads after storage works again.Unknown: the browser stores the database, but it may delete it, as Chrome's incognito does when the session ends, without telling the app.
Show the user a notice for NotPersisted, and never tell them their data is
saved on the device unless it is Persisted. The
examples show both.
Why a browser may delete stored data
- Safari deletes it after seven days without a visit. With tracking prevention on, the default, Safari deletes all data a site's scripts stored, including OPFS, after seven days of Safari use without the user interacting with the site. Web apps added to the Home Screen are exempt. See Full Third-Party Cookie Blocking and More.
- Browsers delete it when disk space runs low. Chrome, Firefox, and Safari delete the least recently used sites' data first, unless the site's storage is persistent. See Storage quotas and eviction criteria.
- Users can clear site data at any time.
Only changes that have not synced exist nowhere else, so an app that syncs with
a relay loses at most those, as long as the owners' secrets are kept elsewhere
too. createEvoluApp stores the AppOwner secrets in the app's device database,
so once a browser deletes it, the synced data can't be read again unless the
user kept the AppOwner's mnemonic.
Persistent storage
A site whose storage is persistent keeps it when disk space runs low. After the
first local change of a database the browser stores, Evolu asks the browser
once per tab with
navigator.storage.persist():
- Chrome decides silently, granting it to sites the user installed, bookmarked, uses often, or allows to send notifications.
- Firefox asks the user, so every tab asks until the user allows it.
- Safari decides silently, granting it mainly to Home Screen web apps.
Evolu asks after the first change, not on page load, because until then
there's nothing to lose, and Firefox's prompt makes sense to the user only after
they saved something. To ask at another moment, or never, pass your own
requestPersistentStorage to createEvoluDeps:
import { constVoid } from "@evolu/common";
import { createEvoluDeps } from "@evolu/web";
const deps = createEvoluDeps({ requestPersistentStorage: constVoid });
createEvoluApp keeps its databases in memory only where the browser stores
nothing, so a user who wants nothing kept on the device needs an app that
creates its instances with createEvolu and offers its memoryOnly option.
How can I check the current database filesize?
Use exportDatabase method on Evolu instance.
const database = await evolu.exportDatabase();
const sizeInBytes = database.length;
How to delete OPFS Sqlite in browser?
Call evolu.deleteDatabase(), which deletes the database's file and its OPFS directory, and disposes the database's instances in every tab; see Purge data.
To clear the OPFS (Origin Private File System) SQLite database by hand, such as when the app doesn't start:
- Install the OPFS Explorer Chrome DevTools extension
- Disable JavaScript in your browser
- Reload the page
- Open DevTools and navigate to the OPFS Explorer tab
- Remove the SQLite database file
- Re-enable JavaScript
- Reload the page
How do I create ORM-like relations (nest related rows in queries)?
Evolu uses Kysely, a query builder, not an ORM, so it has no relations. Join related rows with SQL, or nest them in a subquery with evoluJsonArrayFrom or evoluJsonObjectFrom, as Relations shows.
How do I store device-specific settings that shouldn't sync?
With createEvoluApp, put settings such as UI preferences or onboarding state in the app's device database, which keeps the AppOwners on the device. Pass its tables as device.schema, and use them through app.device, or in React and Vue through useDeviceEvolu and useDeviceQuery, in Vue typed with createEvoluBinding. They stay the same when the user opens another AppOwner. Prefix the tables with _, which keeps them local-only:
import { AppName, createEvoluApp, id } from "@evolu/common";
const PreferencesId = id("Preferences");
type PreferencesId = typeof PreferencesId.Output;
const DeviceSchema = {
_preferences: {
id: PreferencesId,
// whatever
},
};
const app = await run.orThrow(
createEvoluApp(Schema, {
appName: AppName.orThrow("MyApp"),
auth: { type: "InstantStart" },
createFirstAppOwner: true,
device: { schema: DeviceSchema },
}),
);
const { id: preferencesId } = app.device.insert("_preferences", {});
This approach gives us:
- Type safety with the same Evolu APIs
- Schema evolution for local settings
- Reactive queries for local state
- Complete separation from synced user data
An app that brings its own AppOwners to createEvolu can keep such settings in a separate instance with transports: [] and _-prefixed tables.
How do I store owner-specific data that shouldn't sync?
Tables prefixed with underscores (_) are local-only within an existing Evolu instance—they're never synced.
Imagine editing a JSON-rich text document. Syncing the entire document on every keystroke would be inefficient. Instead, create an Evolu instance with the following schema and save drafts to its local table first. The documentId, title, and content below are values already validated with the corresponding schema types.
import {
id,
NonEmptyTrimmedString,
NonEmptyTrimmedString1000,
sqliteTrue,
} from "@evolu/common";
const DocumentId = id("Document");
const Schema = {
// Regular synced table
document: {
id: DocumentId,
title: NonEmptyTrimmedString1000,
content: NonEmptyTrimmedString,
},
// Local-only table (underscore prefix)
_documentDraft: {
id: DocumentId,
title: NonEmptyTrimmedString1000,
content: NonEmptyTrimmedString,
},
};
// Save draft locally on every keystroke (no sync)
evolu.upsert("_documentDraft", {
id: documentId,
title,
content,
});
// When ready to sync (e.g., on blur, route change)
evolu.update("_documentDraft", { id: documentId, isDeleted: sqliteTrue });
evolu.upsert("document", { id: documentId, title, content });
Evolu batches mutations queued in the same microtask and applies them in a SQLite transaction. The draft deletion and document upsert above are therefore applied together. Local tables use the same mutation and reactive query APIs as synced tables.
Drafts in local tables also survive reloads and accidentally closed tabs when their database is stored, so keep anything a user would be sad to lose there. For example, when a tab loads a new version of your app whose Evolu workers changed, such as after an Evolu update, Evolu reloads tabs still running the previous version, which ends their memory instances too; see Will my data stay on the device?.
How do I integrate with external systems that have their own IDs?
Use createIdFromString to convert external IDs into valid Evolu IDs. Using the schema and Evolu instance from Get started:
import { createIdFromString, NonEmptyTrimmedString100 } from "@evolu/common";
// Use the table's ID brand, matching TodoId from the getting-started schema.
const todoId = createIdFromString<"Todo">("external-todo-456");
evolu.upsert("todo", {
id: todoId,
title: NonEmptyTrimmedString100.orThrow("Task from external system"),
});
This ensures that multiple clients creating records with the same external identifier will generate the same Evolu ID.
Important: This transformation uses the first 16 bytes of SHA-256 hash of the string bytes, therefore it's not possible to recover the original external string. If you need to preserve the original external ID, store it in a separate column.
When the external IDs are UUIDs, use uuidToId instead. A UUID and an Evolu ID are both 16 bytes, so the conversion is reversible with idToUuid, and the original ID doesn't need its own column:
import { assertEqual, idToUuid, Uuid, uuidToId } from "@evolu/common";
const externalId = Uuid.orThrow("0190a6f4-8c3e-7b2a-9d41-5e6f7a8b9c0d");
const todoId = uuidToId<"Todo">(externalId);
// Later, when talking to the external system:
const uuid = idToUuid(todoId);
assertEqual(uuid, externalId);
Uuid accepts only the canonical lowercase form, so lowercase UUIDs from other sources before validating them. A time-based UUID, such as version 7, keeps its creation time in the Evolu ID.
For ULIDs, use ulidToId and idToUlid the same way. Ulid accepts only the canonical uppercase form, so uppercase ULIDs from other sources before validating them.
How do I seed initial data like country lists or default categories?
Evolu previously had an automatic seeding feature that ran when an AppOwner was created, but it was removed because Evolu syncs all changes immediately. Every page visit would generate and sync data to the relay, creating unnecessary traffic. Automatic seeding opens a DoS vulnerability where bots or users could repeatedly trigger data creation by simply visiting the page.
Simple approach: Create initial data on explicit user action. For example:
import {
createIdFromString,
id,
NonEmptyTrimmedString100,
type AppOwnerEvolu,
} from "@evolu/common";
const CategorySchema = {
category: { id: id("Category"), name: NonEmptyTrimmedString100 },
};
const seedDefaultData = (evolu: AppOwnerEvolu<typeof CategorySchema>) => {
for (const [externalId, name] of [
["groceries", "Groceries"],
["utilities", "Utilities"],
["entertainment", "Entertainment"],
] as const) {
evolu.upsert("category", {
id: createIdFromString<"Category">(externalId),
name: NonEmptyTrimmedString100.orThrow(name),
});
}
};
// Create an instance with CategorySchema and call seedDefaultData(evolu)
// from a setup button or onboarding step.
Note: Using createIdFromString ensures deterministic IDs, so if a user clicks the button on multiple devices (e.g., after restoring their account but before sync completes), the same data will be upserted rather than duplicated. Upserting an existing row does not change its createdAt, but an upsert from a device that had not synced yet can move it earlier. Upserting also writes the passed columns again, so seeding after the user edited a row replaces that edit.
Alternative approach: Create Evolu without transports initially, verify the user through a backend service that knows whether it's their first login, then have the client insert data explicitly before enabling sync:
Using CategorySchema and seedDefaultData above, with the shared run and appOwner from Bring your own accounts:
import { AppName, createEvolu, WebSocketUrl } from "@evolu/common";
// Start without sync
const evolu = await run.ok(
createEvolu(CategorySchema, {
appName: AppName.orThrow("MyApp-Categories"),
transports: [],
appOwner,
}),
);
// After backend verification for first-time user
if (isFirstLogin) {
seedDefaultData(evolu);
}
// Enable sync on the same instance. Call unuseOwner() to release this use.
const unuseOwner = evolu.useOwner(appOwner, [
{ type: "WebSocket", url: WebSocketUrl.orThrow("wss://free.evoluhq.com/") },
]);
For reference data that rarely changes (like country or currency lists), consider whether it needs to be in the database at all—it might be better as a constant in your code or imported from a package.