feat: Add database restart command

[joshrotenberg]

Overview

Add a command to restart Redis processes for a database, similar to rladmin's restart db <id> command.

Use Case

Database restarts are needed for:

• Applying certain configuration changes
• Recovering from hung processes
• Clearing memory after heavy operations
• Testing failover behavior
• Troubleshooting connectivity issues

Current Workaround

No direct way via redisctl - must use rladmin or manual failover:

# Option 1: SSH and use rladmin
ssh admin@cluster-node
rladmin restart db db:1

# Option 2: Trigger failover (not a true restart)
redisctl enterprise database failover <id>

Desired Behavior

# Restart database (with automatic role preservation)
redisctl enterprise database restart 1

# Output
Restarting database 'prod-db' (db:1)...
  ✓ Restarting slave shards (redis:2, redis:4, redis:6)
  ✓ Restarting master shards (redis:1, redis:3, redis:5)
  ✓ Verifying connectivity
Database restart complete (45 seconds)

# Restart without preserving roles (faster, but roles may swap)
redisctl enterprise database restart 1 --no-preserve-roles

# Force restart even with warnings
redisctl enterprise database restart 1 --force

# Discard data (for non-persisted databases)
redisctl enterprise database restart 1 --discard-data

# Wait for restart to complete
redisctl enterprise database restart 1 --wait

# JSON output
redisctl enterprise database restart 1 -o json
{
  "database_id": 1,
  "status": "success",
  "shards_restarted": 6,
  "duration_seconds": 45,
  "roles_preserved": true
}

Implementation Requirements

1. API Verification

First, verify if the REST API exposes a restart endpoint:

# Test against local Docker cluster
curl -k -u "admin@redis.local:Redis123!" \
  -X POST \
  https://localhost:9443/v1/bdbs/1/restart

If endpoint exists: Straightforward implementation
If endpoint doesn't exist: Need to investigate alternatives (failover-based approach?)

2. Command Structure

#[derive(Debug, Clone, Parser)]
pub struct RestartArgs {
    /// Database ID
    pub database_id: i32,
    
    /// Don't preserve master/slave roles (faster)
    #[arg(long)]
    pub no_preserve_roles: bool,
    
    /// Discard data (for non-persisted DBs)
    #[arg(long)]
    pub discard_data: bool,
    
    /// Force restart even with warnings
    #[arg(long)]
    pub force: bool,
    
    /// Wait for restart to complete
    #[arg(long)]
    pub wait: bool,
    
    /// Timeout for wait (seconds)
    #[arg(long, default_value = "300")]
    pub timeout: u64,
    
    /// Output format
    #[arg(short, long, value_enum, default_value = "table")]
    pub output_format: OutputFormat,
}

3. Safety Checks

Before restarting, validate:

// Pre-restart validation
async fn validate_restart(client: &Client, db_id: i32, force: bool) -> CliResult<()> {
    let db = client.databases().get(db_id).await?;
    
    // Check if database is active
    if db.status != "active" && !force {
        bail!("Database is not active (status: {}). Use --force to restart anyway.", db.status);
    }
    
    // Warn about data loss if not persisted
    if !db.persistence_enabled && !force {
        eprintln!("⚠️  Warning: Database has no persistence. Data may be lost.");
        eprintln!("Use --discard-data to confirm, or --force to proceed anyway.");
        bail!("Restart cancelled for safety");
    }
    
    // Check replication
    if db.replication_enabled {
        eprintln!("✓ Replication enabled - safe restart");
    } else if !force {
        eprintln!("⚠️  Warning: Database has no replication. Restart will cause downtime.");
        eprintln!("Use --force to proceed.");
        bail!("Restart cancelled for safety");
    }
    
    Ok(())
}

4. Restart Workflow

pub async fn restart_database(
    client: &Client,
    args: RestartArgs,
) -> CliResult<()> {
    // 1. Validate
    validate_restart(client, args.database_id, args.force).await?;
    
    // 2. Get database info
    let db = client.databases().get(args.database_id).await?;
    let shards = client.shards().list_for_database(args.database_id).await?;
    
    println!("Restarting database '{}' (db:{})...", db.name, args.database_id);
    
    // 3. Call restart API
    let response = client
        .databases()
        .restart(args.database_id, RestartRequest {
            preserve_roles: !args.no_preserve_roles,
            discard_data: args.discard_data,
        })
        .await?;
    
    // 4. Wait if requested
    if args.wait {
        wait_for_database_active(client, args.database_id, args.timeout).await?;
    }
    
    println!("✓ Database restart complete");
    Ok(())
}

rladmin Equivalent

# Basic restart
rladmin restart db db:1

# Restart with role preservation
rladmin restart db db:1 preserve_roles

# Restart and discard data
rladmin restart db db:1 discard_data

# Force discard even with persistence
rladmin restart db db:1 discard_data force_discard

Benefits

1. Remote restart - No SSH required (vs rladmin)
2. Safety checks - Validates before restarting
3. Wait mode - Automatic polling until restart completes
4. Structured output - JSON for automation
5. Clear feedback - Progress indicators and status

Risks & Considerations

1. Downtime - Restarting causes temporary unavailability
2. Data loss - If not persisted/replicated
3. Connection disruption - All clients will be disconnected
4. Timing - Consider maintenance windows

Testing Plan

1. Test against Docker cluster first
2. Verify API endpoint exists
3. Test with persisted vs non-persisted databases
4. Test with replicated vs non-replicated databases
5. Test role preservation
6. Test wait mode and timeout

Related

• Issue Enhancement: Consider adding rladmin-inspired features #416 - Parent issue for rladmin-inspired features
• Issue feat: Add database restart command #421 - Database upgrade command (similar workflow)
• examples/presentation/RLADMIN_COMPARISON.md - Feature comparison

Priority

Medium - Useful operational command, but requires API verification first.

Next Steps

1. ✅ Create this issue to track the feature
2. ⏳ Verify if /v1/bdbs/<id>/restart endpoint exists in REST API
3. ⏳ If exists, implement command
4. ⏳ If not, evaluate alternatives (failover-based approach)

[joshrotenberg]

❌ API Endpoint Does Not Exist

Tested against Docker Redis Enterprise cluster and the restart endpoint does not exist.

Testing Results

# Test 1: /v1/bdbs/1/actions/restart
curl -k -u "admin@redis.local:Redis123!" \
  -X POST https://localhost:9443/v1/bdbs/1/actions/restart
# Result: HTTP 404 Not Found

# Test 2: /v1/bdbs/1/restart  
curl -k -u "admin@redis.local:Redis123!" \
  -X POST https://localhost:9443/v1/bdbs/1/restart
# Result: HTTP 404 Not Found

# Test 3: Confirmed working action for comparison
curl -k -u "admin@redis.local:Redis123!" \
  -X POST https://localhost:9443/v1/bdbs/3/actions/stop_traffic
# Result: HTTP 200 OK - {"action_uid": "52d3e3af..."}

Documentation Search

Searched Redis Enterprise REST API documentation extensively:

• ❌ No /v1/bdbs/{uid}/actions/restart endpoint documented
• ✅ Other actions exist: stop_traffic, resume_traffic, rebalance, recover, etc.
• ❌ Not mentioned in official REST API specifications

Existing Code Issue

The redis-enterprise crate currently has a restart() method that calls a non-existent endpoint:

// Line 546 in crates/redis-enterprise/src/bdb.rs
pub async fn restart(&self, uid: u32) -> Result<DatabaseActionResponse> {
    self.client.post(
        &format!("/v1/bdbs/{}/actions/restart", uid),  // ❌ Does not exist!
        &serde_json::json!({}),
    ).await
}

This method will always fail with a 404 error.

Alternative Approaches

Since there's no restart endpoint, we have a few options:

Option 1: Remove the Non-Working Method

• Remove the restart() method from the library
• Close this issue as "not supported by API"
• Document in issue Enhancement: Consider adding rladmin-inspired features #416 that restart is not available

Option 2: Implement Restart via Stop/Resume

Create a helper that uses existing endpoints:

pub async fn restart_database_workaround(
    client: &EnterpriseClient,
    uid: u32
) -> Result<()> {
    // 1. Stop traffic
    client.databases().stop_traffic(uid).await?;
    
    // 2. Wait for traffic to stop
    tokio::time::sleep(Duration::from_secs(2)).await;
    
    // 3. Resume traffic  
    client.databases().resume_traffic(uid).await?;
    
    Ok(())
}

Limitations:

• This doesn't actually restart Redis processes
• Only pauses/resumes traffic
• May not achieve the same effect as rladmin restart

Option 3: Wait for API Support

• Keep issue open
• Mark as "blocked - waiting for API support"
• Revisit when Redis Enterprise adds restart endpoint

Recommendation

I recommend Option 1 for now:

1. Remove the non-functional restart() method
2. Document that restart is not available via REST API
3. Note in documentation that users must use rladmin for database restarts

The stop/resume workaround doesn't provide the same functionality as an actual restart (which restarts the Redis processes), so it would be misleading to call it "restart".

Related

Similar issue might exist with the start() and stop() methods - should verify those too.

[joshrotenberg]

🔍 Additional Finding: Multiple Non-Existent Endpoints

Tested additional "action" endpoints and found more issues:

Endpoints That Do NOT Exist

1. ❌ POST /v1/bdbs/{uid}/actions/restart - Returns 404
2. ❌ POST /v1/bdbs/{uid}/actions/start - Returns 404
3. ❌ POST /v1/bdbs/{uid}/actions/stop - Returns 404

Endpoints That DO Exist

1. ✅ POST /v1/bdbs/{uid}/actions/stop_traffic - Works (pauses traffic)
2. ✅ POST /v1/bdbs/{uid}/actions/resume_traffic - Works (resumes traffic)
3. ✅ POST /v1/bdbs/{uid}/actions/flush - Should work (haven't tested)
4. ✅ POST /v1/bdbs/{uid}/actions/backup - Should work
5. ✅ Many others documented in redis.io

Library Cleanup Needed

The redis-enterprise crate has THREE non-functional methods:

// ❌ All three of these call non-existent endpoints
pub async fn start(&self, uid: u32) -> Result<Value>
pub async fn stop(&self, uid: u32) -> Result<Value>  
pub async fn restart(&self, uid: u32) -> Result<DatabaseActionResponse>

Proposed Action

Convert Issue #421 to a Cleanup Task

Instead of implementing a restart command, let's:

1. Remove non-functional methods from redis-enterprise/src/bdb.rs:

   • Remove start() method (line ~526)
   • Remove stop() method (line ~536)
   • Remove restart() method (line ~546)

2. Add deprecation notice if removal would break compatibility

3. Update documentation to clarify:

   • Database start/stop/restart require rladmin CLI
   • Use stop_traffic/resume_traffic for traffic control
   • Traffic control != process restart

4. Add comment in CLAUDE.md documenting these non-existent endpoints

Updated Issue Title

Suggest changing from:

"feat: Add database restart command"

To:

"chore: Remove non-functional start/stop/restart methods from redis-enterprise library"

This way we're cleaning up technical debt rather than trying to implement a feature that the API doesn't support.

Impact

Low Risk:

• These methods likely aren't used since they return 404
• Better to remove than leave broken code
• Users expecting restart can use rladmin

Benefits:

• Cleaner API surface
• No misleading method names
• Clearer documentation about limitations

Would you like me to create a PR for the cleanup?

[joshrotenberg]

Resolution: Cannot Implement - API Endpoints Do Not Exist

After thorough investigation, I've confirmed that the database restart/start/stop endpoints do not exist in the Redis Enterprise REST API.

Verification

1. Docker Cluster Testing:

# All return 404 Not Found
curl -k -u "admin@redis.local:Redis123!" -X POST https://localhost:9443/v1/bdbs/1/actions/restart
curl -k -u "admin@redis.local:Redis123!" -X POST https://localhost:9443/v1/bdbs/1/actions/start  
curl -k -u "admin@redis.local:Redis123!" -X POST https://localhost:9443/v1/bdbs/1/actions/stop

2. Official Documentation:
Comprehensive search of redis.io REST API docs shows the complete list of database action endpoints:

✅ Existing endpoints:

• stop_traffic / resume_traffic (pause/resume traffic, NOT the same as stop/start)
• export / import / recover
• optimize_shards_placement / rebalance
• backup_reset_status / import_reset_status / export_reset_status

❌ Non-existent endpoints:

• restart - Not documented
• start - Not documented
• stop - Not documented

Cleanup

The library incorrectly contained these three non-functional methods. Removed in PR #443:

• BdbHandler::start()
• BdbHandler::stop()
• BdbHandler::restart()

Alternative

While rladmin restart db exists as a CLI command, it uses internal mechanisms not exposed via REST API. Users can use stop_traffic + resume_traffic for maintenance windows, though this doesn't restart the database process itself.