go-redis/example/digest-optimistic-locking/README.md

Redis Digest & Optimistic Locking Example

This example demonstrates how to use Redis DIGEST command and digest-based optimistic locking with go-redis.

What is Redis DIGEST?

The DIGEST command (Redis 8.4+) returns a 64-bit xxh3 hash of a key's value. This hash can be used for:

• Optimistic locking: Update values only if they haven't changed
• Change detection: Detect if a value was modified
• Conditional operations: Delete or update based on expected content

Features Demonstrated

1. Basic Digest Usage: Get digest from Redis and verify with client-side calculation
2. Optimistic Locking with SetIFDEQ: Update only if digest matches (value unchanged)
3. Change Detection with SetIFDNE: Update only if digest differs (value changed)
4. Conditional Delete: Delete only if digest matches expected value
5. Client-Side Digest Generation: Calculate digests without fetching from Redis

Requirements

• Redis 8.4+ (for DIGEST command support)
• Go 1.18+

Installation

cd example/digest-optimistic-locking
go mod tidy

Running the Example

# Make sure Redis 8.4+ is running on localhost:6379
redis-server

# In another terminal, run the example
go run .

Expected Output

=== Redis Digest & Optimistic Locking Example ===

1. Basic Digest Usage
---------------------
Key: user:1000:name
Value: Alice
Digest: 7234567890123456789 (0x6478a1b2c3d4e5f6)
Client-calculated digest: 7234567890123456789 (0x6478a1b2c3d4e5f6)
✓ Digests match!

2. Optimistic Locking with SetIFDEQ
------------------------------------
Initial value: 100
Current digest: 0x1234567890abcdef
✓ Update successful! New value: 150
✓ Correctly rejected update with wrong digest

3. Detecting Changes with SetIFDNE
-----------------------------------
Initial value: v1.0.0
Old digest: 0xabcdef1234567890
✓ Value changed! Updated to: v2.0.0
✓ Correctly rejected: current value matches the digest

4. Conditional Delete with DelExArgs
-------------------------------------
Created session: session:abc123
Expected digest: 0x9876543210fedcba
✓ Correctly refused to delete (wrong digest)
✓ Successfully deleted with correct digest
✓ Session deleted

5. Client-Side Digest Generation
---------------------------------
Current price: $29.99
Expected digest (calculated client-side): 0xfedcba0987654321
✓ Price updated successfully to $24.99

Binary data example:
Binary data digest: 0x1122334455667788
✓ Binary digest matches!

=== All examples completed successfully! ===

How It Works

Digest Calculation

Redis uses the xxh3 hashing algorithm. To calculate digests client-side, use github.com/zeebo/xxh3:

import "github.com/zeebo/xxh3"

// For strings
digest := xxh3.HashString("myvalue")

// For binary data
digest := xxh3.Hash([]byte{0x01, 0x02, 0x03})

Optimistic Locking Pattern

// 1. Read current value and get its digest
currentValue := rdb.Get(ctx, "key").Val()
currentDigest := rdb.Digest(ctx, "key").Val()

// 2. Perform business logic
newValue := processValue(currentValue)

// 3. Update only if value hasn't changed
result := rdb.SetIFDEQ(ctx, "key", newValue, currentDigest, 0)
if result.Err() == redis.Nil {
    // Value was modified by another client - retry or handle conflict
}

Client-Side Digest (No Extra Round Trip)

// If you know the expected current value, calculate digest client-side
expectedValue := "100"
expectedDigest := xxh3.HashString(expectedValue)

// Update without fetching digest from Redis first
result := rdb.SetIFDEQ(ctx, "counter", "150", expectedDigest, 0)

Use Cases

1. Distributed Counter with Conflict Detection

// Multiple clients can safely update a counter
currentValue := rdb.Get(ctx, "counter").Val()
currentDigest := rdb.Digest(ctx, "counter").Val()

newValue := incrementCounter(currentValue)

// Only succeeds if no other client modified it
if rdb.SetIFDEQ(ctx, "counter", newValue, currentDigest, 0).Err() == redis.Nil {
    // Retry with new value
}

2. Session Management

// Delete session only if it contains expected data
sessionData := "user:1234:active"
expectedDigest := xxh3.HashString(sessionData)

deleted := rdb.DelExArgs(ctx, "session:xyz", redis.DelExArgs{
    Mode:        "IFDEQ",
    MatchDigest: expectedDigest,
}).Val()

3. Configuration Updates

// Update config only if it changed
oldConfig := loadOldConfig()
oldDigest := xxh3.HashString(oldConfig)

newConfig := loadNewConfig()

// Only update if config actually changed
result := rdb.SetIFDNE(ctx, "config", newConfig, oldDigest, 0)
if result.Err() != redis.Nil {
    fmt.Println("Config updated!")
}

Advantages Over WATCH/MULTI/EXEC

• Simpler: Single command instead of transaction
• Faster: No transaction overhead
• Client-side digest: Can calculate expected digest without fetching from Redis
• Works with any command: Not limited to transactions

Learn More

• Redis DIGEST command
• Redis SET command with IFDEQ/IFDNE
• xxh3 hashing algorithm
• github.com/zeebo/xxh3

Comparison: XXH3 vs XXH64

Note: Redis uses XXH3, not XXH64. If you have github.com/cespare/xxhash/v2 in your project, it implements XXH64 which produces different hash values. You must use github.com/zeebo/xxh3 for Redis DIGEST operations.

See XXHASH_LIBRARY_COMPARISON.md for detailed comparison.