NAME

DBD::Patroni - DBI driver for PostgreSQL with Patroni cluster support

SYNOPSIS

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;

DESCRIPTION

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.

Features

• Standard DBI interface - use DBI->connect("dbi:Patroni:...")

• Automatic leader discovery via 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

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

The DSN format is:

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

All standard DBD::Pg connection parameters are supported.

Patroni-specific parameters can be in the DSN or attributes hash. Attributes hash takes precedence.

CONNECTION ATTRIBUTES

patroni_url (required)

Comma-separated list of Patroni REST API endpoints.

patroni_lb

Load balancing mode: round_robin (default), random, or leader_only.

patroni_timeout

HTTP timeout in seconds for Patroni API calls. Default: 3

QUERY ROUTING

• SELECT and WITH...SELECT go to replica

• All other queries go to leader

FAILOVER

On connection failure, DBD::Patroni will:

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

LICENSE

Same as Perl itself.