/ 
DBD-Patroni-0.01
/ DBD::Patroni

NAME

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

SYNOPSIS

use DBD::Patroni;

# Option 1: Patroni parameters in attributes hash
my $dbh = DBD::Patroni->connect(
    "dbname=mydb",
    $user, $password,
    {
        patroni_url => "http://patroni1:8008/cluster,http://patroni2:8008/cluster",
        patroni_lb  => "round_robin",  # round_robin | random | leader_only
    }
);

# Option 2: Patroni parameters in DSN string
my $dbh = DBD::Patroni->connect(
    "dbname=mydb;patroni_url=http://patroni1:8008/cluster;patroni_lb=round_robin",
    $user, $password
);

# 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 wrapper around DBD::Pg that provides automatic routing of queries to the appropriate node in a Patroni-managed PostgreSQL cluster.

Features

  • 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

Unlike standard DBI drivers, DBD::Patroni uses a direct connect method:

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

The DSN should be a PostgreSQL DSN without the dbi:Pg: prefix. All standard DBD::Pg connection parameters are supported (host, port, dbname, sslmode, etc.). See DBD::Pg for a complete list of options.

Patroni-specific parameters (patroni_url, patroni_lb, patroni_timeout) can be passed either in the DSN string or in the attributes hash. If specified in both places, the attributes hash takes precedence.

Example with Patroni parameters in DSN:

my $dbh = DBD::Patroni->connect(
    "dbname=mydb;sslmode=disable;patroni_url=http://patroni:8008/cluster",
    $user, $password
);

Example with Patroni parameters in attributes:

my $dbh = DBD::Patroni->connect(
    "dbname=mydb;sslmode=disable",
    $user, $password,
    { patroni_url => "http://patroni:8008/cluster" }
);

CONNECTION ATTRIBUTES

These attributes can be specified either in the DSN string or in the attributes hash. If specified in both places, the attributes hash takes precedence.

patroni_url (required)

Comma-separated list of Patroni REST API endpoints.

patroni_lb

Load balancing mode for replicas:

  • round_robin (default): Cycle through available replicas

  • random: Select a random replica

  • leader_only: Always use the leader (no read scaling)

patroni_timeout

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

QUERY ROUTING

Queries are automatically routed based on their type:

  • SELECT and WITH...SELECT queries go to a replica

  • INSERT, UPDATE, DELETE, CREATE, DROP, etc. go to the leader

FAILOVER

On connection failure, DBD::Patroni will:

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

If the retry also fails, the error is propagated to the caller.

SEE ALSO

DBD::Pg - The underlying PostgreSQL driver

DBI - Database independent interface for Perl

AUTHOR

Xavier Guimard

LICENSE

Same as Perl itself.