DEBUG command not exposed as first-class API

[affonsov]

Summary

This issue documents the outcome of the investigation into whether valkey-glide should implement the DEBUG command as a first-class API, and explains how users who need it should proceed.

Background

The DEBUG command is an internal Valkey server command tagged @admin @dangerous @slow, described by Valkey itself as "an internal command meant for developing and testing Valkey." Sub-commands range from informational to catastrophic:

Sub-command	Risk
SEGFAULT	Crashes the server immediately
SLEEP <seconds>	Blocks the server event loop for N seconds
RELOAD	Forces a full RDB dump + reload
CHANGE-REPL-ID	Breaks replication
OBJECT <key>	Returns encoding, refcount, serialized-length — safe
SET-ACTIVE-EXPIRE	Controls lazy expiry behavior

Precedent: jedis

jedis implemented DebugParams in 3.x, then deprecated and deleted it entirely in 4.x, citing the command's dangerous and internal nature. This is the clearest signal from the ecosystem.

Decision: Not implemented as glide command

valkey-glide does not and will not implement DEBUG as a typed public API method. Reasons:

1. Dangerous surface area: DEBUG SEGFAULT, DEBUG SLEEP, and DEBUG CHANGE-REPL-ID can crash or disrupt production systems. A typed client.debug(...) normalizes this.
2. Blocked on managed cloud: AWS ElastiCache disables DEBUG entirely — a first-class method would silently fail for a large portion of production users.
3. No unique value: The only sub-command with practical application-developer value — DEBUG OBJECT — is already accessible via the existing customCommand API.

How to use DEBUG if you need it

Use the customCommand (raw command) API available in all language clients:

# Python
await client.custom_command(["DEBUG", "OBJECT", "mykey"])

// Node.js / TypeScript
await client.customCommand(["DEBUG", "OBJECT", "mykey"]);

// Java
client.customCommand(new String[]{"DEBUG", "OBJECT", "mykey"}).get();

// Go
client.CustomCommand(ctx, []string{"DEBUG", "OBJECT", "mykey"})

⚠️ Warning: Sub-commands like DEBUG SEGFAULT, DEBUG SLEEP, and DEBUG CHANGE-REPL-ID can crash, hang, or corrupt your Valkey server. Only use them in controlled, non-production environments.

For valkey-glide internal test infrastructure

If glide's own integration test suite needs sub-commands like DEBUG SET-ACTIVE-EXPIRE (to force TTL expiry) or DEBUG SLEEP (to simulate latency), use customCommand within the test layer — no public API additions needed.

References

• Valkey DEBUG command documentation
• jedis DebugParams removal: redis/jedis#3803

[harish18092002]

#245

@affonsov