dsh-db-connector

中文说明

A database connector bundle for DeepSeek Harness (dsh, the "everything is a plugin" framework built on Cordis).

It gives your agent safe, audited access to SQLite, PostgreSQL and MySQL through five model-facing tools, plus a human /db command, with a deliberate focus on read-only safety, schema intelligence, write approval, and a durable SQL audit trail — an area the official dsh tool set does not cover.

This bundle is an independent, from-scratch implementation. It does not reuse any existing open-source dsh tool code; the tool names, parameter shapes, and result formats are this bundle's own design and are not tied to any official dsh schema.

---

Feature overview

Concern	What the bundle provides
Connections	Named connections for SQLite / PostgreSQL / MySQL; lazy open, reuse, explicit close, one line of redacted status per connection.
Credentials	Secrets come from environment variables (${VAR} placeholders, passwordEnv) or the dsh credentials service (passwordRef). Never written to logs or audit records.
Schema introspection	Tables, views, columns (name/type/nullable/default/primary key), indexes, foreign keys; per-connection snapshot cache with TTL, refresh and filter.
Read-only queries	db_query runs only SELECT / EXPLAIN-style statements. Everything else is rejected before it touches a database. Row caps, SELECT guard-LIMIT, JSON-safe results.
Write approval gate	INSERT / UPDATE / DELETE / DDL require an explicit allowWrite: true confirmation. Writes run inside a transaction: COMMIT on success, ROLLBACK on failure.
SQL audit	Every call (including denials and failures) appends one JSONL record: time, connection, statement digest + summary, kind, rows, duration, status, error, and who asked (tool/command/cli).
Injection safety	Values are always bound as parameters (? or :name), never interpolated into SQL text.
Timeouts	Per-statement AbortSignal deadlines with real termination, even for synchronous SQLite (child-process isolation).

---

Minimum requirements

• Node.js ≥ 22.13 (uses the built-in, unflagged node:sqlite).
• A running dsh profile for the tools to show up on ctx.tools.
• Optional server drivers (peer dependencies, only needed for those engines):
  • PostgreSQL: npm i pg
  • MySQL: npm i mysql2

SQLite needs nothing extra. Development (npm test) is easiest on Node ≥ 23.6, which runs the type-stripped test files natively.

---

How it plugs into dsh (bundle format)

This package is a bundle: package.json declares dsh.bundle.patch → ./cordis.patch.yml, and the patch inserts one plugin row that resolves the package by name. The entry module exports the standard name / inject / apply(ctx, config) contract.

Install the bundle into a profile:

dsh plugin --profile <name> add /path/to/dsh-db-connector

The package is also on npm for the standalone tooling / programmatic API:

npm install -g dsh-db-connector   # global CLI-style usage of the engine
npm install dsh-db-connector      # or add it as a local dependency

(Equivalently: add it to the profile's dependencies ("dsh-db-connector": "link:/path/to/dsh-db-connector") and append "dsh-db-connector" to dsh.profile.bundles.)

…