WATCH - Upstash Documentation

Use WATCH to mark keys whose modification should cancel the next transaction, which gives you optimistic locking. If any watched key is changed by another client between the WATCH and the EXEC, the transaction is not executed and EXEC replies with null instead. Nothing is locked in the meantime: other clients keep working normally, and the conflict is detected rather than prevented. The usual loop is: watch the keys, read them, decide what to write, open MULTI, queue the writes, and call EXEC, retrying from the top when the reply is null. That is how a read-modify-write cycle stays correct without holding a lock. All watches are cleared by EXEC and DISCARD. The raw command is TCP-only. Over HTTP, use the transaction or pipeline API of an Upstash SDK instead of sending this command directly.

Syntax

WATCH <key> [<key> ...]

Arguments

Argument	Required	Repeatable	Description
`<key>`	Yes	Yes	Redis key targeted by the command.

Important points

The raw command is TCP-only. For HTTP, use an Upstash SDK transaction API rather than sending this command directly.

Response

The reply reports the result of the operation. Error replies have the same shape in RESP2 and RESP3 and are surfaced as exceptions by the SDKs below.

Protocol	Reply
RESP2	Simple string `OK`
RESP3	Simple string `OK`

Client libraries often decode bulk strings, maps, sets, and numeric strings into language-native values. The table describes the Redis wire reply.

Examples

TCP examples use the TLS REDIS_URL from the Upstash console. REST examples use UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN.

Redis CLI

WATCH balance

ioredis

import Redis from "ioredis";

const client = new Redis(process.env.REDIS_URL!);
await client.watch("balance");
const result = await client.multi().set("balance", "100").exec();

node-redis

import { createClient } from "redis";

const client = await createClient({ url: process.env.REDIS_URL }).connect();
await client.watch("balance");
const result = await client.multi().set("balance", "100").exec();

redis-py

import os
import redis

client = redis.from_url(os.environ["REDIS_URL"])
with client.pipeline() as pipe:
    pipe.watch("balance")
    pipe.multi()
    pipe.set("balance", "100")
    result = pipe.execute()

go-redis

ctx := context.Background()
opts, err := redis.ParseURL(os.Getenv("REDIS_URL"))
if err != nil { panic(err) }
client := redis.NewClient(opts)

err = client.Watch(ctx, func(tx *redis.Tx) error {
    _, err := tx.TxPipelined(ctx, func(pipe redis.Pipeliner) error {
        pipe.Set(ctx, "balance", "100", 0)
        return nil
    })
    return err
}, "balance")
if err != nil { panic(err) }

jedis

import java.net.URI;
import redis.clients.jedis.Jedis;
import redis.clients.jedis.Transaction;

try (Jedis jedis = new Jedis(new URI(System.getenv("REDIS_URL")))) {
  jedis.watch("balance");
  try (Transaction transaction = jedis.multi()) {
    transaction.set("balance", "100");
    Object result = transaction.exec();
  }
}

redis-rs

fn main() -> redis::RedisResult<()> {
    let url = std::env::var("REDIS_URL").expect("REDIS_URL is not set");
    let client = redis::Client::open(url)?;
    let mut connection = client.get_connection()?;

    let _: () = redis::transaction(&mut connection, &["balance"], |con, pipe| {
        pipe.set("balance", "100").ignore().query::<Option<()>>(con)
    })?;
    Ok(())
}

​Syntax

​Arguments

​Important points

​Response

​Examples

Syntax

Arguments

Important points

Response

Examples