-=head1 Frequetly Asked Questions
+=head1 NAME
+
+DBIx::Class::Manual::FAQ - Frequently Asked Questions (in theory)
+
+=head1 DESCRIPTION
+
+This document is intended as an anti-map of the documentation. If you
+know what you want to do, but not how to do it in L<DBIx::Class>, then
+look here. It does B<not> contain any code or examples, it just gives
+explanations and pointers to the correct pieces of documentation to
+read.
+
+=head1 FAQs
+
+How Do I:
+
+=head2 Getting started
+
+=over 4
+
+=item .. create a database to use?
+
+First, choose a database. For testing/experimenting, we reccommend
+L<DBD::SQLite>, which is a self-contained small database. (i.e. all
+you need to do is to install the DBD from CPAN, and it's usable).
+
+Next, spend some time defining which data you need to store, and how
+it relates to the other data you have. For some help on normalisation,
+go to L<http://b62.tripod.com/doc/dbbase.htm> or
+L<http://209.197.234.36/db/simple.html>.
+
+Now, decide whether you want to have the database itself be the
+definitive source of information about the data layout, or your
+DBIx::Class schema. If it's the former, look up the documentation for
+your database, eg. L<http://sqlite.org/lang_createtable.html>, on how
+to create tables, and start creating them. For a nice universal
+interface to your database, you can try L<DBI::Shell>. If you decided
+on the latter choice, read the FAQ on setting up your classes
+manually, and the one on creating tables from your schema.
+
+=item .. use DBIx::Class with L<Catalyst>?
+
+Install L<Catalyst::Model::DBIC::Schema> from CPAN. See it's
+documentation, or below, for further details.
+
+=item .. set up my DBIx::Class classes automatically from my database?
+
+Install L<DBIx::Class::Schema::Loader> from CPAN, and read it's documentation.
+
+=item .. set up my DBIx::Class classes manually?
+
+Look at the L<DBIx::Class::Manual::Example>, come back here if you get lost.
+
+=item .. create my database tables from my DBIx::Class schema?
+
+Create your classes manually, as above. Write a script that calls
+L<DBIx::Class::Schema/deploy>. See there for details, or the
+L<DBIx::Class::Manual::Cookbook>.
+
+=item .. connect to my database?
+
+Once you have created all the appropriate table/source classes, and an
+overall L<DBIx::Class::Schema|"Schema"> class, you can start using
+them in an application. To do this, you need to create a central
+Schema object, which is used to access all the data in the various
+tables. See L<DBIx::Class::Schema/connect> for details. The actual
+connection does not happen until you actually request data, so don't
+be alarmed if the error from incorrect connection details happens a
+lot later.
+
+
+=back
+
+=head2 Relationships
+
+=over 4
+
+=item .. tell DBIx::Class about relationships between my tables?
+
+There are a vareity of relationship types that come pre-defined for you to use. These are all listed in L<DBIx::Class::Relationship>. If you need a non-standard type, or more information, look in L<DBIx::Class::Relationship::Base>.
+
+=item .. define a one-to-many relationship?
+
+This is called a C<has_many> relationship on the one side, and a C<belongs_to> relationship on the many side. Currently these need to be set up individually on each side. See L<DBIx::Class::Relationship> for details.
+
+=item .. define a relationship where this table contains another table's primary key? (foreign key)
+
+Create a C<belongs_to> relationship for the field containing the foreign key. L<DBIx::Class::Relationship/belongs_to>.
+
+=item .. define a foreign key relationship where the key field may contain NULL?
+
+Just create a C<belongs_to> relationship, as above. If
+the column is NULL then the inflation to the foreign object will not
+happen. This has a side effect of not always fetching all the relevant
+data, if you use a nullable foreign-key relationship in a JOIN, then
+you probably want to set the join_type to 'left'.
+
+=item .. define a relationship where the key consists of more than one column?
+
+Instead of supplying a single column name, all relationship types also
+allow you to supply a hashref containing the condition across which
+the tables are to be joined. The condition may contain as many fields
+as you like. See L<DBIx::Class::Relationship::Base>.
+
+=item .. define a relatiopnship across an intermediate table? (many-to-many)
+
+Read the documentation on L<DBIx::Class::Relationship/many_to_many>.
+
+=item .. stop DBIx::Class from attempting to cascade deletes on my has_many relationships?
+
+By default, DBIx::Class cascades deletes and updates across
+C<has_many> relationships. If your database already does this (and
+probably better), turn it off by supplying C<< cascade_delete => 0 >> in
+the relationship attributes. See L<DBIx::Class::Relationship::Base>.
+
+=item .. use a relationship?
+
+Use it's name. An accessor is created using the name. See examples in L<DBIx::Class::Manual::Cookbook/Using relationships>.
+
+=back
+
+=head2 Searching
=over 4
-=item What is the point of this module? Is it a fork of Class::DBI?
+=item .. search for data?
+
+Create a C<$schema> object, as mentioned above in ".. connect to my
+database". Find the
+L<DBIx::Class::Manual::Glossary/ResultSet|"ResultSet"> that you want
+to search in, and call C<search> on it. See
+L<DBIx::Class::ResultSet/search>.
+
+=item .. search using database functions?
+
+Supplying something like:
+
+ ->search({'mydatefield' => 'now()'})
+
+to search, will probably not do what you expect. It will quote the
+text "now()", instead of trying to call the function. To provide
+literal, unquoted text you need to pass in a scalar reference, like
+so:
+
+ ->search({'mydatefield' => \'now()'})
+
+=item .. sort the results of my search?
+
+Supply a list of columns you want to sort by, to the C<order_by>
+attribute, see L<DBIx::Class::ResultSet/order_by>.
-=item Who's the intended audience for this module?
+=item .. sort my results based on fields I've aliased using C<as>?
-=item What databases does it support?
+You don't. You'll need to supply the same functions/expressions to
+C<order_by>, as you did to C<select>.
-=item What's the current status of this module?
+=item .. group the results of my search?
-=item What's planned in the future?
+Supply a list of columns you want to group on, to the C<group_by>
+attribute, see L<DBIx::Class::ResultSet/group_by>.
-=item Where can I go for support?
+=item .. group my results based on fields I've aliased using C<as>?
+
+You don't. You'll need to supply the same functions/expressions to
+C<group_by>, as you did to C<select>.
+
+=item .. filter the results of my search?
+
+=item .. search in several tables simultaneously?
+
+=item .. create joins with conditions other than column equality?
+
+=item .. search using greater-than or less-than and database functions?
+NOT
+ my $interval = "now() - interval '12 hours'";
+ last_attempt => { '<' => \$interval },
+BUT
+08:44 <@castaway> my $interval = "< now() - interval '12 hours'"; ..
+ last_attempt => \$interval ,
+
+
+=item .. find more help on constructing searches?
+
+Behind the scenes, DBIx::Class uses L<SQL::Abstract> to help construct
+it's SQL searches. So if you fail to find help in the
+L<DBIx::Class::Manual::Cookbook>, try looking in the SQL::Abstract
+documentation.
=back
-=cut
+=head2 Fetching data
+
+=over 4
+
+=item .. fetch as much data as possible in as few select calls as possible? (prefetch)
+See the prefetch examples in the L<DBIx::Class::Manual::Cookbook|"Cookbook">.
+
+=back
+
+=head2 Inserting and updating data
+
+=over 4
+
+=item .. insert many rows of data efficiently?
+
+=item .. update a collection of rows at the same time?
+
+=item .. use database functions when updating rows?
+
+=item .. update a column using data from another column?
+
+=back
+
+=head2 Misc
+
+=over 4
+
+=item How do I store my own (non-db) data in my DBIx::Class objects?
+
+=item How do I use DBIx::Class objects my TT templates?
+
+=item See the SQL statements my code is producing?
+
+=item Why didn't my search run any SQL?
+
+
+=back
projects / dbsrgits/DBIx-Class-Historic.git / blobdiff