Rose::...torial(3pm)

💖 NAME 💖

Rose::DB::Tutorial — Best practices for using Rose::DB.

This is the Rose::DB::Tutorial(3pm) page from the User Contributed Perl Documentation, bestie, and it's about to be your little guide to doing Rose::DB the robust, maintainable way. ✨

🌸 INTRODUCTION 🌸

Okay so this tutorial is all about the "best practices" for using Rose::DB in the most robust, maintainable manner. It does not replace the actual documentation, though. The actual Rose::DB documentation is still essential, and it contains some good examples of its own. No cap. 💅

In particular, you should read the description section of the Rose::DB documentation if you have not done so already. It describes the features and philosophy of Rose::DB. That information will not be repeated here. So go read it, bestie, iykyk. 🦋

fr fr, do not skip the real docs. This tutorial is the vibe, not the whole entire manual. 😭

---

🎀 CONVENTIONS 🎀

The examples in this tutorial will use the fictional My:: namespace prefix. Your code should use whatever namespace you deem appropriate. Usually, it will be more akin to MyCorp::MyProject:: (i.e., your corporation, organization, and/or project). I've chosen to use My:: simply because it's shorter, and will help this tutorial stay within an 80-column width. Lowkey iconic of me, honestly. 👑

For the sake of brevity, the use strict directive and associated my declarations have been omitted from the example code. Needless to say, you should always use strict in your actual code. Always. Like, this is not the place to get silly. 😤

🫶 seriously bestie: use strict in real code. The tutorial examples are just skipping it to keep things cute and short.

Similarly, the traditional 1; true value used at the end of each .pm file has been omitted from the examples. Don't forget to add this to the end of your actual Perl module files. 💖

🎀 TUTORIAL 🎀

💖 Creating a subclass 💖

okay bestie listen up, this is literally step one. if you're doing anything with Rose::DB that isn't a throwaway script you're gonna delete in five minutes, make a lil subclass. it's a whole thing and it matters, because Rose::DB is holding a lot of class data. if you use Rose::DB directly you're out here reading and writing the same data as any other badly-behaved code that also uses Rose::DB directly. messy. not slay.

specifically: the registry that holds all the info for each data source is class data, and by default it's inherited from — aka shared with — the base class. so you make a subclass and boom, you get your own private data source registry. main character energy, honestly.

so here's our starter Rose::DB subclass:

# File: My/DB.pm
package My::DB;

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

# Use a private registry for this class
__PACKAGE__->use_private_registry;

---

🦋 Designing your namespace 🦋

so like the Rose::DB docs say, Rose::DB gives you a two-level namespace for data sources, made up of a "domain" and a "type." both are just arbitrary strings, so you have SO much freedom to chop up that namespace however you want. you can even make sub-domains and sub-types inside each string using delimiter characters — like "::" the way Perl's package namespace does. cute.

but let's back up for a sec. the simplest possible case is you have exactly one data source and therefore genuinely no need for a namespace at all. if that's you, skip ahead to the next section. bye bestie 💅

in the common case, it's usually enough to just use simple words for both type and domain. like the name "domain" implies, this value usually represents the environment or surroundings. for example, a typical server app might use domains named "development", "qa", "staging", and "production".

the "type" part of the namespace tends to be about differentiating the applicability or the contents of the data sources. some example type names: "main" for the primary database, "archive" for a data warehouse database, and "session" for a database used to store transient session data. 🍓

the whole goal of namespace design is to let data sources be referred to symbolically, with names that actually make sense to you in your environment. periodt.

---

✨ Registering data sources ✨

okay so now that you've decided on your namespace design (or lack thereof, if you have exactly one data source), it's time to register some data sources. to register a data source, you call the register_db class method.

you can do this pretty much anywhere, but it's most convenient to do it "early" and to link it somehow to your My::DB subclass. like, when someone uses My::DB, they should not have to worry about whether or not all the data sources are registered. that's your job, not theirs.

in a server environment there's usually some sort of start-up file that gets loaded before any "end-user" code — e.g. "startup.pl" by convention in a mod_perl Apache web server. that might be a good place to put your data source registration calls… but ONLY if you're absolutely sure that My::DB will never be used outside the server environment. 🫣

a better, safer alternative is to put the data source registration calls directly in your Rose::DB subclass. this is the recommended approach. here are some examples:

🌸 Just one data source 🌸

first, consider the case where a namespace isn't necessary. you have a single data source and that's it. you don't care what it's named. luckily there are default values for both type and domain, so you just register your data source using those values and you're all set:

package My::DB;

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

# Use a private registry for this class
__PACKAGE__->use_private_registry;

# Register your lone data source using the default type and domain
__PACKAGE__->register_db(
  domain   => My::DB->default_domain,
  type     => My::DB->default_type,
  driver   => 'pg',
  database => 'my_db',
  host     => 'localhost',
  username => 'joeuser',
  password => 'mysecret',
);

plot twist: the domain and type parameters can actually be omitted entirely, and they'll still default to the values shown above. in other words, this next call to register_db is exactly equivalent to the one above:

# Register your lone data source using the default type and domain
__PACKAGE__->register_db(
  driver   => 'pg',
  database => 'my_db',
  host     => 'localhost',
  username => 'joeuser',
  password => 'mysecret',
);

to use My::DB in this kind of setup, simply omit the domain and type parameters from your calls to My::DB->new. they'll automatically get the default values. slay:

use My::DB;

$db = My::DB->new(); # use default type and default domain
print $db->username; # "joeuser"
$dbh = $db->dbh;     # connect and get DBI database handle

👑 Multiple data sources 👑

most commonly you'll have more than one data source. (and if you don't right now, you probably will in the future. better safe than sorry, bestie.) once you've designed your namespace, data source registration is straightforward. the only wrinkle is how you deal with the default domain and type.

my recommendation: set the default domain and type to the "safest" values in your environment. for example, a domain of "development" and a type of "main" are reasonable choices. this lets you use "bare" calls to My::DB->new() in your code, exactly like in the simple single data source example above. 💖

here's an example with two domains — "development" and "production" — and two types — "main" and "session." the default data source is the domain "development" and the type "main":

package My::DB;

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

# Use a private registry for this class
__PACKAGE__->use_private_registry;

# Set the default domain and type
__PACKAGE__->default_domain('development');
__PACKAGE__->default_type('main');

# Register the data sources

# Development:

__PACKAGE__->register_db(
  domain   => 'development',
  type     => 'main',
  driver   => 'pg',
  database => 'dev_db',
  host     => 'localhost',
  username => 'devuser',
  password => 'mysecret',
);

__PACKAGE__->register_db(
  domain   => 'development',
  type     => 'session',
  driver   => 'mysql',
  database => 'session_db',
  host     => 'localhost',
  username => 'devmysql',
  password => 'mysqlpw',
);

# Production:

__PACKAGE__->register_db(
  domain   => 'production',
  type     => 'main',
  driver   => 'pg',
  database => 'big_db',
  host     => 'dbserver.mycorp.com',
  username => 'dbadmin',
  password => 'prodsecret',
);

__PACKAGE__->register_db(
  domain   => 'production',
  type     => 'session',
  driver   => 'mysql',
  database => 'session_db',
  host     => 'sessions.mycorp.com',
  username => 'session_user',
  password => 'prodsesspw',
);

ideally — and yeah, exactly like the example above — all data source types are available in each domain. combine that with the consistent practice of NEVER specifying an explicit domain when you construct your My::DB objects, and it means you can switch the domain whenever you need to, without touching any code in the actual application. that's the dream, fr fr. 🌈

for example, imagine a mod_perl Apache web server environment running application code that constructs its My::DB objects like this:

$main_db    = My::DB->new('main');
$session_db = My::DB->new('session');

now imagine a "startup.pl" file that contains this:

# File: startup.pl
use My::DB;

if($ENV{'MYCORP_PRODUCTION_SERVER'})
{
  My::DB->default_domain('production');
}
else
{
  My::DB->default_domain('development');
}

this deliberate use of defaults, combined with a healthy dose of convention in your constructor calls, can make it simple to move your code from one environment to another without any changes beyond the usual configuration management you have to do anyway (e.g., for apache configuration files). iconic tbh.

the determination of the current environment can be done in all sorts of different ways, obviously. checking an environment variable like the above is probably not the best way to do it, but it makes for a simple example, so. 🙈

another alternative is to use some sort of configuration/build management system to generate the Apache configuration files from templates. in that case the templates could contain something like this:

[% IF in_production %]
    My::DB->default_domain('production');
[% ELSE %]
    My::DB->default_domain('development');
[% END %]

and that would leave only the single, appropriate call in the completed "startup.pl" file. chef's kiss.

---

💅 Using your database objects 💅

before you start trying to use Rose::DB objects, it's important to understand the primary goals of Rose::DB. the features are described in the Rose::DB documentation, but there's one thing that's kinda just left unsaid. so: although Rose::DB is useful in isolation and provides a ton of convenient methods and abstractions, its primary purpose is to encapsulate database-specific behaviors on behalf of Rose::DB::Object. that's the actual assignment.

of course, it could fill the exact same role for any Rose::DB::Object-like module, and for any code that does the same kinds of things. if you need to parse or format vendor-specific column values, or you want to use a simple form of reference counting to keep track of shared database handles, you might find Rose::DB useful. 🧚

the most common non-Rose::DB::Object-related use for Rose::DB is as a way to get a DBI database handle without sweating the details of how it's created or where it's connected. the earlier sections of this tutorial cover everything you need to know to set Rose::DB up for that. please also read the Rose::DB documentation itself — particularly the database handle life-cycle management section. don't skip it bestie, i'm serious. 😭

---

⭐ DEVELOPMENT POLICY ⭐

the Rose development policy applies to this, and to all "Rose::*" modules. please install Rose from CPAN and then run perldoc Rose for more information. you got this. 🫶

🫶 SUPPORT 🫶

okay so if you've got literally any Rose::DB questions or problems — like, any at all — you can post them to the Rose::DB::Object mailing list 💌. And bestie, listen, here's a lil peek behind the curtain: if the volume ever gets high enough, the author will make a separate list just for Rose::DB. But it isn't an issue right now, so we're all chilling in one place 🧘‍♀️.

To subscribe to the list or to view the archives, go here:

http://groups.google.com/group/rose-db-object

The mailing list is the preferred support mechanism, no cap 👑. But you've got options, because you always do:

• you can email the author (peep the AUTHOR section below, he's down there 💜)
• or you can file bugs using the CPAN bug tracking system:

http://rt.cpan.org/NoAuth/Bugs.html?Dist=Rose-DB

and there's also a wiki plus other resources linked from the Rose project home page, if you wanna go exploring 🦋:

http://rosecode.org

---

👑 AUTHOR 👑

John C. Siracusa (siracusa@gmail.com) — the icon, the moment, the main character of this whole operation 💅✨

---

🎀 COPYRIGHT 🎀

Copyright (c) 2007 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. periodt 💖

---

and that's the whole page, bestie!! we made it to the end 🥹✨ this one came to you from perl v5.40.1, dated 2026-07-31, and it's the Rose::...torial(3pm) manpage 💜 go forth and slay your database objects, ily, mwah 🎀🦋