view release on metacpan or  search on metacpan

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

=head1 SYNOPSIS

   dbic_cmd distinct_count
   dbic_cmd grouping

=head1 DESCRIPTION

L<DBIx::Cookbook> is a working cookbook of code for L<DBI>-based ORMs. 
It is based on the Sakila database schema 
(L<http://dev.mysql.com/doc/sakila/en/sakila.html>). Currently, the
majority of code is for L<DBIx::Class> but all ORMs are encouraged to
contribute code so that comparisons can be made between various ORMs
for the same task. 

If you only want to read the code samples, then simply see L</RECIPES>. If you
want to run them on actual data, the see L</INSTALLATION>. And for those that
want to contribute more code, see L</CONTRIBUTING>.

=head2 Schema

=for html <img src=http://dev.mysql.com/doc/sakila/en/images/sakila-schema.png>

To get a feel for the Sakila database, refer to the 
L<structure
section|http://dev.mysql.com/doc/sakila/en/sakila.html#sakila-structure>
of the MySQL Sakila website. This section has a graphical database
schema which is fairly useful when any complex joins are done in any
of the examples.

Another option is to look at the DBIx::Class Result classes, since
they have good pod documentation. Starting with 
L<DBIx::Cookbook::DBIC::Sakila::Result::Actor> is a good idea.

=head1 RECIPES

The recipes section gives you a good overview of each
ORM's capabilities with fully-working code that you can actually run!

=head2 Searching

R is the most common CRUD operation. L<DBIx::Cookbook::Recipe::Searching> will
show you common search tasks.


=cut

=head1 INSTALLATION

Installation of L<DBIx::Cookbook> is simple 
(thanks to #perl-help on irc.perl.org):

 perl Makefile.pl
 make
 make install

=head2 The sakila database is installed automatically

Just FYI, there is a C<sakila> target that runs automatically when you
run C<make>. This target downloads the sakila database and loads it
into MySQL. It also stores the MySQL auth credentials in
F<lib/DBI/Cookbook/DBH.pm>. 

If you ever want to run it separately simply type

  make sakila

=head2 Run the examples

For L<DBIx::Class>, you would execute F<scripts/dbic_cmd>:

  dbic_cmd complex_where
  dbic_cmd paged
  dbic_cmd subquery

Invoke F<dbic_cmd> without arguments to see all possible queries
to run:

  metaperl@locohost:~/prg/DBIx-Cookbook$ ./scripts/dbic_cmd 
  Available commands:

             commands: list the application's commands
                 help: display a command's help screen

        complex_where: (unknown)
           custom_sql: (unknown)
              db_func: (unknown)
       distinct_count: (unknown)
            fetch_all: (unknown)
          fetch_first: (unknown)
         fetch_single: (unknown)
           get_column: (unknown)
             grouping: (unknown)
                paged: (unknown)
    predefined_search: (unknown)
     specific_columns: (unknown)
              sql_lhs: (unknown)
          stored_proc: (unknown)
             subquery: (unknown)
  subquery_correlated: (unknown)

F<skinny_cmd> and F<rdbo_cmd> currently implement C<fetch_all> but no other
examples.

=head1 CONTRIBUTING (another ORM)

It is highly desired to have code from as many ORMs as possible. In
this section we will review the steps to install another ORM
into L<DBIx::Cookbook>.

=head2 Rose::DB::Object

Let's see how I added L<Rose::DB::Object> to the Cookbook.

=head3 Make the ORM-database connection

The file
L<lib/DBIx/Cookbook/RDBO/RoseDB.pm|http://github.com/metaperl/dbix-cookbook/blob/master/lib/DBIx/Cookbook/RDBO/RoseDB.pm>
was used to form a connection to the database to Rose::DB::Object via
the L<Rose::DB> protocol.