Database driver structure

The package describes an engine in engine.json and exports an adapter from an ESM module. Built-in and installed engines use the same contract.

Files and manifest

example-db/
  engine.json
  entry.mjs
  src/

An example manifest for your own driver:

{
  "id": "example-db",
  "label": "Example database",
  "kind": "db-engine",
  "api": 1,
  "minimum": "0.0.0",
  "entry": "entry.mjs"
}

Field	Purpose
id	Unique identifier: 1–41 lowercase Latin letters, digits, hyphens or underscores; starts with a letter or digit.
label	Engine name in the interface.
kind, api	Package type db-engine and contract version 1.
minimum	Minimum stable GrigDesk version, X.Y.Z; replace the example with the minimum actually verified.
entry	Relative path to a regular .mjs file inside the package, without symlinks or node_modules.

The package version comes from a stable vX.Y.Z Git tag. An optional manifest version must match it. An external id cannot replace the built-in mysql or clickhouse engines. The names constructor, prototype and __proto__ are reserved.

If npm dependencies are needed, include package.json and a lockfile. The installer uses the shared dependency policy: lock v2/v3, without Git/file/link/URL dependencies or installation scripts.

Adapter contract

The entry point's default export is an object with id, label, JSON-compatible capabilities and all eight methods:

Method	Responsibility
open({ profile, password, stream, openStream })	Open a connection and return its handle; the password is a Buffer.
close(handle)	Close the connection.
schema(handle)	Return the database schema.
analyze(text, handle)	Classify the query and identify tables.
inspectRights(handle, session)	Inspect connection permissions.
estimate(handle, request, settings)	Estimate the query.
execute(handle, request)	Execute within the required limits.
cancel(handle, run)	Cancel execution.

Check exact result formats against the installed version's adapters in server/src/lib/db/engines/ and registry in server/src/lib/db/engineRegistry.ts. Method names alone do not guarantee correct query analysis, permission inspection or cancellation; verify those behaviors during development.

Storage and loading

Installed packages live in db-engines/<id>/ under the data directory; GRIGDESK_DB_ENGINES_DIR overrides the path. Preparation checks the manifest. The export and methods are checked when loading at server startup. Activation requires a manual restart.

Next: build a driver · install a package.