> ## Documentation Index
> Fetch the complete documentation index at: https://cache-pot.thatdevguy.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Pub/Sub commands: SUBSCRIBE, PUBLISH, PSUBSCRIBE

> Reference for Cache-Pot pub/sub commands: SUBSCRIBE, UNSUBSCRIBE, PSUBSCRIBE, PUNSUBSCRIBE, PUBLISH for real-time messaging.

Cache-Pot supports publish/subscribe messaging, letting you decouple producers from consumers through named channels. When you subscribe to a channel, your connection enters a special subscriber mode and receives messages pushed by any client that publishes to that channel. A slow subscriber that fills its output buffer will have messages dropped rather than blocking publishers — fan-out is non-blocking by design.

<Note>
  While a connection has active subscriptions, use a separate connection for regular data commands including `PUBLISH`. Call `UNSUBSCRIBE` / `PUNSUBSCRIBE` (or `RESET`) to release all subscriptions and return the connection to normal command mode.
</Note>

***

### SUBSCRIBE

Subscribes to one or more channels. After this command your connection enters subscriber mode. For each channel you subscribe to, Cache-Pot sends a confirmation reply: `["subscribe", channel, subscription_count]`.

**Syntax:** `SUBSCRIBE channel [channel ...]`

```redis theme={null}
# Terminal 1: subscribe and wait for messages
SUBSCRIBE notifications alerts

# Cache-Pot confirms each subscription:
# 1) "subscribe"
# 2) "notifications"
# 3) (integer) 1

# 1) "subscribe"
# 2) "alerts"
# 3) (integer) 2
```

**Returns:** A 3-element array for each channel: `["subscribe", channel_name, total_subscription_count]`.

***

### UNSUBSCRIBE

Unsubscribes from one or more channels. Omit channel names to unsubscribe from all channels at once. Cache-Pot sends a confirmation reply for each channel unsubscribed. When your total subscription count (channels + patterns) drops to zero, the connection leaves subscriber mode.

**Syntax:** `UNSUBSCRIBE [channel ...]`

```redis theme={null}
# Unsubscribe from a specific channel
UNSUBSCRIBE notifications

# Unsubscribe from all channels
UNSUBSCRIBE
```

**Returns:** A 3-element array for each unsubscription: `["unsubscribe", channel_name, total_subscription_count]`.

***

### PSUBSCRIBE

Subscribes to one or more glob patterns. You will receive messages from any channel whose name matches a subscribed pattern. Patterns use the same syntax as `KEYS`: `*` matches any sequence, `?` matches any single character, `[...]` matches a character class.

Messages delivered through a pattern subscription arrive as 4-element `pmessage` replies: `["pmessage", pattern, channel, message]`.

**Syntax:** `PSUBSCRIBE pattern [pattern ...]`

```redis theme={null}
# Subscribe to all user-related channels
PSUBSCRIBE user:*

# Confirmation:
# 1) "psubscribe"
# 2) "user:*"
# 3) (integer) 1

# When a message arrives on user:42:
# 1) "pmessage"
# 2) "user:*"
# 3) "user:42"
# 4) "hello"
```

**Returns:** A 3-element confirmation per pattern: `["psubscribe", pattern, total_subscription_count]`.

***

### PUNSUBSCRIBE

Unsubscribes from one or more patterns. Omit patterns to unsubscribe from all active pattern subscriptions at once.

**Syntax:** `PUNSUBSCRIBE [pattern ...]`

```redis theme={null}
PUNSUBSCRIBE user:*

# Confirmation:
# 1) "punsubscribe"
# 2) "user:*"
# 3) (integer) 0
```

**Returns:** A 3-element array for each unsubscription: `["punsubscribe", pattern, total_subscription_count]`.

***

### PUBLISH

Publishes `message` to `channel`. All clients currently subscribed to that channel (via `SUBSCRIBE`) or to a matching pattern (via `PSUBSCRIBE`) receive the message immediately.

**Syntax:** `PUBLISH channel message`

```redis theme={null}
# Terminal 2: publish a message
PUBLISH notifications "new message"
# (integer) 1  (one subscriber received it)

PUBLISH channel_with_no_subs "hello"
# (integer) 0
```

**Returns:** Integer — the number of clients that received the message.

***

## Workflow example

Here is a minimal two-terminal pub/sub flow:

```redis theme={null}
# Terminal 1: subscriber
SUBSCRIBE notifications
# Waiting for messages...

# Terminal 2: publisher (separate connection)
PUBLISH notifications "deployment complete"
# (integer) 1

# Terminal 1 now receives:
# 1) "message"
# 2) "notifications"
# 3) "deployment complete"
```

## Pattern subscription example

```redis theme={null}
# Terminal 1: subscribe to all user channels
PSUBSCRIBE user:*
# Waiting for messages...

# Terminal 2: publish to a specific user channel
PUBLISH user:42 "your order shipped"
# (integer) 1

# Terminal 1 receives a pmessage:
# 1) "pmessage"
# 2) "user:*"       <- the matched pattern
# 3) "user:42"      <- the actual channel
# 4) "your order shipped"
```

<Tip>
  Use pattern subscriptions (`PSUBSCRIBE`) when you want a single subscriber to receive events from a whole family of channels — for example `orders:*` to monitor all order lifecycle events regardless of order ID.
</Tip>

<Warning>
  If your application both publishes and subscribes, use two separate connections: one dedicated to subscriptions, and one for publishing and all other data commands. This keeps your command flow clean and avoids interleaving pub/sub confirmations with regular replies.
</Warning>