view release on metacpan or  search on metacpan

lib/DBD/Patroni.pm  view on Meta::CPAN

        "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;

=head1 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.

=head2 Features

=over 4

=item * Standard DBI interface - use DBI->connect("dbi:Patroni:...")

=item * Automatic leader discovery via Patroni REST API

=item * Read queries (SELECT) routed to replicas

=item * Write queries (INSERT, UPDATE, DELETE) routed to leader

=item * Configurable load balancing for replicas

=item * Automatic failover with retry on connection errors

=back

=head1 CONNECTION

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

The DSN format is:

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

All standard L<DBD::Pg> connection parameters are supported.

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

=head1 CONNECTION ATTRIBUTES

=over 4

=item patroni_url (required)

Comma-separated list of Patroni REST API endpoints.

=item patroni_lb

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

=item patroni_timeout

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

=back

=head1 QUERY ROUTING

=over 4

=item * B<SELECT> and B<WITH...SELECT> go to replica

=item * All other queries go to leader

=back

=head1 FAILOVER

On connection failure, DBD::Patroni will:

=over 4

=item 1. Query Patroni API to discover current leader

=item 2. Reconnect to new leader/replica

=item 3. Retry the failed operation

=back

=head1 SEE ALSO

L<DBD::Pg>, L<DBI>

=head1 AUTHOR

Xavier Guimard

=head1 LICENSE

Same as Perl itself.

=cut