[Bast-commits] r4515 -
trunk/DBIx-Class-Tutorial/lib/DBIx/Class/Tutorial
castaway at dev.catalyst.perl.org
castaway at dev.catalyst.perl.org
Wed Jun 25 13:35:16 BST 2008
Author: castaway
Date: 2008-06-25 13:35:15 +0100 (Wed, 25 Jun 2008)
New Revision: 4515
Modified:
trunk/DBIx-Class-Tutorial/lib/DBIx/Class/Tutorial/Part1.pod
trunk/DBIx-Class-Tutorial/lib/DBIx/Class/Tutorial/Part2.pod
trunk/DBIx-Class-Tutorial/lib/DBIx/Class/Tutorial/Part3.pod
Log:
Current versions
Modified: trunk/DBIx-Class-Tutorial/lib/DBIx/Class/Tutorial/Part1.pod
===================================================================
--- trunk/DBIx-Class-Tutorial/lib/DBIx/Class/Tutorial/Part1.pod 2008-06-25 10:52:30 UTC (rev 4514)
+++ trunk/DBIx-Class-Tutorial/lib/DBIx/Class/Tutorial/Part1.pod 2008-06-25 12:35:15 UTC (rev 4515)
@@ -4,9 +4,10 @@
=head1 DESCRIPTION
-This is part one of a DBIx::Class tutorial I started writing for the
-folks at work, I hope to turn it into a multi-part releasable
-document.
+This is part one of a DBIx::Class tutorial. In which you should learn
+how to create a set of DBIx::Class files from an existing database,
+and do some simple searching, inserting, updating and deleting. More
+complex things come later.
=head1 GLOSSARY
@@ -19,42 +20,36 @@
=item Schema
The schema object is the main point of contact with the rest of
-DBIx::Class, we create one initially using the database's connection
-details, and keep it around until we are completely done with the
-database.
+DBIx::Class. A schema is created initially using the database's
+connection details, and is kept around until we are completely done
+with the database. Although the schema is passed the connection
+details, it does not use them until we actually ask for data via a
+resultset.
-A L<DBIx::Class::Schema> object is created by calling C<< ->connect >>
-on our Schema subclass, and passing it the DSN (and other possible
-values, see L<DBIx::Class::Schema>). Eg: C<< my $schema =
-Breadcrumbs::Schema->connect('dbi:mysql;dbname=Breadcrumbs',
-'user', 'passwd'); >>
+=item Result class
-NB: Creating this object does not attempt to connect to the database
-yet.
+A class whose objects represent a single result from a resultset,
+usually corresponding to a single row of a table. Result classes are
+defined by calls to class methods proxyied from
+L<DBIx::Class::ResultSource>. These populate an instance of a table
+(Result source) object, with column and relation metadata.
-NB2: To make use of an existing mechanism to store credentials for
-databases, we can do: C<< my $schema = Breadcrumbs::Schema->connect(
-sub { get_dbh('Breadcrumbs') } ); >>.
-
=item ResultSet
A L<DBIx::Class::ResultSet>, an object which represents a database
query, including all conditions/clauses. Creating one does not run the
associated query, it is stored and used when actual data objects are
-requested. The simplest form of ResultSet represents an entire table,
-and can be retrieved from the schema object like this: C<< my $rs =
-$schema->resultset('Path') >>.
+requested. The simplest form of ResultSet represents an entire
+table. Actual data is returned from a ResultSet in the form of a Row
+or a ResultSetColumn.
-=item Result class
-
-A class whose objects represent a single result from a resultset,
-usually corresponding to a single row of a table.
-
=item Row
-A L<DBIx::Class::Row> represents an actual row of data resulting
-from a database query. This could be an entire row, or just certain
-fields as restricted by a ResultSet.
+A L<DBIx::Class::Row> represents an actual row of data resulting from
+a database query. This could be an entire row, or just certain fields
+as restricted by a ResultSet. Fields in the Row object are as
+described by its L</Result class>. A Row object can be used to update
+and delete data.
=head1 GETTING STARTED
@@ -76,13 +71,19 @@
the L<DBIx::Class::Schema> file.
The table files will contain information about the columns and their
-types. If the (mysql) database is innodb, it will also extract
-relationships based on foreign key references etc. An md5 sum of the
-contents is added, so that the user can add more relations or other
-methods to the file, and a later update will not overwrite them.
+types. If the database is supports foreign keysN<mysql's myisam table
+type doesn't for example>, it will also extract relationships based on
+foreign key references etc. An md5 sum of the contents is added, so
+that the user can add more relations or other methods to the file, and
+a later update will not overwrite them.
Look in the files that have been created. For help on what has been
-created, see L<DBIx::Class::ResultSource>.
+created, see L<DBIx::Class::ResultSource>. For some databases, the
+schema loader may not have been able to correctly determine your table
+relationships, and you will have to enter your them by hand. You can
+also create relationships in your ResultSource classes that don't
+exist in the database. For how to set relationships, see
+L<Part2|DBIx::Class::Tutorial::Part2>.
=head2 If the database layout changes
@@ -92,11 +93,12 @@
See L<DBIx::Class::Manual::Intro/SETTING UP DBIx::Class>.
-=head2 Setting up relationships
+=head1 Setting up relationships
-If your database is mysql and not using innodb, you will have
-to add the table relationships yourself. These are the most useful
-part of DBIx::Class, otherwise we might as well just use DBI..
+If your database is mysql with myisam tables, or for some reason
+C<Loader> could not determine your table relationships, you will have
+to add the them yourself. These are the most useful part of
+DBIx::Class, otherwise we might as well just use DBI..
There are two main/useful relationship types, for the rest and a more wordy
description, see L<DBIx::Class::Relationship>.
@@ -163,18 +165,24 @@
lang => $lang }
);
-
=head1 Creating a Schema object
To use a L<DBIx::Class> schema, you must first create a C<$schema>
object. This object must not go out of scope while you are using any
objects created from it.
+For example, to connect to a mysql database named C<breadcrumbs>:
+
my $schema = Breadcrumbs::Schema::Path->connect('dbi:mysql:dbname=breadcrumbs', 'user', 'pass');
For more information on the arguments to connect, see
L<DBIx::Class::Schema/connect_info>
+To make use of an existing mechanism to store credentials for
+databases, we can do something like:
+
+ my $schema = Breadcrumbs::Schema->connect(sub { get_dbh('Breadcrumbs') } );
+
=head1 Getting data
Whether fetching complete rows, searching for rows, or fetching data
@@ -187,7 +195,7 @@
it the B<name> of a C</Result class>.
## ResultSet for the Breadcrumbs::Schema::Name class
- $schema->resultset('Name')
+ my $name_rs = $schema->resultset('Name')
=head2 find (single row by unique key)
@@ -218,8 +226,10 @@
{ 'me.id' => 1 }, ## WHERE
{ prefetch => [ 'path' ] } ## JOIN/SELECT
-This creates a L<DBIx::Class::ResultSet>, to retrieve the actual Row object:
+This creates a L<DBIx::Class::ResultSet>, to retrieve the actual Row
+object, can can iterate over the set with C<next>.
+ ## Fetch first entry using iteration:
my $namerow = $name_rs->next;
The following SQL is executed:
@@ -227,7 +237,7 @@
SELECT me.ID, me.Name, me.LangID, me.PathID, path.ID, path.Path, path.Parent, path.Position, path.MenuID FROM Name me JOIN Path path ON ( path.ID = me.PathID ) WHERE ( me.id = ? ): '1'
L<DBIx::Class::ResultSet/prefetch> takes the B<name> of the
-relationship for the table we want to join to. In this case, the
+relationship for the table we want to join to. In this case, it is the
B<name> of the L</belongs_to> relationship we defined in the C<Name>
class earlier.
Modified: trunk/DBIx-Class-Tutorial/lib/DBIx/Class/Tutorial/Part2.pod
===================================================================
--- trunk/DBIx-Class-Tutorial/lib/DBIx/Class/Tutorial/Part2.pod 2008-06-25 10:52:30 UTC (rev 4514)
+++ trunk/DBIx-Class-Tutorial/lib/DBIx/Class/Tutorial/Part2.pod 2008-06-25 12:35:15 UTC (rev 4515)
@@ -69,6 +69,7 @@
=back
+
=head1 More about ResultSets
A Hint:
Modified: trunk/DBIx-Class-Tutorial/lib/DBIx/Class/Tutorial/Part3.pod
===================================================================
--- trunk/DBIx-Class-Tutorial/lib/DBIx/Class/Tutorial/Part3.pod 2008-06-25 10:52:30 UTC (rev 4514)
+++ trunk/DBIx-Class-Tutorial/lib/DBIx/Class/Tutorial/Part3.pod 2008-06-25 12:35:15 UTC (rev 4515)
@@ -32,7 +32,7 @@
Most databases provide a way to auto-increment a numeric column,
usually an integer column, to use as a primary key. Some allow you to
-create a sequence which can be queried for it's next value, to use as
+create a sequence which can be queried for its next value, to use as
the primary key. The difficulty with creating new rows using
auto-increment primary keys is retrieving the value of the key after a
new row has been inserted.
@@ -49,7 +49,7 @@
=head1 Dealing with Primary Keys
-L<DBIx::Class> automatically fetches primary keys from the database
+L<DBIx::Class> automatically fetches the primary key from the database
for you, and stores it in your new row object.
## Fetch a new path and print its ID:
@@ -60,8 +60,8 @@
This is done using L<last_insert_id|DBI>.
-Tables using sequences for their Primary keys should be updated using
-a trigger to update the PK value. The name of the sequence can be set
+Tables using sequences for their primary keys should be updated using
+a trigger to update the value. The name of the sequence can be set
in the L<add_columns|DBIx::Class::ResultSource/add_columns> so that
the last value can be fetched by L<DBIx::Class::PK::Auto>.
@@ -74,7 +74,7 @@
If we want to take that date and display, for example, how long since
the row was modified in days/hours/minutes, it would be useful to have
-that datetime value as a L<DateTime> object, then we can use
+that C<datetime> value as a L<DateTime> object, then we can use
L<DateTime::Duration> or similar to display the elapsed time.
To do this, we can add a new C<component> to the C<Result class>es. In
@@ -120,7 +120,7 @@
## add accessor for path column, in
## Breadcrumbs::Schema::Path
- __PACKAGE__->add_columns( ..
+ __PACKAGE__->add_columns( ...
path => {
data_type => 'varchar',
size => 255,
@@ -162,7 +162,7 @@
## Add method to check if the path exists:
sub check {
- my ($self, $root) = @_l
+ my ($self, $root) = @_;
return 1 if(-d catfile($root, $self->path));
@@ -173,7 +173,7 @@
Putting methods in your Result classes will make them available to the
Row objects. To add methods to entire resultsets, you will first need
-to subclass L<LDBIx::Class::ResultSet>.
+to subclass L<DBIx::Class::ResultSet>.
package Breadcrumbs::Schema::Path::ResultSet;
use base 'DBIx::Class::ResultSet';
More information about the Bast-commits
mailing list