Registry / database / declarative-sqlite

declarative-sqlite

library2.2.29jsnpmunverified

TypeScript port of declarative_sqlite for PWA and Capacitor applications. Version 2.2.29 (stable) provides zero code generation via JavaScript Proxy, automatic schema migration, and built-in conflict resolution for offline-first apps. Key differentiators: tiny bundle (~15KB gzipped), RxJS reactive queries, multi-backend support (wa-sqlite, Capacitor, better-sqlite3), and HLC+LWW conflict resolution. Release cadence is frequent (multiple updates per month). Requires rxjs as a peer dependency.

database

npm install declarative-sqlite

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · DECLARATIVE-SQLITE

declarative-sqlite

databasejavascriptv2.2.29

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.

SchemaBuilder

✓ import { SchemaBuilder } from 'declarative-sqlite'

✗ const { SchemaBuilder } = require('declarative-sqlite')

ESM-only; does not export CommonJS. Use dynamic import if needed in Node.

DeclarativeDatabase

✓ import { DeclarativeDatabase } from 'declarative-sqlite'

✗ import * as declarative from 'declarative-sqlite'; const db = new declarative.DeclarativeDatabase(...)

Named export, not part of a default namespace.

AdapterFactory

✓ import { AdapterFactory } from 'declarative-sqlite'

Factory to create adapters for different backends.

StorageBackend

✓ import { StorageBackend } from 'declarative-sqlite'

✗ Interface is a type export; use import type if not needed at runtime.

Enum-like object for specifying storage backend.

Defines a users schema with automatic migration and inserts/query records using DeclarativeDatabase.

import { SchemaBuilder, DeclarativeDatabase, AdapterFactory } from 'declarative-sqlite'; const schema = new SchemaBuilder() .table('users', t => { t.guid('id').notNull(''); t.text('name').notNull(''); t.text('email').notNull(''); t.integer('age').notNull(0); t.key('id').primary(); }) .build(); const adapter = await AdapterFactory.create({ name: 'myapp.db', enableWAL: true, }); const db = new DeclarativeDatabase({ adapter, schema, autoMigrate: true }); await db.initialize(); await db.insert('users', { id: 'u1', name: 'Alice', email: 'alice@example.com', age: 30 }); const users = await db.query('users', { where: 'age >= ?', whereArgs: [21] }); console.log(users);

Debug

Known issues

breakingIn v2.0.0, the API changed from class-based to factory-based adapter creation. Old code using new Adapter() will break.

fix

Use AdapterFactory.create() instead of direct instantiation.

affects: <2.0.0

deprecatedThe method db.createRecord() uses Proxy objects; some TypeScript strict mode configurations may complain about property assignments on Proxy targets.

fix

Use explicit type assertion with 'as' or cast the record to the desired type.

affects: >=1.0.0

gotchaTable names and column definitions in SchemaBuilder are case-sensitive. Mismatched casing between schema and query leads to silent failures.

fix

Always use lowercase table/column names in schema and queries.

affects: >=1.0.0

gotchaThe autoMigrate option does not rollback on failure; partial migrations may leave the database in an inconsistent state.

fix

Manually backup database before schema changes or disable autoMigrate for production.

affects: >=2.0.0

Errors

Common errors & fixes

Error: Cannot find module 'declarative-sqlite'

Package not installed or installed without peer dependency rxjs.

fix

Run 'npm install declarative-sqlite rxjs' (rxjs is a required peer dependency)

TypeError: db.insert is not a function

Calling insert before the database is fully initialized.

fix

Ensure you await db.initialize() before any CRUD operations.

Error: SchemaBuilder: Duplicate table name 'users'

Defining the same table twice in the schema.

fix

Remove duplicate table definitions from the schema builder chain.

Error: AdapterFactory.create: backend not supported

Invalid backend string or unsupported environment (e.g., StorageBackend.OPFS in Node.js).

fix

Check environment compatibility; use StorageBackend.Auto for automatic detection.

Upgrade

Version history

2.2.29latest on npm

Audit

Dependencies

rxjsrequiredPeer dependency for reactive streaming queries

Agent activity

13 hits · last 30 days

node

Resources

githubhttps://github.com/graknol/declarative_sqlite ↗

packagedeclarative-sqlite ↗

homepagehttps://github.com/graknol/declarative_sqlite#readme ↗