Registry / database / sqlite-replication

sqlite-replication

library0.0.26-bjsnpmunverified

A TypeScript module for replicating SQLite databases between a mobile client (using Capacitor SQLite plugin) and a server. Version 0.0.26-b provides a master-slave replication pattern with server-side conflict resolution. It is designed for offline-first mobile apps and is framework-agnostic. Released at an early stage (pre-v1) with frequent updates. Key differentiators: works with existing SQLite queries, no query builder lock-in, supports multiple server protocols (REST, GraphQL, WebSocket), and integrates with Capacitor SQLite and Jeep-SQLite.

database mobile

npm install sqlite-replication

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SQLITE-REPLICATION

sqlite-replication

databasejavascriptv0.0.26-b

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ReplicationSQLiteStorage

✓ import { ReplicationSQLiteStorage } from 'sqlite-replication'

✗ const ReplicationSQLiteStorage = require('sqlite-replication')

ESM-only; CommonJS require() will fail because the package exports ESM modules.

ReplicationService

✓ import { ReplicationService } from 'sqlite-replication'

Used together with ReplicationSQLiteStorage to configure and run replication.

ReplicationHelpers

✓ import { ReplicationHelpers } from 'sqlite-replication'

✗ import { ReplicationHelpers } from 'sqlite-replication/helpers'

Import from the main package, not a subpath. Provides getDefaultCollectionOptions().

Sets up SQLite replication with Capacitor SQLite, defines collections and server sync endpoints, initializes checkpoints, and triggers a replication cycle.

import { ReplicationSQLiteStorage, ReplicationService, ReplicationHelpers } from 'sqlite-replication'; // Assume 'db' is already initialized with @capacitor-community/sqlite const storage = new ReplicationSQLiteStorage(db); const replicationService = new ReplicationService(storage, { collections: [ ReplicationHelpers.getDefaultCollectionOptions(db, 'users'), { name: 'todos', batchSize: 99, getDocumentOffset: async (updatedAt: number, id: string) => ({ updatedAt, id }), upsertAll: async (documents: any[]) => { /* implement */ }, deleteAll: async (documents: any[]) => { /* implement */ }, findChanges: async (state: any) => { /* implement */ } } ], fetchPull: async (pullConfig: any) => { const response = await fetch(`${process.env.API_URL}/replicationPull`, { method: 'POST', body: JSON.stringify(pullConfig), headers: { 'Content-Type': 'application/json' } }); return response.json(); }, fetchPush: async () => { const response = await fetch(`${process.env.API_URL}/replicationPush`, { method: 'POST', headers: { 'Content-Type': 'application/json' } }); return response.json(); } }); await replicationService.init(); await replicationService.replicate();

Debug

Known issues

breakingRequires tables to have specific columns: id, updateAt, deletedAt, _forkParent. Missing columns will cause replication failure.

fix

Add these columns to all replicated tables: id TEXT PRIMARY KEY, updateAt INTEGER, deletedAt INTEGER, _forkParent TEXT.

affects: >=0.0.1

gotchaDeleted documents must be soft-deleted using a deletedAt column; hard deletes are not supported and may cause sync issues.

fix

Use UPDATE SET deletedAt = timestamp instead of DELETE. The client and server must keep deleted records.

affects: >=0.0.1

gotchaServer must return documents in a predictable order (ORDER BY updatedAt, id). Otherwise, the pull replication may miss changes.

fix

Ensure your server API sorts results by updatedAt then id ascending.

affects: >=0.0.1

gotchaForeign key constraints should be disabled in a distributed context. Circular references can cause sync issues.

fix

Set PRAGMA foreign_keys = OFF on the client side and adjust server schema accordingly.

affects: >=0.0.1

gotchaThe package is pre-v1 and may have breaking changes in minor versions. Lock the exact version in package.json.

fix

Use 'sqlite-replication': '0.0.26-b' (or current version) without ^ or ~ in dependencies.

affects: >=0.0.1

Errors

Common errors & fixes

TypeError: ReplicationSQLiteStorage is not a constructor

Importing using CommonJS require() instead of ESM import.

fix

Change to: import { ReplicationSQLiteStorage } from 'sqlite-replication';

Cannot find module 'sqlite-replication' or its corresponding type declarations.

Missing TypeScript declaration files or incorrect module resolution.

fix

Ensure typescript is installed and tsconfig.json has 'moduleResolution': 'node' and 'esModuleInterop': true.

Error: Collection 'mytable' not found. Did you forget to define it?

The collection name in config does not match the actual SQLite table name.

fix

Verify the 'name' property in collections array matches the exact table name in SQLite.

SQLITE_ERROR: table mytable has no column named updateAt

The table is missing the required 'updateAt' column.

fix

ALTER TABLE mytable ADD COLUMN updateAt INTEGER NOT NULL DEFAULT 0;

Upgrade

Version history

0.0.26-blatest on npm

Audit

Dependencies

@capacitor-community/sqliterequiredPeer dependency for accessing SQLite database on Capacitor-based mobile apps.

Agent activity

58 hits · last 30 days

node