-=head1 NAME
+=head1 NAME
-DBIx::Class::Manual::FAQ - Frequently Asked Questions
+DBIx::Class::Manual::FAQ - Frequently Asked Questions (in theory)
-=head1 General
+=head1 DESCRIPTION
-=head2 What is the point of this module? Is it a fork of Class::DBI?
+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.
-This is an alternative to Class::DBI, intended to provide greater
-functionality and simplicity.
+=head1 FAQs
-It is inspired by the Class::DBI framework, and meant to support
-compability with it, while restructuring the internals and making it
-possible to support some new features like self-joins, distinct, group
-bys and more.
+How Do I:
-=head2 Who's the intended audience for this module?
+=head2 Getting started
-=head2 What databases does it support?
+=over 4
-At least MSSQL, MySQL, Oracle, PostgreSQL and SQLite.
+=item .. create a database to use?
-=head2 What's the current status of this module?
+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).
-This project is still at an early stage, so the maintainers don't make
-any absolute promise that full backwards-compatibility will be
-supported; however, if we can without compromising the improvements
-we're trying to make, we will, and any non-compatible changes will
-merit a full justification on the mailing list and a CPAN developer
-release for people to test against.
+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>.
-=head2 What's planned in the future?
+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.
-=head2 Where can I go for support?
+=item .. use DBIx::Class with L<Catalyst>?
- Mailing list: http://lists.rawmode.org/mailman/listinfo/dbix-class/
+Install L<Catalyst::Model::DBIC::Schema> from CPAN. See it's
+documentation, or below, for further details.
- SVN: http://dev.catalyst.perl.org/repos/bast/trunk/DBIx-Class/
+=item .. set up my DBIx::Class classes automatically from my database?
- Wiki: http://dbix-class.shadowcatsystems.co.uk/
+Install L<DBIx::Class::Schema::Loader> from CPAN, and read it's documentation.
- IRC: irc.perl.org#dbix-class
+=item .. set up my DBIx::Class classes manually?
-=head1 PostgresQL Specific Problems
+Look at the L<DBIx::Class::Manual::Example>, come back here if you get lost.
-=head2 Can't get last insert id - inserts with serial primary keys fail
+=item .. create my database tables from my DBIx::Class schema?
-Older DBI and DBD::Pg versions fail to correctly handle
-C<last_insert_id> correctly, causing code that uses auto incrementing
-primary key columns to fail with a message such as:-
+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>.
- Can't get last insert id at /.../DBIx/Class/Row.pm line 95
+=back
-In particular the RHEL 4 and FC3 Linux distributions both ship with
-combinations of DBI and DBD::Pg modules that do not work correctly.
+=head2 Relationships
-DBI version 1.50 and DBD::Pg 1.43 are known to work.
+=over 4
-=cut
+=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?
+
+=item .. search using database functions?
+
+=item .. sort the results of my search?
+
+=item .. group the results of my search?
+
+=item .. filter the results of my search?
+
+=item .. search in several tables simultaneously?
+
+=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
projects / dbsrgits/DBIx-Class.git / blobdiff