signalk-database

library0.2.0jsnpmunverified

SQLite library and admin UI for SignalK Node Server plugins, version 0.2.0 (early development, active). Provides isolated per-plugin SQLite databases via `openPluginDb(app)`, with WAL mode, foreign keys, caching. Includes web-based admin UI for browsing all plugin databases disk. Requires Node >=22.5.0 (uses built-in `node:sqlite`). No server-side cooperation needed. Differentiator: zero-config per-plugin isolation, admin UI that sees all databases regardless of plugin status, and integration with signalk-backup for transactional backups via `VACUUM INTO`.

database devops

npm install signalk-database

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SIGNALK-DATABASE

signalk-database

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

openPluginDb

✓ import { openPluginDb } from 'signalk-database'

✗ const openPluginDb = require('signalk-database').openPluginDb

ESM-only due to Node 22+ module system. No CommonJS support.

PluginDb

✓ import type { PluginDb } from 'signalk-database'

✗ import { PluginDb } from 'signalk-database'

PluginDb is a TypeScript interface, not a class. Use type-only import.

Migration

✓ import type { Migration } from 'signalk-database'

✗ const Migration = require('signalk-database/types').Migration

Migration is a type, not a runtime value. TypeScript only.

Shows how a SignalK plugin ESM module imports openPluginDb, migrates a table, and queries data.

// plugin.js export default function (app) { let db; return { id: 'my-plugin', name: 'My Plugin', async start() { const { openPluginDb } = await import('signalk-database'); db = await openPluginDb(app); await db.migrate([ { version: 1, sql: 'CREATE TABLE IF NOT EXISTS settings (key TEXT PRIMARY KEY, value TEXT)' }, ]); const rows = await db.query('SELECT * FROM settings'); console.log(rows); }, async stop() {}, }; }

Debug

Known issues

breakingRequires Node >=22.5.0 because it uses built-in node:sqlite. Older Node versions throw MODULE_NOT_FOUND.

fix

Upgrade Node to 22.5.0 or later.

affects: >=0.0.0

gotchaThe plugin is automatically enabled on install (signalk-plugin-enabled-by-default) after server restart. It may add an unconfigured SQLite database unexpectedly.

fix

Manually disable the plugin in SignalK admin UI if not needed.

affects: >=0.0.0

gotchaopenPluginDb returns a cached handle per plugin ID. Calling with the same pluginId returns the same database instance. The migrate function is re-entrant safe but should only be called once per version.

fix

Do not call migrate multiple times; check version carefully.

affects: >=0.0.0

Errors

Common errors & fixes

Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'signalk-database'

Peer dependency not installed or not added to package.json.

fix

Add "signalk-database": "^0.2" to your plugin's peerDependencies and run npm install.

TypeError: openPluginDb is not a function

CommonJS require incorrectly used on ESM-only package.

fix

Use dynamic import or static ESM import: import { openPluginDb } from 'signalk-database'.

Error: Cannot find module 'node:sqlite'

Node version <22.5.0 does not have built-in node:sqlite.

fix

Upgrade Node to 22.5.0+.

Upgrade

Version history

0.2.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

10 hits · last 30 days

node