replic-sqlite

library0.4.0jsnpmunverified

Replic-sqlite adds multi-writer, conflict-free replication to SQLite via CRDT patches, using only ~800 lines of code. Version 0.4.0 is actively developed and already used in production. Key differentiators: extremely lightweight, no leader bottleneck, protocol-agnostic transport, selective per-table replication, crash-safe, and supports rolling schema upgrades. Compared to libSQL, Turso, cr-sqlite, or dqlite, it is purely embedded (no separate process) and relies on CRDT for eventual consistency without strong ordering.

database

npm install replic-sqlite

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REPLIC-SQLITE

replic-sqlite

databasejavascriptv0.4.0

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.

ReplicSQLite

✓ import { ReplicSQLite } from 'replic-sqlite'

✗ const ReplicSQLite = require('replic-sqlite')

Module is ESM-only; no CommonJS export.

createServer

✓ import { createServer } from 'replic-sqlite/server'

✗ import { createServer } from 'replic-sqlite'

Server factory is exported from a subpath; not at package root.

default

✓ import Replic from 'replic-sqlite'

✗ import { ReplicSQLite } from 'replic-sqlite'

Default export provides a pre-configured instance; named export ReplicSQLite is the class.

Shows how to set up a replic-sqlite server and client with WebSocket transport for multi-writer replication.

import { ReplicSQLite } from 'replic-sqlite'; import { createServer } from 'replic-sqlite/server'; import Database from 'better-sqlite3'; const db = new Database(':memory:'); db.exec(`CREATE TABLE IF NOT EXISTS todos (id TEXT PRIMARY KEY, task TEXT, done INTEGER)`); db.exec(`CREATE TABLE IF NOT EXISTS todos_patches (id TEXT PRIMARY KEY, patch BLOB)`); const replic = new ReplicSQLite({ db, secret: process.env.SECRET ?? 'changeme' }); // Create a WebSocket server that handles sync const server = createServer({ replic, port: 8080 }); server.start(); console.log('Replic server running on ws://localhost:8080'); // In another process, connect a client import WebSocket from 'ws'; const ws = new WebSocket('ws://localhost:8080'); const replicClient = new ReplicSQLite({ db: new Database(':memory:'), secret: 'changeme' }); replicClient.connect(ws);

Debug

Known issues

breakingIn v0.4.0, the table enumeration pattern changed: all tables to be replicated MUST have a corresponding `_patches` table. Tables without a patches table are silently ignored.

fix

Add a `_patches` table (id TEXT PRIMARY KEY, patch BLOB) for each table you want to sync.

affects: >=0.3.0

breakingThe 'createServer' function moved from 'replic-sqlite' to 'replic-sqlite/server' in v0.4.0. Old imports break.

fix

Use `import { createServer } from 'replic-sqlite/server'` instead of `import { createServer } from 'replic-sqlite'`.

affects: >=0.4.0

deprecatedThe option 'syncInterval' (used in constructor) is deprecated in v0.4.0 and will be removed in v0.5.0. Use 'syncIntervalMs' instead.

fix

Rename 'syncInterval' to 'syncIntervalMs' in the config object.

affects: >=0.4.0 <0.5.0

gotchaDefault export `Replic` is a pre-configured instance, but its internal database connection uses a fixed file path. Overriding the database path may cause silent failure.

fix

Always construct your own `ReplicSQLite` instance with explicit `db` parameter for predictable database location.

affects: >=0.1.0

gotchaThe 'secret' option must be identical on all replicas; mismatched secrets will cause silent disconnect without error.

fix

Ensure 'secret' is the same string on every node. Use environment variables to distribute it.

affects: >=0.1.0

Errors

Common errors & fixes

Error: cannot find module 'replic-sqlite/server'

Importing from a subpath that doesn't exist in older versions or using wrong case.

fix

Run `npm install replic-sqlite@latest`. Use correct import: `import { createServer } from 'replic-sqlite/server'`. Note that the 'server' subpath was added in v0.4.0.

TypeError: ReplicSQLite is not a constructor

Using default import as class, or using CommonJS require incorrectly.

fix

If using ESM, use `import { ReplicSQLite } from 'replic-sqlite'`. If using CommonJS, replic-sqlite does not support it; wrap with dynamic import or switch to ESM.

SQLITE_ERROR: no such table: todos_patches

Replic-sqlite requires a patches table for each replicated table, but it wasn't created.

fix

Create a `_patches` table for each table you intend to replicate: `CREATE TABLE todos_patches (id TEXT PRIMARY KEY, patch BLOB)`.

Upgrade

Version history

0.4.0latest on npm

Audit

Dependencies

better-sqlite3requiredSQLite bindings used internally for database operations

Agent activity

7 hits · last 30 days

node

Resources

githubssh://git@github.com/carboneio/replic-sqlite ↗

packagereplic-sqlite ↗

homepagehttps://github.com/carboneio/replic-sqlite#readme ↗