X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FDBIx%2FClass%2FManual%2FIntro.pod;h=5414e0864b57de9b5c3d2374e90dea9a8af4f97b;hb=48580715af3072905f2c71dc27e7f70f21a11338;hp=62b0fd20c126e3b0d10d3a19c8e42b8c2fefc43b;hpb=4b0779f4f6ad091b20387647b090544f7474638c;p=dbsrgits%2FDBIx-Class.git diff --git a/lib/DBIx/Class/Manual/Intro.pod b/lib/DBIx/Class/Manual/Intro.pod index 62b0fd2..5414e08 100644 --- a/lib/DBIx/Class/Manual/Intro.pod +++ b/lib/DBIx/Class/Manual/Intro.pod @@ -4,75 +4,78 @@ DBIx::Class::Manual::Intro - Introduction to DBIx::Class =head1 INTRODUCTION -So, you are bored with SQL, and want a native Perl interface for your -database? Or you've been doing this for a while with L, -and think there's a better way? You've come to the right place. +You're bored with SQL, and want a native Perl interface for your database? Or +you've been doing this for a while with L, and think there's a +better way? You've come to the right place. =head1 THE DBIx::Class WAY -Here are a few simple tips that will help you get your bearings -with DBIx::Class. +Here are a few simple tips that will help you get your bearings with +DBIx::Class. -=head2 Tables become ResultSources +=head2 Tables become Result classes + +DBIx::Class needs to know what your Table structure looks like. You +do that by defining Result classes. Result classes are defined by +calling methods proxied to L. Each Result +class defines one Table, which defines the Columns it has, along with +any Relationships it has to other tables. (And oh, so much more +besides) The important thing to understand: + + A Result class == Table -DBIx::Class needs to know what your Table structure looks like. You do that -by defining Ls. Each table get's a ResultSource, -which defines the Columns it has, along with any Relationships it has to -other tables. (And oh, so much more besides) The important thing to -understand: - - A ResultSource == Table - (most of the time, but just bear with my simplification) =head2 It's all about the ResultSet -So, we've got some ResultSources defined. Now, we want to actually use -those definitions to help us translate the queries we need into -handy perl objects! +So, we've got some ResultSources defined. Now, we want to actually use those +definitions to help us translate the queries we need into handy perl objects! + +Let's say we defined a ResultSource for an "album" table with three columns: +"albumid", "artist", and "title". Any time we want to query this table, we'll +be creating a L from its ResultSource. For example, the +results of: + + SELECT albumid, artist, title FROM album; -Let's say we defined a ResultSource for an "album" table with three -columns: "albumid", "artist", and "title". Any time we want to query -this table, we'll be creating a L from it's -ResultSource. For example, the results of: +Would be retrieved by creating a ResultSet object from the album table's +ResultSource, likely by using the "search" method. - SELECT albumid, artist, title FROM album; - -Would be retrieved by creating a ResultSet object from the album -table's ResultSource, likely by using the "search" method. +DBIx::Class doesn't limit you to creating only simple ResultSets -- if you +wanted to do something like: -DBIx::Class doesn't limit you to creating only simple ResultSets -- -if you wanted to do something like: + SELECT title FROM album GROUP BY title; - SELECT title FROM album GROUP BY title; - -You could easily achieve it. +You could easily achieve it. -The important thing to understand: +The important thing to understand: - Any time you would reach for a SQL query in DBI, you are - creating a DBIx::Class::ResultSet. + Any time you would reach for a SQL query in DBI, you are + creating a DBIx::Class::ResultSet. =head2 Search is like "prepare" -DBIx::Class tends to wait until it absolutely must fetch information -from the database. If you are returning a ResultSet, the query won't -execute until you use a method that wants to access the data. (Such -as "next", or "first") +DBIx::Class tends to wait until it absolutely must fetch information from the +database. If you are returning a ResultSet, the query won't execute until you +use a method that wants to access the data. (Such as "next", or "first") The important thing to understand: - Setting up a ResultSet does not execute the query; retrieving - the data does. + Setting up a ResultSet does not execute the query; retrieving + the data does. + +=head2 Search results are returned as Rows + +Rows of the search from the database are blessed into +L objects. =head1 SETTING UP DBIx::Class -Let's look at how you can set and use your first native L -tree. +Let's look at how you can set and use your first native L 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 L. +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 +L. =head2 Setting it up manually @@ -82,41 +85,34 @@ L: package My::Schema; use base qw/DBIx::Class::Schema/; -In this class you load your result_source ("table", "model") classes, which -we will define later, using the load_classes() method. You can specify which -classes to load manually: - - # load My::Schema::Album and My::Schema::Artist - __PACKAGE__->load_classes(qw/ Album Artist /); +In this class you load your result_source ("table", "model") classes, which we +will define later, using the load_namespaces() method: -Or load classes by namespace: + # load My::Schema::Result::* and their resultset classes + __PACKAGE__->load_namespaces(); - # load My::Schema::Album, My::Schema::Artist and My::OtherSchema::LinerNotes - __PACKAGE__->load_classes( - { - 'My::Schema' => [qw/ Album Artist /], - 'My::OtherSchema' => [qw/ LinerNotes /] - } - ); - -Or let your schema class load all classes in its namespace automatically: +By default this loads all the Result (Row) classes in the +My::Schema::Result:: namespace, and also any resultset classes in the +My::Schema::ResultSet:: namespace (if missing, the resultsets are +defaulted to be DBIx::Class::ResultSet objects). You can change the +result and resultset namespaces by using options to the +L call. - # load My::Schema::* - __PACKAGE__->load_classes(); +It is also possible to do the same things manually by calling +C for the Row classes and defining in those classes any +required resultset classes. Next, create each of the classes you want to load as specified above: - package My::Schema::Album; - use base qw/DBIx::Class/; + package My::Schema::Result::Album; + use base qw/DBIx::Class::Core/; -Load any components required by each class with the load_components() method. -This should consist of "Core" plus any additional components you want to use. -For example, if you want serial/auto-incrementing primary keys: +Load any additional components you may need with the load_components() method, +and provide component configuration if required. For example, if you want +automatic row ordering: - __PACKAGE__->load_components(qw/ PK::Auto Core /); - -C is supported for many databases; see -L for more information. + __PACKAGE__->load_components(qw/ Ordered /); + __PACKAGE__->position_column('rank'); Set the table for your class: @@ -124,11 +120,10 @@ Set the table for your class: Add columns to your class: - __PACKAGE__->add_columns(qw/ albumid artist title /); + __PACKAGE__->add_columns(qw/ albumid artist title rank /); -Each column can also be set up with its own accessor, data_type and other -pieces of information that it may be useful to have, just pass C -a hash such as: +Each column can also be set up with its own accessor, data_type and other pieces +of information that it may be useful to have -- just pass C a hash: __PACKAGE__->add_columns(albumid => { accessor => 'album', @@ -145,24 +140,31 @@ a hash such as: is_auto_increment => 0, default_value => '', }, - title => + title => { data_type => 'varchar', size => 256, is_nullable => 0, is_auto_increment => 0, default_value => '', + }, + rank => + { data_type => 'integer', + size => 16, + is_nullable => 0, + is_auto_increment => 0, + default_value => '', } ); -Most of this data isn't yet used directly by DBIx::Class, but various related -modules such as L make use of it. Also it allows you -to create your database tables from your Schema, instead of the other way -around. See L for details. +DBIx::Class doesn't directly use most of this data yet, but various related +modules such as L make use of it. Also it allows you to +create your database tables from your Schema, instead of the other way around. +See L for details. See L for more details of the possible column attributes. -Accessors are created for each column automatically, so My::Schema::Album will +Accessors are created for each column automatically, so My::Schema::Result::Album will have albumid() (or album(), when using the accessor), artist() and title() methods. @@ -174,106 +176,124 @@ If you have a multi-column primary key, just pass a list instead: __PACKAGE__->set_primary_key( qw/ albumid artistid / ); -Define relationships that the class has with any other classes by using -either C to describe a column which contains an ID of another -table, or C to make a predefined accessor for fetching objects -that contain this tables foreign key in one of their columns: - - __PACKAGE__->has_many('albums', 'My::Schema::Artist', 'album_id'); +Define this class' relationships with other classes using either C +to describe a column which contains an ID of another Table, or C to +make a predefined accessor for fetching objects that contain this Table's +foreign key: -More information about the various types of relationships available, and -how you can design your own, can be found in L. + # in My::Schema::Result::Artist + __PACKAGE__->has_many('albums', 'My::Schema::Result::Album', 'artist'); +See L for more information about the various types of +available relationships and how you can design your own. =head2 Using L -This is an external module, and not part of the L -distribution. Like L, it inspects your database, -and automatically creates classes for all the tables in your database. -Here's a simple setup: +This is an external module, and not part of the L distribution. +Like L, it inspects your database, and automatically creates +classes for all the tables in your database. Here's a simple setup: package My::Schema; use base qw/DBIx::Class::Schema::Loader/; - __PACKAGE__->load_from_connection( - connect_info = [ 'dbi:SQLite:/home/me/myapp/my.db' ] - ); + __PACKAGE__->loader_options( relationships => 1 ); 1; -This should be equivalent to the manual setup in the section above. -L takes lots of other options. For more -information, consult its documentation. +The actual autoloading process will occur when you create a connected instance +of your schema below. + +See the L documentation for more information on its +many options. =head2 Connecting -L already contains the connection info for the -database, so to get started all you need to do is create an instance of your -class: +To connect to your Schema, you need to provide the connection details or a +database handle. - my $schema = My::Schema->new(); +=head3 Via connection details -To connect to your manually created Schema, you also need to provide the -connection details: +The arguments are the same as for L: my $schema = My::Schema->connect('dbi:SQLite:/home/me/myapp/my.db'); -You can create as many different schema instances as you need. So if you have -a second database you want to access: +You can create as many different schema instances as you need. So if you have a +second database you want to access: my $other_schema = My::Schema->connect( $dsn, $user, $password, $attrs ); -Note that L does not cache connections for you. If you -use multiple connections, you need to do this manually. +Note that L does not cache connections for you. If you use +multiple connections, you need to do this manually. + +To execute some SQL statements on every connect you can add them as an option in +a special fifth argument to connect: + + my $another_schema = My::Schema->connect( + $dsn, + $user, + $password, + $attrs, + { on_connect_do => \@on_connect_sql_statments } + ); + +See L for more information about +this and other special C-time options. -To execute some sql statements on every connect you can pass them to your schema after the connect: +=head3 Via a database handle - $schema->storage->on_connect_do(\@on_connect_sql_statments); +The supplied coderef is expected to return a single connected database handle +(e.g. a L C<$dbh>) + + my $schema = My::Schema->connect ( + sub { Some::DBH::Factory->connect }, + \%extra_attrs, + ); =head2 Basic usage Once you've defined the basic classes, either manually or using L, you can start interacting with your database. -To access your database using your $schema object, you can fetch a L -representing each of your tables by calling the ->resultset method. +To access your database using your $schema object, you can fetch a +L representing each of your tables by +calling the C method. The simplest way to get a record is by primary key: my $album = $schema->resultset('Album')->find(14); -This will run a C with C in the C clause, and +return an instance of C that represents this row. Once you +have that row, you can access and update columns: $album->title('Physical Graffiti'); my $title = $album->title; # $title holds 'Physical Graffiti' -If you prefer, you can use the C and C -accessors instead: +If you prefer, you can use the C and C accessors +instead: $album->set_column('title', 'Presence'); $title = $album->get_column('title'); -Just like with L, you call C to commit your -changes to the database: +Just like with L, you call C to save your changes to the +database (by executing the actual C statement): $album->update; -If needed, you can throw away your local changes like this: +If needed, you can throw away your local changes: $album->discard_changes if $album->is_changed; -As you can see, C allows you to check if there are local -changes to your object. +As you can see, C 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 C -method. It returns an instance of C that can be -used to access the data in the new record: +To create a new record in the database, you can use the C method. It +returns an instance of C that can be used to access the data +in the new record: - my $new_album = $schema->resultset('Album')->create({ + my $new_album = $schema->resultset('Album')->create({ title => 'Wish You Were Here', artist => 'Pink Floyd' }); @@ -284,27 +304,26 @@ Now you can add data to the new record: $new_album->year('1975'); $new_album->update; -Likewise, you can remove it from the database like this: +Likewise, you can remove it from the database: $new_album->delete; -You can also remove records without retrieving them first, by calling -delete directly on a ResultSet object. +You can also remove records without retrieving them first, by calling delete +directly on a ResultSet object. # Delete all of Falco's albums $schema->resultset('Album')->search({ artist => 'Falco' })->delete; =head2 Finding your objects -L provides a few different ways to retrieve data from -your database. Here's one example: +L provides a few different ways to retrieve data from your +database. Here's one example: # Find all of Santana's albums my $rs = $schema->resultset('Album')->search({ artist => 'Santana' }); -In scalar context, as above, C returns a -L object. It can be used to peek at the first -album returned by the database: +In scalar context, as above, C returns a L +object. It can be used to peek at the first album returned by the database: my $album = $rs->first; print $album->title; @@ -321,11 +340,7 @@ Or, you can update them all at once: $rs->update({ year => 2001 }); -For more information on what you can do with a -L, see L. - -In list context, the C method returns all of the matching -rows: +In list context, the C method returns all of the matching rows: # Fetch immediately all of Carlos Santana's albums my @albums = $schema->resultset('Album')->search( @@ -340,20 +355,20 @@ We also provide a handy shortcut for doing a C search: # Find albums whose artist starts with 'Jimi' my $rs = $schema->resultset('Album')->search_like({ artist => 'Jimi%' }); -Or you can provide your own C clause, like: +Or you can provide your own C clause: # Find Peter Frampton albums from the year 1986 my $where = 'artist = ? AND year = ?'; my @bind = ( 'Peter Frampton', 1986 ); my $rs = $schema->resultset('Album')->search_literal( $where, @bind ); -The preferred way to generate complex queries is to provide a -L construct to C: +The preferred way to generate complex queries is to provide a L +construct to C: my $rs = $schema->resultset('Album')->search({ artist => { '!=', 'Janis Joplin' }, year => { '<' => 1980 }, - albumid => [ 1, 14, 15, 65, 43 ] + albumid => { '-in' => [ 1, 14, 15, 65, 43 ] } }); This results in something like the following C clause: @@ -362,8 +377,7 @@ This results in something like the following C clause: AND year < 1980 AND albumid IN (1, 14, 15, 65, 43) -For more examples of complex queries, see -L. +For more examples of complex queries, see L. The search can also be modified by passing another hash with attributes: @@ -375,9 +389,20 @@ attributes: C<@albums> then holds the two most recent Bob Marley albums. +For more information on what you can do with a L, see +L. + For a complete overview of the available attributes, see L. +=head1 NOTES + +=head2 Problems on RHEL5/CentOS5 + +There used to be an issue with the system perl on Red Hat Enterprise +Linux 5, some versions of Fedora and derived systems. Further +information on this can be found in L + =head1 SEE ALSO =over 4