DBD::Patroni(3pm)

🌸 DBD::Patroni 💖

okay bestie, welcome to the DBD::Patroni manual page — it's part of the User Contributed Perl Documentation collection (yes, that's the man section it lives in), and it's literally the driver that makes your Postgres cluster drama-free. no cap. 🦋

---

✨ NAME ✨

DBD::Patroni — a DBI driver for PostgreSQL with Patroni cluster support 👑

🎀 SYNOPSIS 🎀

like, here's the whole vibe in code, no explanation needed yet:

use DBI;

# Standard DBI connection with patroni_url in DSN
my $dbh = DBI->connect(
    "dbi:Patroni:dbname=mydb;patroni_url=http://patroni1:8008/cluster,http://patroni2:8008/cluster",
    $user, $password
);

# Or with attributes
my $dbh = DBI->connect(
    "dbi:Patroni:dbname=mydb",
    $user, $password,
    {
        patroni_url => "http://patroni1:8008/cluster",
        patroni_lb  => "round_robin",
    }
);

# SELECT queries go to replica
my $sth = $dbh->prepare("SELECT * FROM users WHERE id = ?");
$sth->execute(1);

# INSERT/UPDATE/DELETE queries go to leader
$dbh->do("INSERT INTO users (name) VALUES (?)", undef, "John");

$dbh->disconnect;

it's giving effortless. 💅

---

💜 DESCRIPTION 💜

so DBD::Patroni is a DBI driver that wraps DBD::Pg and provides automatic routing of queries to the appropriate node in a Patroni-managed PostgreSQL cluster. that's the whole personality. it does the cluster-brain work so you don't have to. 🧚

🌈 Features 🌈

• Standard DBI interface — use DBI->connect("dbi:Patroni:...") like a normal person, no weird new API to learn 💖
• Automatic leader discovery via the Patroni REST API
• Read queries (SELECT) routed to replicas 📖
• Write queries (INSERT, UPDATE, DELETE) routed to leader ✍️
• Configurable load balancing for replicas ⚖️
• Automatic failover with retry on connection errors 🔥

---

🫶 CONNECTION 🫶

the connect call, in all its glory:

my $dbh = DBI->connect($dsn, $user, $pass, \%attr);

the DSN format is literally this:

dbi:Patroni:dbname=...;patroni_url=...;[other_pg_options]

All standard DBD::Pg connection parameters are supported. all of them. every single one. we're not gatekeeping. 💖

Patroni-specific parameters can live in the DSN or in the attributes hash. and here's the tea: the attributes hash takes precedence. so if you're duplicating stuff in both places, the attribute wins. periodt. 👑

---

💅 CONNECTION ATTRIBUTES 💅

• patroni_url (required) — comma-separated list of Patroni REST API endpoints. no patroni_url, no connection, that's the rules bestie 🚨
• patroni_lb — load balancing mode. the options are "round_robin" (which is the default, so if you do nothing this is what you get), "random", or "leader_only".
• patroni_timeout — HTTP timeout in seconds for Patroni API calls. Default: 3 ⏱️

---

⭐ QUERY ROUTING ⭐

this is the part where it just knows where your query should go:

• SELECT and WITH...SELECT go to replica 🌸
• All other queries go to leader 👑

---

💀 FAILOVER 💀

when a connection fails, DBD::Patroni goes into main character mode and does this:

1. Query Patroni API to discover current leader 🔍
2. Reconnect to new leader/replica 🔁
3. Retry the failed operation 💪

---

👀 SEE ALSO 👀

• DBD::Pg
• DBI

---

🎀 AUTHOR 🎀

Xavier Guimard — icon, legend, the moment 💖

📜 LICENSE 📜

Same as Perl itself.

---

and that's the whole page bestie!! 🦋✨ this was the manual page rendered by perl v5.40.1, dated 2026-02-20, filed under DBD::Patroni(3pm) in the User Contributed Perl Documentation. go slay your cluster, ily 🫶💅