Data::ObjectDriver::Driver::Partition - base class for partitioned object drivers

       Except where otherwise noted, Data::ObjectDriver is Copyright 2005-2006 Six Apart, cpan@sixapart.com. All
       rights reserved.

perl v5.40.1                                       2025-04-19              Data::ObjectDr...iver::Partition(3pm)

       There are no known bugs in this module.

Data::ObjectDriver::Driver::Partition provides the basic structure for partitioning objects into
       different databases. Using partitions, you can horizontally scale your application by using different
       database servers to hold sets of data.

       To partition data, you need a certain criteria to determine which partition data goes in. Partition
       drivers use a "get_driver" function to find the database driver for the correct partition, given either
       the arguments to a search() or the object's primary key for a lookup(), update(), etc where the key is
       known.

       No errors are created by Data::ObjectDriver::Driver::Partition itself.  Errors may come from  a  specific
       partitioning subclass or the driver for a particular database.

Data::ObjectDriver  is  free  software;  you may redistribute it and/or modify it under the same terms as
       Perl itself.

       Data::ObjectDriver::Driver::Partition - base class for partitioned object drivers

Data::ObjectDriver::Driver::SimplePartition

       While you can use any stable, predictable method of selecting the partition for an object, the most
       flexible way is to keep an unpartitioned table that maps object keys to their partitions. You can then
       look up the appropriate record in your get_driver method to find the partition.

       For many applications, you can partition several classes of data based on the ID of the user account that
       "owns" them. In this case, you would include the user ID as the first part of a complex primary key.

       Because multiple objects can use the same partitioning scheme, often
       Data::ObjectDriver::Driver::Partition is subclassed to define the "get_driver" function once and
       automatically specify it to the Data::ObjectDriver::Driver::Partition constructor.

       Note these practices are codified into the Data::ObjectDriver::Driver::SimplePartition class.

           package SomeObject;

           __PACKAGE__->install_properties({
               ...
               primary_key => 'id',
               driver      => Data::ObjectDriver::Driver::Partition->new(get_driver => \&find_partition),
           });

           # Say we have a list of 5 arrayrefs of the DBI driver information.
           my @DBI_INFO;

           sub find_partition {
               my ($part_key, $args) = @_;

               my $id;

               if (ref $terms && ref $terms eq 'HASH') {
                   # This is a search($terms, $args) call.
                   my $terms = $part_key;
                   $id = $terms->{id}
                       or croak "Can't determine partition from a search() with no id field";
               }
               else {
                   # This is a lookup($id) or some method invoked on an object where we know the ID.
                   my $id = $part_key;
               }

               # "ID modulo N" is not a good partitioning strategy, but serves as an example.
               my $partition = $id % 5;
               return Data::ObjectDriver::Driver::DBI->new( @{ $DBI_INFO[$partition] } );
           }

"Data::ObjectDriver::Driver::Partition->new(%params)"
       Creates a new partitioning driver. The required members of %params are:

       •   "get_driver"

           A  reference  to  a  function  to be used to retrieve for a given object or set of search terms. Your
           function is invoked as either:

           •   "get_driver(\%terms, \%args)"

               Return a driver based on the given search() parameters.

           •   get_driver($id)

               Return a driver based on the given object ID. Note that $id may be an arrayref, if the class  was
               defined with a complex primary key.

       •   "pk_generator"

           A reference to a function that, given a data object, generates a primary key for it. This is the same
           "pk_generator" given to "Data::ObjectDriver"'s constructor.

   "$driver->search($class,$terms,$args)""$driver->lookup($class,$id)""$driver->lookup_multi($class,@ids)""$driver->exists($obj)""$driver->insert($obj)""$driver->update($obj)""$driver->remove($obj)""$driver->fetch_data($what)"
       Performs  the  named  action,  by  passing  these  methods  through to the appropriate database driver as
       determined by $driver's "get_driver" function.