1Data::ObjectDriver(3pm)User Contributed Perl DocumentatioDnata::ObjectDriver(3pm)
2
6 Data::ObjectDriver - Simple, transparent data interface, with caching
7
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 ## 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 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 ## And now, use them!
39 my $recipe = Recipe->new;
40 $recipe->title('Banana Milkshake');
41 $recipe->save;
42 my $ingredient = Ingredient->new;
44 $ingredient->recipe_id($recipe->id);
45 $ingredient->name('Bananas');
46 $ingredient->quantity(5);
47 $ingredient->save;
48 ## Needs more bananas!
50 $ingredient->quantity(10);
51 $ingredient->save;
52 ## Shorthand constructor
54 my $ingredient = Ingredient->new(recipe_id=> $recipe->id,
55 name => 'Milk',
56 quantity => 2);
57
59 Data::ObjectDriver is an object relational mapper, meaning that it maps
60 object-oriented design concepts onto a relational database.
61 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
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 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 For example, the following code:
79 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 creates a new driver that supports both caching (using memcached) and
90 partitioning.
91 It's useful to demonstrate the flow of a sample request through this
93 driver framework. The following code:
94 my $ingredient = Ingredient->lookup([ $recipe->recipe_id, 1 ]);
96 would take the following path through the Data::ObjectDriver framework:
98 1. The caching layer would look up the object with the given primary
100 key in all of the specified memcached servers.
101 If the object was found in the cache, it would be returned
103 immediately.
104 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 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 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 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 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 4. The caching layer, when it receives the object loaded in Step 3,
132 will store the object in memcached.
133 5. The object will be passed back to the caller. Subsequent lookups of
135 that same object will come from the cache.
136
138 Data::ObjectDriver differs from other similar frameworks (e.g.
139 Class::DBI) in a couple of ways:
140 • It has built-in support for caching.
142 • It has built-in support for data partitioning.
144 • Drivers are attached to classes, not to the application as a whole.
146 This is essential for partitioning, because your partition drivers
148 need to know how to load a specific class of data.
149 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 • The driver class != the base object class.
155 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 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
167 Class->lookup($id)
168 Looks up/retrieves a single object with the primary key $id, and
169 returns the object.
170 $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 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 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 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 Class->lookup_multi([
187 [ 5, 3 ],
188 [ 4, 2 ],
189 ]);
190 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 [
195 undef,
196 $object
197 ]
198 where $object is an instance of Class.
200 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 my $iter = Ingredient->search({ recipe_id => 5 });
207 while (my $ingredient = $iter->()) {
208 ...
209 }
210 $iter is blessed in Data::ObjectDriver::Iterator package, so the above
212 could also be written:
213 my $iter = Ingredient->search({ recipe_id => 5 });
215 while (my $ingredient = $iter->next()) {
216 ...
217 }
218 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 %options can contain:
224 • sort
226 The name of a column to use to sort the result set.
228 Optional.
230 • direction
232 The direction in which you want to sort the result set. Must be
234 either "ascend" or "descend".
235 Optional.
237 • limit
239 The value for a LIMIT clause, to limit the size of the result set.
241 Optional.
243 • offset
245 The offset to start at when limiting the result set.
247 Optional.
249 • fetchonly
251 A reference to an array of column names to fetch in the SELECT
253 statement.
254 Optional; the default is to fetch the values of all of the columns.
256 • for_update
258 If set to a true value, the SELECT statement generated will include
260 a FOR UPDATE clause.
261 • comment
263 A sql comment to watermark the SQL query.
265 • window_size
267 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 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 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 my $iter = Ingredient->search([ { recipe_id => 5 },
287 -or => { calories => { value => 300, op => '<' } } ]);
288 while (my $ingredient = $iter->()) {
289 ...
290 }
291 Supported logic operators are: '-and', '-or', '-and_not', '-or_not'.
293 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 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 $obj->save
306 Saves the object $obj to the database.
307 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 If an error occurs, save will croak.
313 Internally, save calls update for records that already exist in the
315 database, and insert for those that don't.
316 $obj->remove
318 Removes the object $obj from the database.
319 If an error occurs, remove will croak.
321 Class->remove(\%terms, \%args)
323 Removes objects found with the %terms. So it's a shortcut of:
324 my @obj = Class->search(\%terms, \%args);
326 for my $obj (@obj) {
327 $obj->remove;
328 }
329 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 ## issues "DELETE FROM tbl WHERE user_id = 2"
334 Class->remove({ user_id => 2 }, { nofetch => 1 });
335 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 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 $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 $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
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 Triggers can be added and called for these events:
362 • pre_save -> ($obj, $orig_obj)
364 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 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 • post_save -> ($obj, $orig_obj)
376 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 • pre_insert/post_insert/pre_update/post_update/pre_remove/post_remove
384 -> ($obj, $orig_obj)
385 Those triggers are fired before and after $obj is created, updated
387 and deleted.
388 • post_load -> ($obj)
390 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 Modifications to $obj will affect the object passed to subsequent
398 triggers and returned from the loading method.
399 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 • pre_search -> ($class, $terms, $args)
405 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 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 Note pre_search should only be used as a trigger on a class, as
417 search is never invoked on specific objects.
418 The return values from your callbacks are ignored.
420 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
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 To obtain the profile statistics, get the global
434 Data::ObjectDriver::Profiler instance:
435 my $profiler = Data::ObjectDriver->profiler;
437 Then see the documentation for Data::ObjectDriver::Profiler to see the
439 methods on that class.
440 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
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 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 Example
459 ## start a transaction
460 Data::ObjectDriver::BaseObject->begin_work;
461 $recipe = Recipe->new;
463 $recipe->title('lasagnes');
464 $recipe->save;
465 my $ingredient = Ingredient->new;
467 $ingredient->recipe_id($recipe->recipe_id);
468 $ingredient->name("more layers");
469 $ingredient->insert;
470 $ingredient->remove;
471 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 Driver implementation
481 Drivers have to implement the following methods:
482 • begin_work to initialize a transaction
484 • rollback
486 • commit
488 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 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 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 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 ## 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
522 A Partitioned, Caching Driver
523 package Ingredient;
524 use strict;
525 use base qw( Data::ObjectDriver::BaseObject );
526 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 our $IDs;
534 __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 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 sub generate_pk {
569 my($obj) = @_;
570 $obj->ingredient_id(++$IDs{$obj->recipe_id});
571 1;
572 }
573 1;
575
577 As of version 0.21, Data::ObjectDriver resets internal database handles
578 after fork(2) is called, but only if POSIX::AtFork module is installed.
579 Otherwise, Data::ObjectDriver is not fork-safe.
580
582 Data::ObjectDriver is very modular and it's not very difficult to add
583 new drivers.
584 • MySQL is well supported and has been heavily tested.
586 • PostgreSQL has been used in production and should just work, too.
588 • SQLite is supported, but YMMV depending on the version. This is the
590 backend used for the test suite.
591 • Oracle support has been added in 0.06
593
595 Data::ObjectDriver is free software; you may redistribute it and/or
596 modify it under the same terms as Perl itself.
597
599 Except where otherwise noted, Data::ObjectDriver is Copyright 2005-2006
600 Six Apart, cpan@sixapart.com. All rights reserved.
601perl v5.38.0 2023-07-20 Data::ObjectDriver(3pm)