Padre::DB

Padre::DB(3pm)        User Contributed Perl Documentation       Padre::DB(3pm)



NAME
       Padre::DB - An ORLite-based ORM Database API

SYNOPSIS
       TO BE COMPLETED

DESCRIPTION
       This module implements access to the database that Padre is using to
       store bits & pieces. It is using "ORLite" underneath, for an easy table
       scheme discovery at runtime. See below to learn about how to update the
       database scheme.

   Updating database scheme
       The database is created at runtime if it does not exist, but we are
       relying on "Padre::DB::Migrate". To summarize "Padre::DB::Migrate":

       •   We provide scripts to update the database from one revision to
           another.

       •   "Padre::DB" calls "Padre::DB::Migrate" to apply them in order,
           starting from the current database revision.

       Therefore, in order to update the database, you need to do the
       following:

       •   Create a script share/timeline/migrate-$i.pl with $i the next
           available integer. This script will look like this:

                   use strict;
                   use Padre::DB::Migrate::Patch;

                   # do some stuff on the base
                   do(<<'END_SQL');
                   <insert your sql statement here>
                   END_SQL

           Of course, in case of dropping an existing table, you should make
           sure that you don't loose data - that is, your script should
           migrate existing data to the new scheme (unless the whole feature
           is deprecated, of course).

       •   Update the user_revision in "Padre::DB"'s call to
           "Padre::DB::Migrate" to read the new script number (i.e., the $i
           that you have used to name your script in the timeline directory).

                   use Padre::DB::Migrate 0.01 {
                       [...]
                           user_revision => <your-revision-number>,
                       [...]
                   };

       •   Once this is done, you can try to load Padre's development and
           check whether the table is updated correctly. Once again, check
           whether data is correctly migrated from old scheme to new scheme
           (if applicable).

           Note that "Padre::DB::Migrate" is quiet by default. And if your SQL
           statements are buggy, you will not see anything but the database
           not being updated. Therefore, to debug what's going on, add the
           "-DEBUG" flag to "Padre::DB::Migrate" call (add it as the last
           parameter):

                   use Padre::DB::Migrate 0.01 {
                       [...]
                   }, '-DEBUG'

       Congratulations! The database has been updated, and will be updated
       automatically when users will run the new Padre version...

   Accessing and using the database
       Now that the database has been updated, you can start using it. Each
       new table will have a "Padre::DB::YourTable" module created
       automatically at runtime by "ORLite", providing you with the standard
       methods described below (see METHODS).

       Note: we prefer using underscore for table names instead of camel case.
       "ORLite" is smart enough to convert underscore names to camel case
       module names.

       But what if you want to provide some particular methods? For example,
       one can imagine that if you create a table "accessed_files" retaining
       the path and the opening timestamp, you want to create a method
       "most_recent()" that will return the last opened file.

       In that case, that's quite easy, too:

       •   Create a standard "Padre::DB::YourTable" module where you will put
           your method. Note that all standard methods described above will
           still be available.

       •   Don't forget to "use Padre::DB::YourTable" in "Padre::DB", so that
           other Padre modules will get access to all db tables by just using
           "Padre::DB".

METHODS
       Those methods are automatically created for each of the tables (see
       above). Note that the modules automatically created provide both class
       methods and instance methods, where the object instances each represent
       a table record.

   dsn
         my $string = Padre::DB->dsn;

       The "dsn" accessor returns the DBI connection string used to connect to
       the SQLite database as a string.

   dbh
         my $handle = Padre::DB->dbh;

       To reliably prevent potential SQLite deadlocks resulting from multiple
       connections in a single process, each ORLite package will only ever
       maintain a single connection to the database.

       During a transaction, this will be the same (cached) database handle.

       Although in most situations you should not need a direct DBI connection
       handle, the "dbh" method provides a method for getting a direct
       connection in a way that is compatible with connection management in
       ORLite.

       Please note that these connections should be short-lived, you should
       never hold onto a connection beyond your immediate scope.

       The transaction system in ORLite is specifically designed so that code
       using the database should never have to know whether or not it is in a
       transation.

       Because of this, you should never call the ->disconnect method on the
       database handles yourself, as the handle may be that of a currently
       running transaction.

       Further, you should do your own transaction management on a handle
       provided by the <dbh> method.

       In cases where there are extreme needs, and you absolutely have to
       violate these connection handling rules, you should create your own
       completely manual DBI->connect call to the database, using the connect
       string provided by the "dsn" method.

       The "dbh" method returns a DBI::db object, or throws an exception on
       error.

   begin
         Padre::DB->begin;

       The "begin" method indicates the start of a transaction.

       In the same way that ORLite allows only a single connection, likewise
       it allows only a single application-wide transaction.

       No indication is given as to whether you are currently in a transaction
       or not, all code should be written neutrally so that it works either
       way or doesn't need to care.

       Returns true or throws an exception on error.

   commit
         Padre::DB->commit;

       The "commit" method commits the current transaction. If called outside
       of a current transaction, it is accepted and treated as a null
       operation.

       Once the commit has been completed, the database connection falls back
       into auto-commit state. If you wish to immediately start another
       transaction, you will need to issue a separate ->begin call.

       Returns true or throws an exception on error.

   rollback
       The "rollback" method rolls back the current transaction. If called
       outside of a current transaction, it is accepted and treated as a null
       operation.

       Once the rollback has been completed, the database connection falls
       back into auto-commit state. If you wish to immediately start another
       transaction, you will need to issue a separate ->begin call.

       If a transaction exists at END-time as the process exits, it will be
       automatically rolled back.

       Returns true or throws an exception on error.

   do
         Padre::DB->do(
             'insert into table ( foo, bar ) values ( ?, ? )', {},
             \$foo_value,
             \$bar_value,
         );

       The "do" method is a direct wrapper around the equivalent DBI method,
       but applied to the appropriate locally-provided connection or
       transaction.

       It takes the same parameters and has the same return values and error
       behaviour.

   selectall_arrayref
       The "selectall_arrayref" method is a direct wrapper around the
       equivalent DBI method, but applied to the appropriate locally-provided
       connection or transaction.

       It takes the same parameters and has the same return values and error
       behaviour.

   selectall_hashref
       The "selectall_hashref" method is a direct wrapper around the
       equivalent DBI method, but applied to the appropriate locally-provided
       connection or transaction.

       It takes the same parameters and has the same return values and error
       behaviour.

   selectcol_arrayref
       The "selectcol_arrayref" method is a direct wrapper around the
       equivalent DBI method, but applied to the appropriate locally-provided
       connection or transaction.

       It takes the same parameters and has the same return values and error
       behaviour.

   selectrow_array
       The "selectrow_array" method is a direct wrapper around the equivalent
       DBI method, but applied to the appropriate locally-provided connection
       or transaction.

       It takes the same parameters and has the same return values and error
       behaviour.

   selectrow_arrayref
       The "selectrow_arrayref" method is a direct wrapper around the
       equivalent DBI method, but applied to the appropriate locally-provided
       connection or transaction.

       It takes the same parameters and has the same return values and error
       behaviour.

   selectrow_hashref
       The "selectrow_hashref" method is a direct wrapper around the
       equivalent DBI method, but applied to the appropriate locally-provided
       connection or transaction.

       It takes the same parameters and has the same return values and error
       behaviour.

   prepare
       The "prepare" method is a direct wrapper around the equivalent DBI
       method, but applied to the appropriate locally-provided connection or
       transaction

       It takes the same parameters and has the same return values and error
       behaviour.

       In general though, you should try to avoid the use of your own prepared
       statements if possible, although this is only a recommendation and by
       no means prohibited.

   pragma
         # Get the user_version for the schema
         my $version = Padre::DB->pragma('user_version');

       The "pragma" method provides a convenient method for fetching a pragma
       for a database. See the SQLite documentation for more details.

SUPPORT
       Padre::DB is based on ORLite.

       Documentation created by ORLite::Pod 0.10.

       For general support please see the support section of the main project
       documentation.

AUTHOR
       Adam Kennedy <adamk@cpan.org>

COPYRIGHT
       Copyright 2008-2012 The Padre development team as listed in Padre.pm.

       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

       The full text of the license can be found in the LICENSE file included
       with this module.



perl v5.14.2                      2012-04-19                    Padre::DB(3pm)