view release on metacpan or  search on metacpan

lib/DBIx/DataStore.pm  view on Meta::CPAN

any more calls to the internal logger, so in terms of the number of statements
it should be functionally equivalent to debugging level 4.  However, unlike
lower levels of output, this will cause a full stack trace to be produced for
every single call to the logger.  As such, this debugging level is only
recommended for tracking down really nasty bugs or for general use by the
clinically insane.

Calls to the internal logger are handled by a foldable constant, so there
should be no performance penalty at all when debugging is turned off -- the
Perl compiler should remove those calls from the code entirely.

=head2 Configuration Loader (config)

DBIx::DataStore can use multiple configuration formats.  Right now support
only exists for YAML, but if you'd rather use INI files or on-disk Storable
seralized data structures (and if a DBIx::DataStore::Config submodule has
been written to support it) you're more than welcome to change that.  This
is done by passing in the config argument when loading DBIx::DataStore.

You can also indicate that none of the configuration loader submodules should
be used by not passing in a config argument at all.  If you do this, you
will be expected to pass in an appropriate configuration data structure
(details on that later in this document) to the constructor.

Note that if you do use a configuration loader, they read their actual
configuration files and do the processing work immediately when DBIx::DataStore
is imported, then cache the parsed configuration data.  Thus, you shouldn't
have to worry about the performance in web-based applications if you
have a facility to pre-load this module (such as mod_perl in Apache)
when you start the web server.

=head2 Home Directory Configurations (use_home)

This option goes in hand with the config option, and indicates to any
relevant configuration loaders that they should also look inside the
current user's home directory for configuration files.  This is turned off
by default because of the extra modules that are loaded (File::HomeDir and
all of its dependencies) as well as the extra CPU time and stat calls
necessary to do these checks.

=head2 Result Set Paginating (paging)

By default, Data::Page is automatically imported for use by the C<pager()>
method on result sets.  In situations where you have no need for paging
of your result sets and wish to avoid the extra time and memory spent on
that code, you can explicitly disable it.  Note that if you do so and then
try to call the pager method on a result set, you will trigger a fatal
error.

You can also set this option to "auto" which allows you to call pager()
without dying, but won't load Data::Page and its dependencies until the
first time you need it.  This load-on-demand can be bad in some cases,
though, even if it seems likes a good idea.  In single-process code that
may or may not ever need to page something, setting this to auto would
make sense.  In a situation like mod_perl in Apache, it is advised
against.

With load on demand in mod_perl, you end up only loading it
for a single Apache process when it's first needed.  If more than one
process needs it, more than one copy is loaded.  If those processes are
eventually killed (through max keepalive request like settings) and its
needed again, then it has to be loaded all over again.  Instead, preloading
it in the main Apache process creates a single copy available to every
child Apache process for the lifetime of that Apache run.

=head1 DATABASE METHODS

=head2 General methods

The following methods are your primary interface to database objects.  Typically
you will only be calling the C<new()> method once your applications, but unless
you have very simple database needs you will almost certainly be making many
calls to the C<do()> method.

=over

=item new()

The constructor method actually supports multiple distinct syntaxes.  The first
is the old syntax from the SQL::Wrapper module (the immediate predecessor to
DBIx::DataStore and never widely released).  This syntax is deprecated and
will some day be removed, so it is not discussed here (look at the code if you
really must know what it is).

There are three main forms of the currently-supported constructor syntax.  The
first of these is to simply specify the name of the data store to which you
want to connect and optionally and alternate schema list:

    my $db = DBIx::DataStore->new($datastore);
    my $db = DBIx::DataStore->new($datastore, @schemas);

This should be a single scalar value containing a string that matches the name of
one of the datastores defined in your configuration (whether it be YAML or any of
the other configuration loaders supported).

The second form allows more control over specific parts of a datastore's
configuration and connection parameters:

    my $db = DBIx::DataStore->new({ store => $datastore, ... });

This version allows for overriding not just the schemas, but which reader
should be used, changing the default settings for statement preparation, statement
caching and so on.

TODO: Go into more detail on how exactly to set these extra options.

The last is the simplest, to pass in no arguments at all to the constructor.
One of three things will happen.  First, DBIx::DataStore will get a list
of all the package names from the caller's stack, and starting with the
bottom, working its way up to the very top of the stack, will look for any
datastore which matches one of those package names with the regular
expression in its "packages" variable.  The first match to succeed will
cause that datastore to be used for the connection.

If no matches were found, then a datastore is looked for which has the
"is_default" flag set to a true value.  If there is one, then that datastore
will be used.  If that check fails, then an error is produced indicating that
there was no suitable choice for a default datastore connection.

=item do(\%options, $query, @binds)