WebSocket Admin Operations

The DBX WebSocket API provides admin operations for server management and monitoring.

Installation

npm install @0dbx/redis

Basic Usage

import { DbxWsClient } from "@0dbx/redis";
 
// Create WebSocket client
const wsClient = new DbxWsClient("ws://localhost:3000/redis_ws");
 
// Admin operations
const health = await wsClient.admin.health();
const ping = await wsClient.admin.ping();

Connection Setup

Before using admin operations, establish a WebSocket connection with admin privileges:

import { DBXWebSocketClient } from "@effortlesslabs/dbx";
 
const client = new DBXWebSocketClient({
  url: "ws://localhost:8080/ws",
  token: "your-admin-jwt-token",
});
 
await client.connect();

Admin Operations

INFO - Get Server Information

Get detailed information about the server and database.

Request:

{
  "id": "req-1",
  "method": "INFO",
  "params": {
    "section": "all"
  }
}

Response:

{
  "id": "req-1",
  "result": {
    "server": {
      "version": "1.0.0",
      "uptime": 86400,
      "mode": "standalone",
      "os": "Linux 5.4.0",
      "arch": "x86_64"
    },
    "clients": {
      "connected_clients": 10,
      "blocked_clients": 0,
      "max_clients": 10000
    },
    "memory": {
      "used_memory": 1048576,
      "used_memory_peak": 2097152,
      "used_memory_rss": 1572864
    },
    "stats": {
      "total_commands_processed": 1000000,
      "total_connections_received": 5000,
      "keyspace_hits": 800000,
      "keyspace_misses": 200000
    }
  }
}

PING - Test Connection

Test the connection and get response time.

Request:

{
  "id": "req-2",
  "method": "PING",
  "params": {
    "message": "Hello DBX"
  }
}

Response:

{
  "id": "req-2",
  "result": {
    "pong": "Hello DBX",
    "latency_ms": 1.5
  }
}

FLUSHDB - Clear Current Database

Clear all keys from the current database.

Request:

{
  "id": "req-3",
  "method": "FLUSHDB",
  "params": {
    "async": false
  }
}

Response:

{
  "id": "req-3",
  "result": {
    "success": true,
    "keys_removed": 1000
  }
}

FLUSHALL - Clear All Databases

Clear all keys from all databases.

Request:

{
  "id": "req-4",
  "method": "FLUSHALL",
  "params": {
    "async": false
  }
}

Response:

{
  "id": "req-4",
  "result": {
    "success": true,
    "keys_removed": 5000
  }
}

KEYS - Find Keys by Pattern

Find keys matching a pattern.

Request:

{
  "id": "req-5",
  "method": "KEYS",
  "params": {
    "pattern": "user:*"
  }
}

Response:

{
  "id": "req-5",
  "result": {
    "keys": ["user:123", "user:456", "user:789"],
    "count": 3
  }
}

SCAN - Iterate Over Keys

Iterate over keys using cursor-based pagination.

Request:

{
  "id": "req-6",
  "method": "SCAN",
  "params": {
    "cursor": 0,
    "count": 10,
    "match": "user:*"
  }
}

Response:

{
  "id": "req-6",
  "result": {
    "cursor": 0,
    "keys": ["user:123", "user:456", "user:789"]
  }
}

DEL - Delete Keys

Delete one or more keys.

Request:

{
  "id": "req-7",
  "method": "DEL",
  "params": {
    "keys": ["user:123", "user:456", "temp:data"]
  }
}

Response:

{
  "id": "req-7",
  "result": {
    "deleted": 3
  }
}

EXISTS - Check Key Exists

Check if one or more keys exist.

Request:

{
  "id": "req-8",
  "method": "EXISTS",
  "params": {
    "keys": ["user:123", "user:456", "nonexistent:key"]
  }
}

Response:

{
  "id": "req-8",
  "result": {
    "exists": 2
  }
}

TYPE - Get Key Type

Get the data type of a key.

Request:

{
  "id": "req-9",
  "method": "TYPE",
  "params": {
    "key": "user:123"
  }
}

Response:

{
  "id": "req-9",
  "result": {
    "type": "hash"
  }
}

TTL - Get Key TTL

Get the time-to-live of a key.

Request:

{
  "id": "req-10",
  "method": "TTL",
  "params": {
    "key": "session:123"
  }
}

Response:

{
  "id": "req-10",
  "result": {
    "ttl": 3600
  }
}

EXPIRE - Set Key Expiration

Set the time-to-live for a key.

Request:

{
  "id": "req-11",
  "method": "EXPIRE",
  "params": {
    "key": "session:123",
    "seconds": 3600
  }
}

Response:

{
  "id": "req-11",
  "result": {
    "success": true
  }
}

PERSIST - Remove Key Expiration

Remove the expiration from a key.

Request:

{
  "id": "req-12",
  "method": "PERSIST",
  "params": {
    "key": "session:123"
  }
}

Response:

{
  "id": "req-12",
  "result": {
    "success": true
  }
}

RENAME - Rename Key

Rename a key.

Request:

{
  "id": "req-13",
  "method": "RENAME",
  "params": {
    "key": "old:key",
    "new_key": "new:key"
  }
}

Response:

{
  "id": "req-13",
  "result": {
    "success": true
  }
}

RENAMENX - Rename Key if Not Exists

Rename a key only if the new name doesn't exist.

Request:

{
  "id": "req-14",
  "method": "RENAMENX",
  "params": {
    "key": "old:key",
    "new_key": "new:key"
  }
}

Response:

{
  "id": "req-14",
  "result": {
    "success": true,
    "renamed": true
  }
}

DBSIZE - Get Database Size

Get the number of keys in the current database.

Request:

{
  "id": "req-15",
  "method": "DBSIZE",
  "params": {}
}

Response:

{
  "id": "req-15",
  "result": {
    "size": 1000
  }
}

SLOWLOG - Get Slow Query Log

Get the slow query log entries.

Request:

{
  "id": "req-16",
  "method": "SLOWLOG",
  "params": {
    "count": 10
  }
}

Response:

{
  "id": "req-16",
  "result": {
    "entries": [
      {
        "id": 1,
        "timestamp": 1642234567,
        "duration": 150,
        "command": ["GET", "user:123"],
        "client": "127.0.0.1:6379"
      }
    ]
  }
}

CONFIG GET - Get Configuration

Get configuration parameters.

Request:

{
  "id": "req-17",
  "method": "CONFIG_GET",
  "params": {
    "parameter": "maxmemory"
  }
}

Response:

{
  "id": "req-17",
  "result": {
    "maxmemory": "2gb"
  }
}

CONFIG SET - Set Configuration

Set configuration parameters.

Request:

{
  "id": "req-18",
  "method": "CONFIG_SET",
  "params": {
    "parameter": "maxmemory",
    "value": "1gb"
  }
}

Response:

{
  "id": "req-18",
  "result": {
    "success": true
  }
}

Error Handling

All WebSocket admin operations return standardized error responses:

{
  "id": "request-id",
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable error message"
  }
}

Common error codes:

PERMISSION_DENIED: Insufficient privileges for the operation
KEY_NOT_FOUND: The specified key doesn't exist
INVALID_PARAMETER: Invalid parameter value
AUTHENTICATION_FAILED: Invalid or missing authentication token
RATE_LIMITED: Request rate limit exceeded
OPERATION_FAILED: The operation failed to complete

TypeScript SDK Example

import { DbxWsClient } from "@0dbx/redis";
 
const wsClient = new DbxWsClient("ws://localhost:3000/redis_ws");
 
// Admin operations
const health = await wsClient.admin.health();
console.log(health); // { status: "ok", timestamp: "..." }
 
const ping = await wsClient.admin.ping();
console.log(ping); // "pong"

Best Practices

Admin Privileges: Only use admin operations with proper authentication and authorization
Production Safety: Be extremely careful with destructive operations like FLUSHDB/FLUSHALL
Monitoring: Use INFO and SLOWLOG operations for monitoring and debugging
Key Management: Use SCAN instead of KEYS for large datasets
Configuration: Document configuration changes and their impact
Backup: Always backup data before performing destructive operations

Performance Considerations

KEYS operation can be slow on large datasets - use SCAN instead
FLUSHDB/FLUSHALL operations are blocking and can impact performance
INFO operations can be expensive - cache results when possible
SLOWLOG operations should be used sparingly in production
Configuration changes may require server restart to take effect

Security Considerations

Admin operations require special privileges
Never expose admin endpoints to public networks
Use strong authentication for admin access
Log all admin operations for audit purposes
Consider using separate admin tokens with limited scope