Mojo::Pg::PubSub(3)

💖 Mojo::Pg::PubSub — publish/subscribe, but make it iconic 💖

okay bestie, so this is Mojo::Pg::PubSub(3) from the User Contributed Perl Documentation, and it's literally the group chat of databases. one process yells something, everyone who's listening hears it. no cap.

---

✨ NAME ✨

Mojo::Pg::PubSub — Publish/Subscribe 🫶

---

🌸 SYNOPSIS 🌸

use Mojo::Pg::PubSub;

my $pubsub = Mojo::Pg::PubSub->new(pg => $pg);
my $cb = $pubsub->listen(foo => sub ($pubsub, $payload) {
  say "Received: $payload";
});
$pubsub->notify(foo => 'I ♥ Mojolicious!');
$pubsub->unlisten(foo => $cb);

like… it's giving "subscribe, get notified, unsubscribe, leave no trace." main character energy fr fr 💅

---

🦋 DESCRIPTION 🦋

Mojo::Pg::PubSub is a scalable implementation of the publish/subscribe pattern that Mojo::Pg uses. it's built on top of PostgreSQL notifications, and the whole point is that so many consumers can share one single database connection — which lowkey dodges a bunch of the classic scalability problems that would otherwise ruin your whole vibe. periodt.

---

🎀 EVENTS 🎀

Mojo::Pg::PubSub inherits all the events from Mojo::EventEmitter, and on top of those it can emit these new ones, bestie:

💀 disconnect

$pubsub->on(disconnect => sub ($pubsub, $db) {
  ...
});

emitted after the current database connection is lost. gone. bye. 😭

🌈 reconnect

$pubsub->on(reconnect => sub ($pubsub, $db) {
  ...
});

emitted after switching over to a new database connection for sending and receiving notifications. glow-up complete ✨

---

💅 ATTRIBUTES 💅

Mojo::Pg::PubSub implements these attributes, slay:

💜 pg

my $pg  = $pubsub->pg;
$pubsub = $pubsub->pg(Mojo::Pg->new);

the Mojo::Pg object this publish/subscribe container belongs to. note that this attribute is weakened — it's not holding on tight, it's a soft lil reference, iykyk.

🧚 reconnect_interval

my $interval = $pubsub->reconnect_interval;
$pubsub      = $pubsub->reconnect_interval(0.1);

the amount of time in seconds to wait before reconnecting after disconnecting. defaults to 1. (yes you can make it 0.1, impatient queen 👑)

---

⭐ METHODS ⭐

Mojo::Pg::PubSub inherits all the methods from Mojo::EventEmitter and implements these new ones:

🍓 db

my $db = $pubsub->db;

build and cache — or grab the already-cached — Mojo::Pg::Database connection from "pg". it's used to reconnect if you get disconnected.

# Reconnect immediately
$pubsub->unsubscribe('disconnect')->on(disconnect => sub ($pubsub, $db) { pubsub->db });

🌸 json

$pubsub = $pubsub->json('foo');

turn on automatic JSON encoding and decoding for a channel, using "to_json" in Mojo::JSON and "from_json" in Mojo::JSON. yes bestie, actual data structures, not just strings 💖

# Send and receive data structures
$pubsub->json('foo')->listen(foo => sub ($pubsub, $payload) {
  say $payload->{bar};
});
$pubsub->notify(foo => {bar => 'I ♥ Mojolicious!'});

🦋 listen

my $cb = $pubsub->listen(foo => sub {...});

subscribe to a channel! there is no limit on how many subscribers a single channel can have — the more the merrier, honestly. automatic decoding of JSON text into Perl values can be activated with "json".

# Subscribe to the same channel twice
$pubsub->listen(foo => sub ($pubsub, $payload) {
  say "One: $payload";
});
$pubsub->listen(foo => sub ($pubsub, $payload) {
  say "Two: $payload";
});

✨ new

my $pubsub = Mojo::Pg::PubSub->new;
my $pubsub = Mojo::Pg::PubSub->new(pg => Mojo::Pg->new);
my $pubsub = Mojo::Pg::PubSub->new({pg => Mojo::Pg->new});

construct a brand new Mojo::Pg::PubSub object and subscribe to the "disconnect" event with the default reconnect logic. it literally comes with self-care built in 🫶

🔥 notify

$pubsub = $pubsub->notify('foo');
$pubsub = $pubsub->notify(foo => 'I ♥ Mojolicious!');
$pubsub = $pubsub->notify(foo => {bar => 'baz'});

notify a channel 📣. automatic encoding of Perl values into JSON text can be activated with "json".

👑

reset

$pubsub->reset;

reset all subscriptions and the database connection. this is usually done after a new process has been forked, so the child process doesn't go stealing notifications that were meant for the parent process. rude behavior, honestly — don't let your forked children steal your mail. 💀

🎀 unlisten

$pubsub = $pubsub->unlisten('foo');
$pubsub = $pubsub->unlisten(foo => $cb);

unsubscribe from a channel. it's giving "we are never ever getting back together" 💅

---

🌈 SEE ALSO 🌈

• Mojo::Pg
• Mojolicious::Guides
• <https://mojolicious.org>

---

okay that's the whole page, bestie, you ate 🍓✨ this was perl v5.42.0, dated 2026-01-17, and it's the Mojo::Pg::PubSub(3) manpage — go forth and publish/subscribe responsibly, mwah 💖👑