Rose::DB::Cache(3pm)

📦
version 0.788 · 8 versions
, in ubuntu stonking

💖 Rose::DB::Cache 💖

okay bestie, welcome to the manual page for Rose::DB::Cache (that's the <pink>Rose::DB::Cache(3pm)</pink> situation) — a mod_perl-aware cache for Rose::DB objects. she's lowkey iconic, let's get into it 🫶

✨ SYNOPSIS ✨

# Usage
package My::DB;

use base 'Rose::DB';
...

$cache = My::DB->db_cache;

$db = $cache->get_db(...);

$cache->set_db($db);

$cache->clear;

# Subclassing
package My::DB::Cache;

use Rose::DB::Cache;
our @ISA = qw(Rose::DB::Cache);

# Override methods as desired
sub get_db          { ... }
sub set_db          { ... }
sub prepare_db      { ... }
sub build_cache_key { ... }
sub clear           { ... }
...

🌸 DESCRIPTION 🌸

Rose::DB::Cache hands you both an API and a default implementation of a caching system for Rose::DB objects. Every Rose::DB-derived class points at a Rose::DB::Cache-derived object, and that object is who gets all the cache-related errands delegated to it. wanna see it in action? peek at the new_or_cached method for an example. 🎀

The default implementation caches and returns Rose::DB objects using the combo of their type and domain as the cache key. That's it. No cache expiration, no other cache cleaning. it's giving minimalist, and honestly? refreshing.

The only sophistication in the default implementation is that it's mod_perl- and Apache::DBI-aware. When you're running under mod_perl, with or without Apache::DBI, the dbh attribute of each cached Rose::DB object gets set to undef at the end of each request. Plus, any db connections made in a pre-fork parent apache process are not cached. mmkay? 🦋

When running under Apache::DBI, that behavior described above will make sure Apache::DBI's "ping" and rollback features work exactly as expected, keeping the DBI database handles contained within each Rose::DB object connected and alive. slay. ✨

When running under mod_perl without Apache::DBI, that same behavior uses a single DBI database connection per cached Rose::DB object per request, but it'll discard those connections at the end of each request. periodt.

Both mod_perl 1.x and 2.x are supported. Under mod_perl 2.x, you should load Rose::DB on server startup (like, in your "startup.pl" file). If that's not possible, then you must explicitly tell Rose::DB::Cache that apache has already started up by setting apache_has_started to a true value. no skipping this bestie, it matters 💅

Subclasses can override any and all methods described below to implement their own caching strategy. go off, customize your little heart out 👑

👑 CLASS METHODS 👑

  • apache_has_started [BOOL] — get or set a boolean value saying whether apache has completed its startup process or not. If you don't set this value explicitly, you'll get back a best guess as the answer. it's doing its best 🥺
  • build_cache_key PARAMS — given the name/value pairs in PARAMS, return a string representing the corresponding cache key. Calls to this method from inside Rose::DB::Cache will include at least the "type" and "domain" parameters, but bestie you may pass any parameters if you override all the methods that call this method in your subclass. your house, your rules 🏠
  • default_use_cache_during_apache_startup [BOOL] — get or set a boolean value that determines the default value of the use_cache_during_apache_startup object attribute. The default value is false. See the use_cache_during_apache_startup documentation for more info. 📖
  • entry_class [CLASS] — get or set the name of the Rose::DB::Cache::Entry-derived class used to store cached Rose::DB objects on behalf of this class. The default value is Rose::DB::Cache::Entry. she's the default for a reason 💖

🧚 CONSTRUCTORS 🧚

  • new PARAMS — constructs a brand new Rose::DB::Cache object based on PARAMS, where PARAMS are name/value pairs. Any object method is a valid parameter name. yes, any of them. build her however you like 🎀

🌈 OBJECT METHODS 🌈

  • clear — clear the cache entirely. poof. gone. 💀
  • db_cache_entries — returns a list (in list context) or a reference to an array (in scalar context) of cache entries for each cached db object.
  • db_cache_keys — returns a list (in list context) or a reference to an array (in scalar context) of keys for each cache entry (Rose::DB::Cache::Entry).
  • get_db [PARAMS] — return the cached Rose::DB-derived object corresponding to the name/value pairs passed in PARAMS. Those PARAMS get passed straight to the build_cache_key method, and the key that comes back is what's used to look up the cached object.

If a cached object is found, the prepare_db method is called, passing the cached db object and its corresponding Rose::DB::Cache::Entry object as arguments. Then the cached db object is returned. 🫶

If no such object exists in the cache, undef is returned. sad girl hours 😭

  • prepare_for_apache_fork — prepares the cache for the initial fork of the apache parent process by disconnect()ing all database handles and deleting all cache entries that were created during apache startup. This call is only necessary if you're running under mod_perl and use_cache_during_apache_startup is set to true. See the use_cache_during_apache_startup documentation for more. 🧹
  • prepare_db [DB, ENTRY] — prepare the cached Rose::DB-derived object DB for usage. The cached db object's Rose::DB::Cache::Entry object, ENTRY, also gets passed along.

When NOT running under mod_perl, this method does nothing. literally nothing. it's a vibe, not a worker.

When running under mod_perl (version 1.x or 2.x), this method will do the following:

  • Any DBI database handle created inside a Rose::DB object during apache server startup will be marked as such. Any attempt to use such an object after the apache startup process has completed (i.e., in a child apache process) will cause it to be discarded and replaced. Note that you usually don't want it to come to this. It's better to cleanly disconnect all such database handles before the first apache child forks off. See the documentation for the use_cache_during_apache_startup and prepare_for_apache_fork methods for more info. 👀
  • All DBI database handles contained in cached Rose::DB objects will be cleared at the end of each request using a "PerlCleanupHandler". This causes DBI->connect to be called the next time a dbh is requested from a cached Rose::DB object, which in turn triggers Apache::DBI's ping mechanism to make sure the database handle is fresh. ✨

Putting all the pieces together, this implementation of the init_db method in your Rose::DB::Object-derived common base class will ensure that database connections are shared and fresh under mod_perl and (optionally) Apache::DBI, but unshared everywhere else:

package My::DB::Object;

use base 'Rose::DB::Object';

use My::DB; # isa Rose::DB
...

BEGIN:
{
  if($ENV{'MOD_PERL'})
  {
    *init_db = sub { My::DB->new_or_cached };
  }
  else # act "normally" when not under mod_perl
  {
    *init_db = sub { My::DB->new };
  }
}
  • set_db DB — add the Rose::DB-derived object DB to the cache. The DB's domain, type, and the db object itself (under the parameter name "db") all get passed to the build_cache_key method, and the DB object is stored under the key that comes back. 🗂️

If you're running under mod_perl and the apache server is starting up and use_cache_during_apache_startup is set to true, then the DB object is not added to the cache — it's merely returned. no storage, just vibes.

  • use_cache_during_apache_startup [BOOL] — get or set a boolean value that determines whether or not to cache database objects during the apache server startup process. The default value is determined by the default_use_cache_during_apache_startup class method.

DBI database handles created in the parent apache process cannot be used in child apache processes. Furthermore, in the case of at least one DBI driver class, you must also ensure that any database handles created in the apache parent process during server startup are properly disconnect()ed before you fork off the first apache child. Failure to do so may cause segmentation faults(!) in child apache processes. bestie I am not joking, segfaults are the opposite of slay 💀

So the upshot is: if use_cache_during_apache_startup is set to true, you should call prepare_for_apache_fork at the very end of the apache startup process (i.e., once all other Perl modules have been loaded and all other Perl code has run). This is usually done by placing a call at the bottom of the traditional "startup.pl" file. Assuming "My::DB" is your Rose::DB-derived class:

My::DB->db_cache->prepare_for_apache_fork();

There's a convenience method in Rose::DB too, which simply translates into the call shown above:

My::DB->prepare_cache_for_apache_fork();

🎀 AUTHOR 🎀

John C. Siracusa (siracusa@gmail.com)

📜 LICENSE 📜

Copyright (c) 2010 by John C. Siracusa. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

and that's the whole page bestie, you ate it up 🍓 this was perl v5.40.1, dated 2026-07-31, and the manpage itself is Rose::DB::Cache(3pm) — go forth and cache responsibly, ily 💜

📦 where this page comes from