1Data::ObjectDriver(3pm)User Contributed Perl DocumentatioDnata::ObjectDriver(3pm)
2
3
4

NAME

6       Data::ObjectDriver - Simple, transparent data interface, with caching
7

SYNOPSIS

9           ## Set up your database driver code.
10           package FoodDriver;
11           sub driver {
12               Data::ObjectDriver::Driver::DBI->new(
13                   dsn      => 'dbi:mysql:dbname',
14                   username => 'username',
15                   password => 'password',
16               )
17           }
18
19           ## Set up the classes for your recipe and ingredient objects.
20           package Recipe;
21           use base qw( Data::ObjectDriver::BaseObject );
22           __PACKAGE__->install_properties({
23               columns     => [ 'recipe_id', 'title' ],
24               datasource  => 'recipe',
25               primary_key => 'recipe_id',
26               driver      => FoodDriver->driver,
27           });
28
29           package Ingredient;
30           use base qw( Data::ObjectDriver::BaseObject );
31           __PACKAGE__->install_properties({
32               columns     => [ 'ingredient_id', 'recipe_id', 'name', 'quantity' ],
33               datasource  => 'ingredient',
34               primary_key => [ 'recipe_id', 'ingredient_id' ],
35               driver      => FoodDriver->driver,
36           });
37
38           ## And now, use them!
39           my $recipe = Recipe->new;
40           $recipe->title('Banana Milkshake');
41           $recipe->save;
42
43           my $ingredient = Ingredient->new;
44           $ingredient->recipe_id($recipe->id);
45           $ingredient->name('Bananas');
46           $ingredient->quantity(5);
47           $ingredient->save;
48
49           ## Needs more bananas!
50           $ingredient->quantity(10);
51           $ingredient->save;
52
53           ## Shorthand constructor
54           my $ingredient = Ingredient->new(recipe_id=> $recipe->id,
55                                            name => 'Milk',
56                                            quantity => 2);
57

DESCRIPTION

59       Data::ObjectDriver is an object relational mapper, meaning that it maps
60       object-oriented design concepts onto a relational database.
61
62       It's inspired by, and descended from, the MT::ObjectDriver classes in
63       Six Apart's Movable Type and TypePad weblogging products. But it adds
64       in caching and partitioning layers, allowing you to spread data across
65       multiple physical databases, without your application code needing to
66       know where the data is stored.
67

METHODOLOGY

69       Data::ObjectDriver provides you with a framework for building database-
70       backed applications. It provides built-in support for object caching
71       and database partitioning, and uses a layered approach to allow
72       building very sophisticated database interfaces without a lot of code.
73
74       You can build a driver that uses any number of caching layers, plus a
75       partitioning layer, then a final layer that actually knows how to load
76       data from a backend datastore.
77
78       For example, the following code:
79
80           my $driver = Data::ObjectDriver::Driver::Cache::Memcached->new(
81                   cache    => Cache::Memcached->new(
82                                   servers => [ '127.0.0.1:11211' ],
83                               ),
84                   fallback => Data::ObjectDriver::Driver::Partition->new(
85                                   get_driver => \&get_driver,
86                               ),
87           );
88
89       creates a new driver that supports both caching (using memcached) and
90       partitioning.
91
92       It's useful to demonstrate the flow of a sample request through this
93       driver framework. The following code:
94
95           my $ingredient = Ingredient->lookup([ $recipe->recipe_id, 1 ]);
96
97       would take the following path through the Data::ObjectDriver framework:
98
99       1.  The caching layer would look up the object with the given primary
100           key in all of the specified memcached servers.
101
102           If the object was found in the cache, it would be returned
103           immediately.
104
105           If the object was not found in the cache, the caching layer would
106           fall back to the driver listed in the fallback setting: the
107           partitioning layer.
108
109       2.  The partitioning layer does not know how to look up objects by
110           itself--all it knows how to do is to give back a driver that does
111           know how to look up objects in a backend datastore.
112
113           In our example above, imagine that we're partitioning our
114           ingredient data based on the recipe that the ingredient is found
115           in. For example, all of the ingredients for a "Banana Milkshake"
116           would be found in one partition; all of the ingredients for a
117           "Chocolate Sundae" might be found in another partition.
118
119           So the partitioning layer needs to tell us which partition to look
120           in to load the ingredients for $recipe->recipe_id. If we store a
121           partition_id column along with each $recipe object, that
122           information can be loaded very easily, and the partitioning layer
123           will then instantiate a DBI driver that knows how to load an
124           ingredient from that recipe.
125
126       3.  Using the DBI driver that the partitioning layer created,
127           Data::ObjectDriver can look up the ingredient with the specified
128           primary key. It will return that key back up the chain, giving each
129           layer a chance to do something with it.
130
131       4.  The caching layer, when it receives the object loaded in Step 3,
132           will store the object in memcached.
133
134       5.  The object will be passed back to the caller. Subsequent lookups of
135           that same object will come from the cache.
136

HOW IS IT DIFFERENT?

138       Data::ObjectDriver differs from other similar frameworks (e.g.
139       Class::DBI) in a couple of ways:
140
141       ·   It has built-in support for caching.
142
143       ·   It has built-in support for data partitioning.
144
145       ·   Drivers are attached to classes, not to the application as a whole.
146
147           This is essential for partitioning, because your partition drivers
148           need to know how to load a specific class of data.
149
150           But it can also be useful for caching, because you may find that it
151           doesn't make sense to cache certain classes of data that change
152           constantly.
153
154       ·   The driver class != the base object class.
155
156           All of the object classes you declare will descend from
157           Data::ObjectDriver::BaseObject, and all of the drivers you
158           instantiate or subclass will descend from Data::ObjectDriver
159           itself.
160
161           This provides a useful distinction between your data/classes, and
162           the drivers that describe how to act on that data, meaning that an
163           object based on Data::ObjectDriver::BaseObject is not tied to any
164           particular type of driver.
165

USAGE

167   Class->lookup($id)
168       Looks up/retrieves a single object with the primary key $id, and
169       returns the object.
170
171       $id can be either a scalar or a reference to an array, in the case of a
172       class with a multiple column primary key.
173
174   Class->lookup_multi(\@ids)
175       Looks up/retrieves multiple objects with the IDs \@ids, which should be
176       a reference to an array of IDs. As in the case of lookup, an ID can be
177       either a scalar or a reference to an array.
178
179       Returns a reference to an array of objects in the same order as the IDs
180       you passed in. Any objects that could not successfully be loaded will
181       be represented in that array as an "undef" element.
182
183       So, for example, if you wanted to load 2 objects with the primary keys
184       "[ 5, 3 ]" and "[ 4, 2 ]", you'd call lookup_multi like this:
185
186           Class->lookup_multi([
187               [ 5, 3 ],
188               [ 4, 2 ],
189           ]);
190
191       And if the first object in that list could not be loaded successfully,
192       you'd get back a reference to an array like this:
193
194           [
195               undef,
196               $object
197           ]
198
199       where $object is an instance of Class.
200
201   Class->search(\%terms [, \%options ])
202       Searches for objects matching the terms %terms. In list context,
203       returns an array of matching objects; in scalar context, returns a
204       reference to a subroutine that acts as an iterator object, like so:
205
206           my $iter = Ingredient->search({ recipe_id => 5 });
207           while (my $ingredient = $iter->()) {
208               ...
209           }
210
211       $iter is blessed in Data::ObjectDriver::Iterator package, so the above
212       could also be written:
213
214           my $iter = Ingredient->search({ recipe_id => 5 });
215           while (my $ingredient = $iter->next()) {
216               ...
217           }
218
219       The keys in %terms should be column names for the database table
220       modeled by Class (and the values should be the desired values for those
221       columns).
222
223       %options can contain:
224
225       ·   sort
226
227           The name of a column to use to sort the result set.
228
229           Optional.
230
231       ·   direction
232
233           The direction in which you want to sort the result set. Must be
234           either "ascend" or "descend".
235
236           Optional.
237
238       ·   limit
239
240           The value for a LIMIT clause, to limit the size of the result set.
241
242           Optional.
243
244       ·   offset
245
246           The offset to start at when limiting the result set.
247
248           Optional.
249
250       ·   fetchonly
251
252           A reference to an array of column names to fetch in the SELECT
253           statement.
254
255           Optional; the default is to fetch the values of all of the columns.
256
257       ·   for_update
258
259           If set to a true value, the SELECT statement generated will include
260           a FOR UPDATE clause.
261
262       ·   comment
263
264           A sql comment to watermark the SQL query.
265
266       ·   window_size
267
268           Used when requesting an iterator for the search method and
269           selecting a large result set or a result set of unknown size. In
270           such a case, no LIMIT clause is assigned, which can load all
271           available objects into memory. Specifying "window_size" will load
272           objects in manageable chunks.  This will also cause any caching
273           driver to be bypassed for issuing the search itself. Objects are
274           still placed into the cache upon load.
275
276           This attribute is ignored when the search method is invoked in an
277           array context, or if a "limit" attribute is also specified that is
278           smaller than the "window_size".
279
280   Class->search(\@terms [, \%options ])
281       This is an alternative calling signature for the search method
282       documented above. When providing an array of terms, it allows for
283       constructing complex expressions that mix 'and' and 'or' clauses. For
284       example:
285
286           my $iter = Ingredient->search([ { recipe_id => 5 },
287               -or => { calories => { value => 300, op => '<' } } ]);
288           while (my $ingredient = $iter->()) {
289               ...
290           }
291
292       Supported logic operators are: '-and', '-or', '-and_not', '-or_not'.
293
294   Class->add_trigger($trigger, \&callback)
295       Adds a trigger to all objects of class Class, such that when the event
296       $trigger occurs to any of the objects, subroutine &callback is run.
297       Note that triggers will not occur for instances of subclasses of Class,
298       only of Class itself. See TRIGGERS for the available triggers.
299
300   Class->call_trigger($trigger, [@callback_params])
301       Invokes the triggers watching class Class. The parameters to send to
302       the callbacks (in addition to Class) are specified in @callback_params.
303       See TRIGGERS for the available triggers.
304
305   $obj->save
306       Saves the object $obj to the database.
307
308       If the object is not yet in the database, save will automatically
309       generate a primary key and insert the record into the database table.
310       Otherwise, it will update the existing record.
311
312       If an error occurs, save will croak.
313
314       Internally, save calls update for records that already exist in the
315       database, and insert for those that don't.
316
317   $obj->remove
318       Removes the object $obj from the database.
319
320       If an error occurs, remove will croak.
321
322   Class->remove(\%terms, \%args)
323       Removes objects found with the %terms. So it's a shortcut of:
324
325         my @obj = Class->search(\%terms, \%args);
326         for my $obj (@obj) {
327             $obj->remove;
328         }
329
330       However, when you pass "nofetch" option set to %args, it won't create
331       objects with "search", but issues DELETE SQL directly to the database.
332
333         ## issues "DELETE FROM tbl WHERE user_id = 2"
334         Class->remove({ user_id => 2 }, { nofetch => 1 });
335
336       This might be much faster and useful for tables without Primary Key,
337       but beware that in this case Triggers won't be fired because no objects
338       are instantiated.
339
340   Class->bulk_insert([col1, col2], [[d1,d2], [d1,d2]]);
341       Bulk inserts data into the underlying table.  The first argument is an
342       array reference of columns names as specified in install_properties
343
344   $obj->add_trigger($trigger, \&callback)
345       Adds a trigger to the object $obj, such that when the event $trigger
346       occurs to the object, subroutine &callback is run. See TRIGGERS for the
347       available triggers. Triggers are invoked in the order in which they are
348       added.
349
350   $obj->call_trigger($trigger, [@callback_params])
351       Invokes the triggers watching all objects of $obj's class and the
352       object $obj specifically for trigger event $trigger. The additional
353       parameters besides $obj, if any, are passed as @callback_params. See
354       TRIGGERS for the available triggers.
355

TRIGGERS

357       Data::ObjectDriver provides a trigger mechanism by which callbacks can
358       be called at certain points in the life cycle of an object. These can
359       be set on a class as a whole or individual objects (see USAGE).
360
361       Triggers can be added and called for these events:
362
363       ·   pre_save -> ($obj, $orig_obj)
364
365           Callbacks on the pre_save trigger are called when the object is
366           about to be saved to the database. For example, use this callback
367           to translate special code strings into numbers for storage in an
368           integer column in the database. Note that this hook is also called
369           when you "remove" the object.
370
371           Modifications to $obj will affect the values passed to subsequent
372           triggers and saved in the database, but not the original object on
373           which the save method was invoked.
374
375       ·   post_save -> ($obj, $orig_obj)
376
377           Callbaks on the post_save triggers are called after the object is
378           saved to the database. Use this trigger when your hook needs
379           primary key which is automatically assigned (like auto_increment
380           and sequence). Note that this hooks is NOT called when you remove
381           the object.
382
383       ·   pre_insert/post_insert/pre_update/post_update/pre_remove/post_remove
384           -> ($obj, $orig_obj)
385
386           Those triggers are fired before and after $obj is created, updated
387           and deleted.
388
389       ·   post_load -> ($obj)
390
391           Callbacks on the post_load trigger are called when an object is
392           being created from a database query, such as with the lookup and
393           search class methods. For example, use this callback to translate
394           the numbers your pre_save callback caused to be saved back into
395           string codes.
396
397           Modifications to $obj will affect the object passed to subsequent
398           triggers and returned from the loading method.
399
400           Note pre_load should only be used as a trigger on a class, as the
401           object to which the load is occurring was not previously available
402           for triggers to be added.
403
404       ·   pre_search -> ($class, $terms, $args)
405
406           Callbacks on the pre_search trigger are called when a content
407           addressed query for objects of class $class is performed with the
408           search method.  For example, use this callback to translate the
409           entry in $terms for your code string field to its appropriate
410           integer value.
411
412           Modifications to $terms and $args will affect the parameters to
413           subsequent triggers and what objects are loaded, but not the
414           original hash references used in the search query.
415
416           Note pre_search should only be used as a trigger on a class, as
417           search is never invoked on specific objects.
418
419               The return values from your callbacks are ignored.
420
421               Note that the invocation of callbacks is the responsibility of
422               the object driver. If you implement a driver that does not
423               delegate to Data::ObjectDriver::Driver::DBI, it is your
424               responsibility to invoke the appropriate callbacks with the
425               call_trigger method.
426

PROFILING

428       For performance tuning, you can turn on query profiling by setting
429       $Data::ObjectDriver::PROFILE to a true value. Or, alternatively, you
430       can set the DOD_PROFILE environment variable to a true value before
431       starting your application.
432
433       To obtain the profile statistics, get the global
434       Data::ObjectDriver::Profiler instance:
435
436           my $profiler = Data::ObjectDriver->profiler;
437
438       Then see the documentation for Data::ObjectDriver::Profiler to see the
439       methods on that class.
440
441       In some applications there are phases of execution in which no I/O
442       operations should occur, but sometimes it's difficult to tell when,
443       where, or if those I/O operations are happening.  One approach to
444       surfacing these situations is to set, either globally or locally, the
445       $Data::ObjectDriver::RESTRICT_IO flag.  If set, this will tell
446       Data::ObjectDriver to die with some context rather than executing
447       network calls for data.
448

TRANSACTIONS

450       Transactions are supported by Data::ObjectDriver's default drivers. So
451       each Driver is capable to deal with transactional state independently.
452       Additionally <Data::ObjectDriver::BaseObject> class know how to turn
453       transactions switch on for all objects.
454
455       In the case of a global transaction all drivers used during this time
456       are put in a transactional state until the end of the transaction.
457
458   Example
459           ## start a transaction
460           Data::ObjectDriver::BaseObject->begin_work;
461
462           $recipe = Recipe->new;
463           $recipe->title('lasagnes');
464           $recipe->save;
465
466           my $ingredient = Ingredient->new;
467           $ingredient->recipe_id($recipe->recipe_id);
468           $ingredient->name("more layers");
469           $ingredient->insert;
470           $ingredient->remove;
471
472           if ($you_are_sure) {
473               Data::ObjectDriver::BaseObject->commit;
474           }
475           else {
476               ## erase all trace of the above
477               Data::ObjectDriver::BaseObject->rollback;
478           }
479
480   Driver implementation
481       Drivers have to implement the following methods:
482
483       ·   begin_work to initialize a transaction
484
485       ·   rollback
486
487       ·   commit
488
489   Nested transactions
490       Are not supported and will result in warnings and the inner
491       transactions to be ignored. Be sure to end each transaction and not to
492       let et long running transaction open (i.e you should execute a rollback
493       or commit for each open begin_work).
494
495   Transactions and DBI
496       In order to make transactions work properly you have to make sure that
497       the $dbh for each DBI drivers are shared among drivers using the same
498       database (basically dsn).
499
500       One way of doing that is to define a get_dbh() subref in each DBI
501       driver to return the same dbh if the dsn and attributes of the
502       connection are identical.
503
504       The other way is to use the new configuration flag on the DBI driver
505       that has been added specifically for this purpose: "reuse_dbh".
506
507           ## example coming from the test suite
508           __PACKAGE__->install_properties({
509               columns => [ 'recipe_id', 'partition_id', 'title' ],
510               datasource => 'recipes',
511               primary_key => 'recipe_id',
512               driver => Data::ObjectDriver::Driver::Cache::Cache->new(
513                   cache => Cache::Memory->new,
514                   fallback => Data::ObjectDriver::Driver::DBI->new(
515                       dsn      => 'dbi:SQLite:dbname=global.db',
516                       reuse_dbh => 1,  ## be sure that the corresponding dbh is shared
517                   ),
518               ),
519           });
520

EXAMPLES

522   A Partitioned, Caching Driver
523           package Ingredient;
524           use strict;
525           use base qw( Data::ObjectDriver::BaseObject );
526
527           use Data::ObjectDriver::Driver::DBI;
528           use Data::ObjectDriver::Driver::Partition;
529           use Data::ObjectDriver::Driver::Cache::Cache;
530           use Cache::Memory;
531           use Carp;
532
533           our $IDs;
534
535           __PACKAGE__->install_properties({
536               columns     => [ 'ingredient_id', 'recipe_id', 'name', 'quantity', ],
537               datasource  => 'ingredients',
538               primary_key => [ 'recipe_id', 'ingredient_id' ],
539               driver      =>
540                   Data::ObjectDriver::Driver::Cache::Cache->new(
541                       cache    => Cache::Memory->new( namespace => __PACKAGE__ ),
542                       fallback =>
543                           Data::ObjectDriver::Driver::Partition->new(
544                               get_driver   => \&get_driver,
545                               pk_generator => \&generate_pk,
546                           ),
547                   ),
548           });
549
550           sub get_driver {
551               my($terms) = @_;
552               my $recipe;
553               if (ref $terms eq 'HASH') {
554                   my $recipe_id = $terms->{recipe_id}
555                       or Carp::croak("recipe_id is required");
556                   $recipe = Recipe->lookup($recipe_id);
557               } elsif (ref $terms eq 'ARRAY') {
558                   $recipe = Recipe->lookup($terms->[0]);
559               }
560               Carp::croak("Unknown recipe") unless $recipe;
561               Data::ObjectDriver::Driver::DBI->new(
562                   dsn          => 'dbi:mysql:database=cluster' . $recipe->cluster_id,
563                   username     => 'foo',
564                   pk_generator => \&generate_pk,
565               );
566           }
567
568           sub generate_pk {
569               my($obj) = @_;
570               $obj->ingredient_id(++$IDs{$obj->recipe_id});
571               1;
572           }
573
574           1;
575

SUPPORTED DATABASES

577       Data::ObjectDriver is very modular and it's not very difficult to add
578       new drivers.
579
580       ·   MySQL is well supported and has been heavily tested.
581
582       ·   PostgreSQL has been used in production and should just work, too.
583
584       ·   SQLite is supported, but YMMV depending on the version. This is the
585           backend used for the test suite.
586
587       ·   Oracle support has been added in 0.06
588

LICENSE

590       Data::ObjectDriver is free software; you may redistribute it and/or
591       modify it under the same terms as Perl itself.
592
594       Except where otherwise noted, Data::ObjectDriver is Copyright 2005-2006
595       Six Apart, cpan@sixapart.com. All rights reserved.
596
597
598
599perl v5.30.1                      2020-01-29           Data::ObjectDriver(3pm)
Impressum