DeepSeek Harness (DSH) uses an “everything is a plugin” architecture. Although its official toolset covers basic capabilities, database access security, read-only restrictions, write approval, and audit trails often require additional handling. The db-connector plugin provides a complete solution for this, supporting SQLite, PostgreSQL, and MySQL, and protecting data security through named connections, schema introspection, and read-only protection.

The plugin is named johnxu22786/db-connector and is maintained by JohnXu22786. It is a database connector package that provides connection management, schema introspection, read-only security policies, write approval gating, and SQL audit logging.

Core Features

The plugin focuses on four core aspects of database access:

  • Connection Management: Supports named connections for SQLite, PostgreSQL, and MySQL. Connections support lazy opening and reuse, avoiding the overhead of frequent connection establishment.
  • Credential Security: Passwords are managed through environment variables or the dsh credential service. Configuration supports passwordEnv or passwordRef, and passwords are never written to logs or audit records.
  • Schema Introspection: Provides queries for table, view, column, index, and foreign key information. Supports connection-based caching (TTL), with a refresh parameter to force cache refresh and a filter parameter to filter table names.
  • Access Control:
    • Read-Only Protection: The db_query tool only allows SELECT, EXPLAIN, DESCRIBE, and SHOW statements. Any other statements (including INSERT/UPDATE/DELETE/DDL) are intercepted before reaching the database and are recorded as denied audit entries.
    • Write Approval: INSERT/UPDATE/DELETE/DDL operations require explicit approval confirmation. Transaction protection and automatic commit handling are supported.

Installation and Activation

Before installing, ensure the environment meets the following requirements:
* Node.js version >= 22.16
* An active dsh profile
* Optional dependencies: pg for PostgreSQL and mysql2 for MySQL

Install the plugin to a specified profile from the command line:

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

After installation, the configuration file must declare dsh.bundle.patch pointing to the package’s cordis.patch.yml, or import it in the profile’s dependencies.

Configuration and Usage

Configuration is usually written in the plugin’s config block and can be in YAML format. The following is a basic configuration example:

- insert:
    - id: db-connector
      name: 'dsh-db-connector'
      inject: [tools, commands]
      config:
        # 预注册连接，将在首次使用时延迟打开
        connections:
          appdata:
            driver: sqlite
            database: ./data/app.db
          warehouse:
            driver: postgres
            host: db.internal
            database: warehouse
            user: readonly
            passwordEnv: WAREHOUSE_PG_PASSWORD

        audit:
          enabled: true
          path: .dsh-db/audit.jsonl

        query:
          maxRows: 1000
          timeoutMs: 30000
          maxSqlChars: 512

        schema:
          ttlMs: 60000

        defaultAllowWrite: false

Credential References

Passwords are stored by reference rather than in plain text. passwordEnv reads from environment variables, while passwordRef references the dsh credential service. Strings in the configuration support ${VAR} placeholders, which the system expands from environment variables when connecting.

Tool Usage

The plugin registers three main tools:

  1. db_connect: Manages connections.

    • Register/reconnect: { "action": "connect", "name": "app", "config": { "driver": "sqlite", "database": "./data/app.db" } }
    • List connections: { "action": "list" }
    • Close connection: { "action": "close", "name": "app" }

  2. db_schema: Queries structure.

    • Query structure: { "name": "app", "refresh": false, "filter": "user" }

  3. db_query: Executes read-only queries.

    • Execute query: { "sql": "SELECT * FROM users LIMIT 10" }
    • This tool protects SQL statements against injection through parameter binding and limits the number of result rows and the length of the query string.

Notes

  • Independent Implementation: This is a standalone plugin implemented from scratch. It does not depend on official DSH tool code, and its tool names and parameter formats are not tied to the official architecture.
  • Runtime Environment: The plugin runs with the privileges of the current dsh process. Review the source code and license before installation.
  • Audit Records: All database calls (including successful queries, denied write attempts, and failed statements) generate JSONL audit logs containing the timestamp, connection, statement summary, duration, status, and request source.