Realtime Publisher/Subscriber service.

Getting started

You start Phoenix.PubSub directly in your supervision tree:

{Phoenix.PubSub, name: :my_pubsub}

You can now use the functions in this module to subscribe and broadcast messages:

iex> alias Phoenix.PubSub
iex> PubSub.subscribe(:my_pubsub, "user:123")
:ok
iex> Process.info(self(), :messages)
{:messages, []}
iex> PubSub.broadcast(:my_pubsub, "user:123", {:user_update, %{id: 123, name: "Shane"}})
:ok
iex> Process.info(self(), :messages)
{:messages, [{:user_update, %{id: 123, name: "Shane"}}]}

Adapters

Phoenix PubSub was designed to be flexible and support multiple backends. There are two officially supported backends:

• Phoenix.PubSub.PG2 - the default adapter that ships as part of Phoenix.PubSub. It uses Distributed Elixir, directly exchanging notifications between servers. It supports a :pool_size option to be given alongside the name, defaults to 1. Note the :pool_size must be the same throughout the cluster, therefore don't configure the pool size based on System.schedulers_online/0, especially if you are using machines with different specs.

• Phoenix.PubSub.Redis - uses Redis to exchange data between servers. It requires the :phoenix_pubsub_redis dependency.

See Phoenix.PubSub.Adapter to implement a custom adapter.

Custom dispatching

Phoenix.PubSub allows developers to perform custom dispatching by passing a dispatcher module which is responsible for local message deliveries.

The dispatcher must be available on all nodes running the PubSub system. The dispatch/3 function of the given module will be invoked with the subscriptions entries, the broadcaster identifier (either a pid or :none), and the message to broadcast.

You may want to use the dispatcher to perform special delivery for certain subscriptions. This can be done by passing the :metadata option during subscriptions. For instance, Phoenix Channels use a custom value to provide "fastlaning", allowing messages broadcast to thousands or even millions of users to be encoded once and written directly to sockets instead of being encoded per channel.

Safe pool size migration (when using Phoenix.PubSub.PG2 adapter)

When you need to change the pool size in a running cluster, you can use the broadcast_pool_size option to ensure no messages are lost during deployment. This is particularly important when increasing the pool size.

Here's how to safely increase the pool size from 1 to 2:

1. Initial state - Current configuration with pool_size: 1:

   {Phoenix.PubSub, name: :my_pubsub, pool_size: 1}

graph TD
    subgraph "Initial State"
        subgraph "Node 1"
            A1[Shard 1<br/>Broadcast & Receive]
        end
        subgraph "Node 2"
            B1[Shard 1<br/>Broadcast & Receive]
        end
        A1 <--> B1
    end

2. First deployment - Set the new pool size but keep broadcasting on the old size:

   {Phoenix.PubSub, name: :my_pubsub, pool_size: 2, broadcast_pool_size: 1}

graph TD
    subgraph "First Deployment"
        subgraph "Node 1"
            A1[Shard 1<br/>Broadcast & Receive]
            A2[Shard 2<br/>Broadcast & Receive]
        end
        subgraph "Node 2"
            B1[Shard 1<br/>Broadcast & Receive]
            B2[Shard 2<br/>Receive Only]
        end
        A1 <--> B1
        A2 --> B2
    end

3. Final deployment - All nodes running with new pool size:

   {Phoenix.PubSub, name: :my_pubsub, pool_size: 2}

graph TD
    subgraph "Final State"
        subgraph "Node 1"
            A1[Shard 1<br/>Broadcast & Receive]
            A2[Shard 2<br/>Broadcast & Receive]
        end
        subgraph "Node 2"
            B1[Shard 1<br/>Broadcast & Receive]
            B2[Shard 2<br/>Broadcast & Receive]
        end
        A1 <--> B1
        A2 <--> B2
    end

This two-step process ensures that:

• All nodes can receive messages from both old and new pool sizes
• No messages are lost during the transition
• The cluster remains fully functional throughout the deployment

To decrease the pool size, follow the same process in reverse order.