DBD::Patroni(3pm)

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.