Introduction

The storage center of DeepSeek Harness (DSH) (ctx.storage) depends on JSON files by default. For scenarios requiring persistence, crash recovery, or cross-process visibility, file storage is often not the best choice. @sandersyao/dsh-storage-mysql provides an alternative, migrating the storage backend to a MySQL database.

Plugin Introduction

This is a DeepSeek Harness storage plugin maintained by sandersyao. Its core purpose is to serve as an alternative to @deepseek-ai/dsh-storage-json. By registering a MySQL backend, it persists KV storage units into InnoDB tables, meeting the requirements for ACID compliance, crash safety, and multi-process visibility.

Core Features

  1. Backend Replacement: After being loaded as a plugin, it registers a backend named mysql on ctx.storage.backend.
  2. KV Interface: Exposes the kv facet, providing standard read and write operations.
  3. Data Persistence: Uses the MySQL InnoDB engine to implement ACID transactions. Writes are persisted immediately, crash recovery is supported, and data can be shared across multiple processes.
  4. Distributed Deployment Component: It is one of the four core components for distributed DSH deployments and should be used together with dsh-credentials-mysql, dsh-session-persistence-mysql, and dsh-workspace-bootstrap.

Installation and Enablement

The package name is @sandersyao/dsh-storage-mysql.

Code Integration

Import and register it at the DSH plugin entry point:

import { apply, Config, inject, name } from '@sandersyao/dsh-storage-mysql'

ctx.plugin(
  { apply, Config, inject, name },
  { connection: { tablePrefix: 'dsh_storage_' } }
)

Configure the Storage Domain

In the configuration file, point the backend of storage-domain to mysql:

{ backend: 'mysql' }

Integration Method

The plugin provides a cordis.patch.yml file. The simplest path is to introduce it via a bundle patch. This keeps the default storage-json backend available while pointing storage-domain.backend to mysql.

Configuration Guide

The plugin does not hard-code credentials directly in code. Instead, it reads them from environment variables or a .env file.

Environment Variables

The plugin first reads variables prefixed with STORAGE_* and falls back to MYSQL_* variables if they are not set.

  • STORAGE_HOST / MYSQL_HOST: 127.0.0.1 by default
  • STORAGE_PORT / MYSQL_PORT: 3306 by default
  • STORAGE_USER / MYSQL_USER: Required. Use a least-privilege user
  • STORAGE_PASSWORD / MYSQL_PASSWORD: Required
  • STORAGE_DATABASE / MYSQL_DATABASE: Required. The target database name
  • STORAGE_TABLE_PREFIX / MYSQL_TABLE_PREFIX: Required. Table prefix (only alphanumeric characters and underscores are allowed). Ensure it does not conflict with the session/credentials plugin prefixes
  • STORAGE_SSL_REQUIRED / MYSQL_SSL_REQUIRED: false by default
  • STORAGE_POOL_SIZE / MYSQL_POOL_SIZE: 10 by default
  • STORAGE_SCHEMA_AUTO_MIGRATE / MYSQL_SCHEMA_AUTO_MIGRATE: true by default. Automatically migrate the schema at startup

Storage Structure and Security

Table Structure

The plugin creates three tables under the specified prefix:
* Pstorage_units: Storage unit definitions and version information.
* Pstorage_records: JSON values corresponding to (unit_name, table_name, record_key).
* Pstorage_meta: The currently applied schema version.

Security Mechanisms

  • Parameter Binding: unit_name, table_name, and record_key are always bound as parameters (rather than SQL identifiers), preventing SQL injection.
  • Credential Isolation: Credentials never appear in code or configuration files.

Notes

  • Use Cases: Suitable for distributed DSH deployments that require cross-process state sharing or strong consistency.
  • License: MIT.
  • Ecosystem Note: This plugin is an item included in a community catalog and has no official affiliation with DeepSeek or High-Flyer.

Conclusion

@sandersyao/dsh-storage-mysql provides DSH with a mature MySQL storage backend. It ensures data safety through ACID compliance and runtime safety through parameter binding. For deployments that prioritize stability and distributed capabilities, it is a reliable choice.

View catalog page
GitHub repository