sqlite-nas-sync

library0.9.0jsnpmunverified

SQLite database synchronization across multiple clients via NAS using changelog-based conflict resolution. Version 0.9.0, actively maintained. Each client operates on a local SQLite database and synchronizes changes through a shared NAS directory. Key differentiators: automatic table discovery using schema introspection (no manual table list), SQLite trigger-based changelog for incremental sync, Last Write Wins conflict resolution using a timestamp column, support for per-table configuration (timestamp column name, delete protection), heartbeat mechanism to extend changelog retention, and an event system for monitoring sync progress. Requires Node.js >=16 and peer dependency better-sqlite3 >=11.0.0. ESM-only with built-in TypeScript types.

database storage

npm install sqlite-nas-sync

package ↗

INSTALL

IMPORT

SIG · SQLITE-NAS-SYNC

sqlite-nas-sync

databasejavascriptv0.9.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.

setupSync

✓ import { setupSync } from 'sqlite-nas-sync'

✗ const { setupSync } = require('sqlite-nas-sync')

Package is ESM-only; require() will fail. Use dynamic import() or ensure your project is ESM (type: module in package.json).

discoverTables

✓ import { discoverTables } from 'sqlite-nas-sync'

✗ import discoverTables from 'sqlite-nas-sync'

discoverTables is a named export, not default. Named imports are available from v0.9.0.

SyncConfig

✓ import type { SyncConfig } from 'sqlite-nas-sync'

✗ import { SyncConfig } from 'sqlite-nas-sync'

SyncConfig is a TypeScript type; use import type to avoid runtime errors. Available as a type export in v0.9.0.

Initializes a sync instance, performs a manual sync, starts periodic sync, and stops after 60 seconds.

import { setupSync } from 'sqlite-nas-sync'; const sync = setupSync({ dbPath: './data/local.sqlite', nasPath: '/mnt/nas/shared-db/', clientId: 'client-abc123', }); await sync.syncNow().then(result => { console.log(`Inserted: ${result.inserted}, Updated: ${result.updated}`); }); sync.start(); setTimeout(() => sync.stop(), 60000);

Debug

Known issues

gotchaSynchronization requires a NAS that supports atomic file copy operations. Non-atomic network filesystems may cause corruption.

fix

Ensure the NAS filesystem supports O_DIRECT or use a local NAS mount with proper locking.

affects: >=0.0.0

breakingIn v0.9.0, table discovery was redesigned: tables missing a TEXT primary key named 'id' and a timestamp column named 'updatedAt' are now excluded. Previously, any table with a primary key was included.

fix

Add 'id' (TEXT) and 'updatedAt' columns to tables you want to sync, or use tableOptions to override column names.

affects: >=0.9.0

deprecatedThe 'autoDetect' option was removed in v0.9.0. Table detection is now automatic and cannot be disabled.

fix

Remove any autoDetect: false from config. If you need to exclude tables, use the 'excludeTables' option.

affects: <0.9.0

gotchaPeriodic sync interval (intervalMs) default is 30 seconds. Shorter intervals may cause high I/O load on NAS and SQLite WAL file growth.

fix

Adjust intervalMs based on your change frequency; monitor disk usage.

affects: >=0.0.0

Errors

Common errors & fixes

Error: No synchronous tables found in database.

No table in the database meets the automatic discovery criteria (TEXT primary key 'id' and timestamp column 'updatedAt').

fix

Add proper columns: ALTER TABLE your_table ADD COLUMN id TEXT NOT NULL PRIMARY KEY; ALTER TABLE your_table ADD COLUMN updatedAt TEXT; or set tableOptions for custom column names.

TypeError: Cannot read properties of undefined (reading 'syncNow')

Using CommonJS require() instead of ESM import. The package is ESM-only and returns undefined when required.

fix

Change to ESM: use import { setupSync } from 'sqlite-nas-sync' or use dynamic import: const { setupSync } = await import('sqlite-nas-sync')

Error: better-sqlite3 is not installed. Please install better-sqlite3 as a dependency.

Missing peer dependency better-sqlite3.

fix

Run: npm install better-sqlite3

Error: NAS path is not a directory or not writable.

The provided nasPath does not exist or is not writable by the current user.

fix

Ensure the NAS directory exists and is writable: mkdir -p /mnt/nas/shared-db && chmod 755 /mnt/nas/shared-db

Error: Changelog table '_changelog' incompatible with version X. Expected schema version Y.

The local changelog table schema does not match the current package version's expected schema.

fix

Drop the existing changelog table: DROP TABLE IF EXISTS _changelog; than re-run setupSync. Note: this will lose pending changes.

Upgrade

Version history

0.9.0latest on npm

Audit

Dependencies

better-sqlite3optionalpeer dependency for SQLite database access

Agent activity

20 hits · last 30 days

node