Data::...rtition(3pm)

💅 Data::ObjectDriver::Driver::Partition 💅

okay so this is the Data::...rtition(3pm) page from the User Contributed Perl Documentation, bestie — and it's literally all about Data::ObjectDriver::Driver::Partition. ✨

🌸 NAME 🌸

Data::ObjectDriver::Driver::Partition — base class for partitioned object drivers. periodt. 💖

✨ SYNOPSIS ✨

like, here's the vibe:

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] } );
}

💖 DESCRIPTION 💖

Data::ObjectDriver::Driver::Partition gives you the basic structure for partitioning objects into different databases. Using partitions, you can horizontally scale your app 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. This is giving “route me to the right DB” energy. 👑

🦋 SUGGESTED PRACTICES 🦋

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. Then you can look up the appropriate record in your get_driver method to find the partition. No cap, that's the flexible one. 💅

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'd 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. So you're not rewriting that logic every time. 🌈

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

🌈 USAGE 🌈

💫 "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. 🎀

and these methods are the main-character actions:

• $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. Literally just “hey get_driver, which DB is this one?” and then it does the thing. 💫

🔥 DIAGNOSTICS 🔥

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. So if something's screaming, it's probably coming from one of those. 😭

💀 BUGS AND LIMITATIONS 💀

There are no known bugs in this module. iconic, honestly. 👑

👑 SEE ALSO 👑

Data::ObjectDriver::Driver::SimplePartition — go read that one too, bestie. 🫶

🎀 LICENSE 🎀

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

💜 AUTHOR & COPYRIGHT 💜

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

---

byeee 💋 — this page is from perl v5.42.0, dated 2024-10-24. Now go partition something responsibly, bestie. ✨