Disable _is_unique_query check in single() since it can't infer properly yet

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

=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 .. 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 .. sort 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<order_by>, as you did to C<select>.

=item .. group the results of my search?

Supply a list of columns you want to group on, to the C<group_by>
attribute, see L<DBIx::Class::ResultSet/group_by>.

=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

=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