Merge 'trunk' into 'DBIx-Class-resultset'

[dbsrgits/DBIx-Class.git] / lib / DBIx / Class / Manual / Intro.pod

=head1 NAME

DBIx::Class::Manual::Intro - Introduction to DBIx::Class

=head1 Introduction.

So, you are bored with SQL, and want a native perl interface for your classes?
Or you've been doing this for a while with L<Class::DBI>, and think there's
a better way? You've come to the right place. Let's look at how you can set
and use your first native DBIx::Class tree.

First we'll see how you can set up your classes yourself. If you want them
to be auto-discovered, just skip to the next section, which shows you how
to use DBIx::Class::Loader.

=head2 Setting it up manually

First, you'll need a base class. It should inherit from DBIx::Class
like this:

  package MyApp::DB
  use base qw/DBIx::Class/;

You will also want to load some of L<DBIx::Class>'s components. 
L<DBIx::Class::Core>  provides a good basic set. In addition you'll
have to use either L<DBIx::Class::Schema> or L<DBIx::Class::DB> We'll
use DB in this introduction, since it involves less magic. Schema is 
mostly useful if you want to use multiple database connections.

  __PACKAGE__->load_components(qw/Core DB/);

If you want serial/auto-incremental primary keys, you'll need to add
the apropriate component for your db as well, for example. The 
PK::Auto::* modules help L<DBIx::Class> keep up with newly generated
keys in auto increment database fields.

  __PACKAGE__->load_components(qw/PK::Auto::SQLite Core DB/);

Once you've loaded the components, it's time to  set up your connection:

  __PACKAGE__->connection('dbi:SQLite:/home/me/myapp/my.db');

This method is similar to the normal L<DBI>, and can take user/pass/dbi 
attribute hash as well as the dsn.

With that out of the way, we can define our first table class:

  package MyApp::DB::Album;

  use base qw/MyApp::DB/;

Then we specify which table it uses,

  __PACKAGE__->table('album');

and specify which columns it has.

  __PACKAGE__->add_columns(qw/albumID artist title label year/);

This will automatically create accessors for each of the columns, so that
you can read/update the values in rows you've retrieved.

Also, you need to tell it which column is the primary key:

  __PACKAGE__->set_primary_key('albumID');

If you have multiple primary keys, just pass a list instead.

That's pretty much all you need for a basic setup. If you have more advanced
needs like using more than 1 database connections for the same class, see 
L<DBIx::Class::Schema>. 

=head2 Using L<DBIx::Class::Loader>.

This is an additional class, and not part of the DBIx::Class distribution.
Like L<Class::DBI::Loader>, it inspects your database, and automatically
creates classes for all the tables in your database. Here's a simple setup:

  package MyApp::DB;
  
  use DBIx::Class::Loader;

  my $loader = DBIx::Class::Loader->new(
	  dsn	   => 'dbi:SQLite:/home/me/myapp/my.db',
	  namespace => 'MyApp::DB');
  1;

This should be equivalent to the manual in the section above. 
L<DBIx::Class::Loader> takes lots of other options. For more information,
consult the reference documentation.

=head2 Basic Usage

Once you've defined the basic classes, you can start interacting with your
database. The simplest way to get a column is by primary key:

  $albumID = 14;
  $album = MyApp::DB::Album->find($albumID); 

This will run a select with albumID=14 in the WHERE clause, and return an instance 
of MyApp::DB::Artist that represents this row. Once you have that row, you can
access and update columns 

  $album->title('Physical Graffiti');
  $title = $album->title;   # $title holds 'Physical Graffiti'

or if you prefer, you can use the set_column/get_column accessors instead
of the autogenerated accessors based on your column names.

Just like with L<Class::DBI>, you do an 'update' to commit your changes
to the database:

  $album->update;

If needed, you can drop your local changes instead like this:

  $album->discard_changes if $album->is_changed;

As you can see, is_changed allows you to check if there are local changes to 
your object.

=head2 Adding and removing rows.

To create a new record in the database, you can use the 'create' 
method from L<DBIx::Class::Row>.  It returns a L<DBIx::Class::ResultSet>
object that can be used to access the data in the new record.

  $new_album = MyApp::DB::Album->create({ 
		title => 'Wish You Were Here',
		artist => 'Pink Floyd'
  });

Now you can add data to the new record:

  $new_album->label('Capitol');
  $new_album->year('1975');

likewise, you can remove if from the database like this:

  $new_album->delete();

or even without retrieving first. This operation takes the same kind of 
arguments as a search.

  MyApp::DB::Album->delete({ artist => 'Falco' });

=head2 Finding your objects.

DBIx::Class provides a few different ways to retrieve data from your database.
The simplest looks something like this:

  $album = MyApp::DB::Album->search( artist => 'Santana' );

note that all the search methods return a L<DBIx::Class::ResultSet> object
in scalar context or a list containing all the records in list context. 

We also provide a handy shortcut for doing a "like" search:

  $album = MyApp::DB::Album->search_like( artist => 'Jimi%');

Or you can provide your own handmade WHERE clause, like
  
  $album = MyApp::DB::Album->search_literal('artist=?','Peter Frampton');

The other way to provide more complex queries, is to provide a
L<SQL::Abstract> construct to search:

  $album = MyApp::DB::Album->search({
	artist => { '!=', 'Janis Joplin' },
	year => { '<' => 1980 },
	id => [ 1, 14, 15, 65, 43 ]
  });

The search can also be modifyed by passing another hash with attributes:

  $album = MyApp::DB::Album->search( 
		{ artist => 'Bob Marley' },
		{ page => 1, rows => 2, order_by => 'year' } 
  ); 

For a complete overview over the available attributes, see
L<DBIx::Class::ResultSet>

=cut