|
| 1 | +# Disable Maintenance Notifications Example |
| 2 | + |
| 3 | +This example demonstrates how to use the go-redis client with maintenance notifications **disabled**. |
| 4 | + |
| 5 | +## What are Maintenance Notifications? |
| 6 | + |
| 7 | +Maintenance notifications are a Redis Cloud feature that allows the server to notify clients about: |
| 8 | +- Planned maintenance events |
| 9 | +- Failover operations |
| 10 | +- Node migrations |
| 11 | +- Cluster topology changes |
| 12 | + |
| 13 | +The go-redis client supports three modes: |
| 14 | +- **`ModeDisabled`**: Client doesn't send `CLIENT MAINT_NOTIFICATIONS ON` command |
| 15 | +- **`ModeEnabled`**: Client forcefully sends the command, interrupts connection on error |
| 16 | +- **`ModeAuto`** (default): Client tries to send the command, disables feature on error |
| 17 | + |
| 18 | +## When to Disable Maintenance Notifications |
| 19 | + |
| 20 | +You should disable maintenance notifications when: |
| 21 | + |
| 22 | +1. **Connecting to non-Redis Cloud / Redis Enterprise instances** - Standard Redis servers don't support this feature |
| 23 | +2. **You want to handle failovers manually** - Your application has custom failover logic |
| 24 | +3. **Minimizing client-side overhead** - You want the simplest possible client behavior |
| 25 | +4. **The Redis server doesn't support the feature** - Older Redis versions or forks |
| 26 | + |
| 27 | +## Usage |
| 28 | + |
| 29 | +### Basic Example |
| 30 | + |
| 31 | +```go |
| 32 | +import ( |
| 33 | + "github.com/redis/go-redis/v9" |
| 34 | + "github.com/redis/go-redis/v9/maintnotifications" |
| 35 | +) |
| 36 | + |
| 37 | +rdb := redis.NewClient(&redis.Options{ |
| 38 | + Addr: "localhost:6379", |
| 39 | + |
| 40 | + // Explicitly disable maintenance notifications |
| 41 | + MaintNotificationsConfig: &maintnotifications.Config{ |
| 42 | + Mode: maintnotifications.ModeDisabled, |
| 43 | + }, |
| 44 | +}) |
| 45 | +defer rdb.Close() |
| 46 | +``` |
| 47 | + |
| 48 | +### Cluster Client Example |
| 49 | + |
| 50 | +```go |
| 51 | +rdbCluster := redis.NewClusterClient(&redis.ClusterOptions{ |
| 52 | + Addrs: []string{"localhost:7000", "localhost:7001", "localhost:7002"}, |
| 53 | + |
| 54 | + // Disable maintenance notifications for cluster |
| 55 | + MaintNotificationsConfig: &maintnotifications.Config{ |
| 56 | + Mode: maintnotifications.ModeDisabled, |
| 57 | + }, |
| 58 | +}) |
| 59 | +defer rdbCluster.Close() |
| 60 | +``` |
| 61 | + |
| 62 | +### Default Behavior (ModeAuto) |
| 63 | + |
| 64 | +If you don't specify `MaintNotifications`, the client defaults to `ModeAuto`: |
| 65 | + |
| 66 | +```go |
| 67 | +// This uses ModeAuto by default |
| 68 | +rdb := redis.NewClient(&redis.Options{ |
| 69 | + Addr: "localhost:6379", |
| 70 | + // MaintNotificationsConfig: nil means ModeAuto |
| 71 | +}) |
| 72 | +``` |
| 73 | + |
| 74 | +With `ModeAuto`, the client will: |
| 75 | +1. Try to enable maintenance notifications |
| 76 | +2. If the server doesn't support it, silently disable the feature |
| 77 | +3. Continue normal operation |
| 78 | + |
| 79 | +## Running the Example |
| 80 | + |
| 81 | +1. Start a Redis server: |
| 82 | + ```bash |
| 83 | + redis-server --port 6379 |
| 84 | + ``` |
| 85 | + |
| 86 | +2. Run the example: |
| 87 | + ```bash |
| 88 | + go run main.go |
| 89 | + ``` |
| 90 | + |
| 91 | +## Expected Output |
| 92 | + |
| 93 | +``` |
| 94 | +=== Example 1: Explicitly Disabled === |
| 95 | +✓ Connected successfully (maintenance notifications disabled) |
| 96 | +✓ SET operation successful |
| 97 | +✓ GET operation successful: value1 |
| 98 | +
|
| 99 | +=== Example 2: Default Behavior (ModeAuto) === |
| 100 | +✓ Connected successfully (maintenance notifications auto-enabled) |
| 101 | +
|
| 102 | +=== Example 3: Cluster Client with Disabled Notifications === |
| 103 | +Cluster not available (expected): ... |
| 104 | +
|
| 105 | +=== Example 4: Performance Comparison === |
| 106 | +✓ 1000 SET operations (disabled): 45ms |
| 107 | +✓ 1000 SET operations (auto): 46ms |
| 108 | +
|
| 109 | +=== Cleanup === |
| 110 | +✓ Database flushed |
| 111 | +
|
| 112 | +=== Summary === |
| 113 | +Maintenance notifications can be disabled by setting: |
| 114 | + MaintNotificationsConfig: &maintnotifications.Config{ |
| 115 | + Mode: maintnotifications.ModeDisabled, |
| 116 | + } |
| 117 | +
|
| 118 | +This is useful when: |
| 119 | + - Connecting to non-Redis Cloud instances |
| 120 | + - You want to handle failovers manually |
| 121 | + - You want to minimize client-side overhead |
| 122 | + - The Redis server doesn't support CLIENT MAINT_NOTIFICATIONS |
| 123 | +``` |
| 124 | + |
| 125 | +## Performance Impact |
| 126 | + |
| 127 | +Disabling maintenance notifications has minimal performance impact. The main differences are: |
| 128 | + |
| 129 | +1. **Connection Setup**: One less command (`CLIENT MAINT_NOTIFICATIONS ON`) during connection initialization |
| 130 | +2. **Runtime Overhead**: No background processing of maintenance notifications |
| 131 | +3. **Memory Usage**: Slightly lower memory footprint (no notification handlers) |
| 132 | + |
| 133 | +In most cases, the performance difference is negligible (< 1%). |
0 commit comments