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.

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.