feat: add Database API — server-managed database for plugins

[dirkwa]

Summary

Add a server-managed Database API that gives plugins access to an isolated relational database, eliminating the need for plugins to ship their own database binaries (better-sqlite3, DuckDB, etc.).

Follows the established provider pattern (History API, Resources API, Weather API) and the naming conventions from #2417.

• Each plugin gets its own SQLite database file at {configPath}/plugin-db/{pluginId}.db
• Two built-in providers: _builtin_nodesqlite (node:sqlite, preferred on Node ≥22.5.0) and _builtin (better-sqlite3, fallback for Node <22.5.0)
• Both providers use the same on-disk SQLite format — no data migration needed when switching
• Community plugins can register alternative backends (e.g. PostgreSQL) via registerDatabaseProvider()
• Async interface (Promise<>) supports both sync and async backends
• HTTP endpoints at /signalk/v2/api/database/_providers for provider management
• Native modules loaded lazily with try/catch guards — server never crashes if a backend is unavailable

Plugin API surface

const db = await app.getDatabaseApi().getPluginDb(plugin.id)
await db.migrate([{ version: 1, sql: 'CREATE TABLE ...' }])
const rows = await db.query('SELECT * FROM foo WHERE bar = ?', [42])
const result = await db.run('INSERT INTO foo (bar) VALUES (?)', [42])
await db.transaction(async (tx) => { /* atomic ops */ })

Node.js compatibility

Node Version	node:sqlite	better-sqlite3	Default Provider
20.x	—	yes	_builtin
22.x	yes	yes	_builtin_nodesqlite
24.x	yes	yes	_builtin_nodesqlite

Tested all three versions with nvm use, clean npm install, and verified provider registration via REST API.

Commits

1. feat: add Database API with pluggable provider architecture — interfaces, both SQLite providers, registry, HTTP routes, server bootstrap, plugin wiring
2. feat: prefer node:sqlite over better-sqlite3 when available — flip default preference, add lazy require guard for better-sqlite3
3. refactor: rename DatabaseApiRegistry to DatabaseProviderRegistry — align with RFC: Consistent Naming Conventions for Provider and API Interfaces #2417 naming conventions
4. docs: add Database API documentation — REST API docs, provider plugin guide, JSDoc

Files

• packages/server-api/src/databaseapi.ts — public interfaces (DatabaseApi, PluginDb, DatabaseProviderRegistry) with JSDoc
• src/api/database/sqliteprovider.ts — better-sqlite3 provider (lazy require)
• src/api/database/nodesqliteprovider.ts — node:sqlite provider (lazy require)
• src/api/database/index.ts — registry, HTTP routes, provider management
• src/api/index.ts, src/interfaces/plugins.ts — server bootstrap and plugin wiring
• docs/develop/rest-api/database_api.md — REST API documentation
• docs/develop/plugins/database_provider_plugins.md — provider plugin guide

Tested with

• signalk-postgsail plugin migrated as proof-of-concept consumer — removed better-sqlite3 dependency, verified migrations, query, run, and transaction on a live server with real GPS data
• All three Node.js versions (20, 22, 24) verified with clean installs

Fixes: #2407

[dirkwa]

What do you think about using this database also for infernal storage, like: #2369 (review) ?

Having it all at a central place could be very beneficial for backup and restore.

[dirkwa]

NOTE:

Researching for the Plugin developer CI I found that

Victron Cerbo uses in latest 3.70.x node 20

I will look into a practical solution, not to loose this device.

PR back to draft.

[dirkwa]

The Cerbo node 20 topic is solved.

I decided to keep this PR clean and will bring a follow up PR "on top" of this one for a separate server db as addressed in #2369 (review) to implement further improvements of the signalk-server while separating the plugin db and the server db while reusing the infrastructure.

Ready for review.

[dirkwa]

Additional samples where this would be a great fit:

noforeignland/nfl-signalk — a track logger that:

• Stores position data as JSONL (pending.jsonl) — one {lat, lon, t} per line via fs.appendFile()
• Has to manage its own file lifecycle — pending.jsonl for unsent data, sent.jsonl for archives
• Already had to write a migration (TrackMigration.ts) because the file naming scheme changed between versions — exactly the kind of schema evolution a database handles natively
• Reads back data by streaming the whole file line-by-line via readline — no indexing, no querying by time range
• Has to handle partial writes / corruption — invalid lines are skipped but not recoverable

signalk-logbook — daily YAML files, full-file rewrites on every entry edit

signalk-anchoralarm-plugin

• Saves anchor state (position, radius, rode) to state.json via getDataDirPath()
• Also calls savePluginOptions with a debounce timer to avoid hammering the filesystem
• Classic "small structured state" that's a perfect fit for a DB record

@meri-imperiumi/signalk-logbook

• Stores log entries as one YAML file per day
• Every single-entry edit rewrites the entire day file
• No cross-day search capability without reading every file
• A database table with indexed datetime and category columns would be far better

signalk-tide-watch

• Had to build a custom binary circular file format for depth readings because no storage API exists
• Uses getDataDirPath() for the binary files

signalk-polar-recorder

• Stores polar data files in getDataDirPath()
• Lists files via fs.readdirSync(app.getDataDirPath())
• Loads data via manual file reads

Any alarm/notification plugin — storing alarm history as individual files is fragile