=head1 DESCRIPTION
-This is an SQL to OO mapper with an object API inspired by L<Class::DBI>
+DBIx::Class (aka DBIC) is an SQL to OO mapper with an object API inspired by L<Class::DBI>
(with a compatibility layer as a springboard for porting) and a resultset API
that allows abstract encapsulation of database operations. It aims to make
representing queries in your code as perl-ish as possible while still
including retrieving related records from multiple tables in a single query,
JOIN, LEFT JOIN, COUNT, DISTINCT, GROUP BY, ORDER BY and HAVING support.
-DBIx::Class can handle multi-column primary and foreign keys, complex
+DBIC can handle multi-column primary and foreign keys, complex
queries and database-level paging, and does its best to only query the
database in order to return something you've directly asked for. If a
resultset is used as an iterator it only fetches rows off the statement
as bugs are found and fixed.
We do our best to maintain full backwards compatibility for published
-APIs, since DBIx::Class is used in production in many organisations,
+APIs, since DBIC is used in production in many organisations,
and even backwards incompatible changes to non-published APIs will be fixed
if they're reported and doing so doesn't cost the codebase anything.
=head1 COPYRIGHT
-Copyright (c) 2005 - 2011 the DBIx::Class L</AUTHOR> and L</CONTRIBUTORS>
+Copyright (c) 2005 - 2012 the DBIC L</AUTHOR> and L</CONTRIBUTORS>
as listed above.
=head1 LICENSE
=head1 REQUIREMENTS
The Admin interface has additional requirements not currently part of
-L<DBIx::Class>. See L<DBIx::Class::Optional::Dependencies> for more details.
+L<DBIC|DBIx::Class>. See L<DBIx::Class::Optional::Dependencies> for more details.
=head1 ATTRIBUTES
=head2 trace
-Toggle DBIx::Class debug output
+Toggle L<DBIC|DBIx::Class> debug output
=cut
return $cfg;
}
-=head1 AUTHOR
+=head1 AUTHOR AND CONTRIBUTORS
-See L<DBIx::Class/CONTRIBUTORS>.
+See L<AUTHOR|DBIx::Class/AUTHOR> and L<CONTRIBUTORS|DBIx::Class/CONTRIBUTORS> in DBIx::Class
=head1 LICENSE
-You may distribute this code under the same terms as Perl itself
+You may distribute this code under the same terms as Perl itself.
=cut
=head1 DESCRIPTION
-DBIx::Class features a fully featured compatibility layer with L<Class::DBI>
+L<DBIC|DBIx::Class> features a fully featured compatibility layer with L<Class::DBI>
and some common plugins to ease transition for existing CDBI users.
-This is not a wrapper or subclass of DBIx::Class but rather a series of plugins. The result being that even though you're using the Class::DBI emulation layer you are still getting DBIx::Class objects. You can use all DBIx::Class features and methods via CDBICompat. This allows you to take advantage of DBIx::Class features without having to rewrite your CDBI code.
+This is not a wrapper or subclass of L<DBIC|DBIx::Class> but rather a series of plugins. The result being that even though you're using the
+L<CDBI|Class::DBI> emulation layer you are still getting L<DBIC|DBIx::Class> objects. You can use all L<DBIC|DBIx::Class> features and methods
+via CDBICompat. This allows you to take advantage of L<DBIC|DBIx::Class> features without having to rewrite your L<CDBI|Class::DBI> code.
=head2 Plugins
-CDBICompat is good enough that many CDBI plugins will work with CDBICompat, but many of the plugin features are better done with DBIx::Class methods.
+CDBICompat is good enough that many CDBI plugins will work with CDBICompat, but many of the plugin features are better done with L<DBIC|DBIx::Class> methods.
=head3 Class::DBI::AbstractSearch
-C<search_where()> is fully emulated using DBIC's search. Aside from emulation there's no reason to use C<search_where()>.
+C<search_where()> is fully emulated using L<DBIC|DBIx::Class>'s search. Aside from emulation there's no reason to use C<search_where()>.
=head3 Class::DBI::Plugin::NoCache
=head3 Class::DBI::Sweet
-The features of CDBI::Sweet are better done using DBIC methods which are almost exactly the same. It even uses L<Data::Page>.
+The features of CDBI::Sweet are better done using L<DBIC|DBIx::Class> methods which are almost exactly the same. It even uses L<Data::Page>.
=head3 Class::DBI::Plugin::DeepAbstractSearch
-This plugin will work, but it is more efficiently done using DBIC's native search facilities. The major difference is that DBIC will not infer the join for you, you have to tell it the join tables.
+This plugin will work, but it is more efficiently done using L<DBIC|DBIx::Class>'s native search facilities. The major difference is that
+L<DBIC|DBIx::Class> will not infer the join for you, you have to tell it the join tables.
=head2 Choosing Features
Emulates the extra behaviors of the Class::DBI search iterator.
-=head2 Differences from DBIx::Class result set
+=head2 Differences from DBIC result set
The CDBI iterator returns true if there were any results, false otherwise. The DBIC result set always returns true.
=head1 NAME
-DBIx::Class::Carp - Provides advanced Carp::Clan-like warning functions for DBIx::Class internals
+DBIx::Class::Carp - Provides advanced Carp::Clan-like warning functions for DBIC internals
=head1 DESCRIPTION
=head1 NAME
-DBIx::Class::Core - Core set of DBIx::Class modules
+DBIx::Class::Core - Core set of DBIC modules
=head1 SYNOPSIS
=head1 DESCRIPTION
This class just inherits from the various modules that make up the
-L<DBIx::Class> core features. You almost certainly want these.
+L<DBIC|DBIx::Class> core features. You almost certainly want these.
The core modules currently are:
=back
-This is meant for internal use by L<DBIx::Class>'s C<throw_exception>
+This is meant for internal use by L<DBIC|DBIx::Class>'s C<throw_exception>
code, and shouldn't be used directly elsewhere.
Expects a scalar exception message. The optional argument
=head2 inflate_column
-Instruct L<DBIx::Class> to inflate the given column.
+Instruct L<DBIC|DBIx::Class> to inflate the given column.
In addition to the column name, you must provide C<inflate> and
C<deflate> methods. The C<inflate> method is called when you access
=over 4
=item L<DBIx::Class::Core> - This component is loaded as part of the
- C<core> L<DBIx::Class> components; generally there is no need to
+ C<core> L<DBIC|DBIx::Class> components; generally there is no need to
load it directly
=back
=head1 SYNOPSIS
-In your L<DBIx::Class> table class:
+In your L<DBIC|DBIx::Class> table class:
use base 'DBIx::Class::Core';
=head1 DESCRIPTION
-This is the L<DBIx::Class> users manual. DBIx::Class is a SQL->OOP mapper.
-This means that it can represent your SQL tables as perl classes, and give
-you convenient accessors and methods for retrieving and updating information
+This is the L<DBIC|DBIx::Class> users manual. L<DBIC|DBIx::Class> is a SQL->OOP
+mapper. This means that it can represent your SQL tables as perl classes, and
+give you convenient accessors and methods for retrieving and updating information
from your SQL database.
=head1 SECTIONS
=head1 NAME
-DBIx::Class::Manual::Component - Developing DBIx::Class Components
+DBIx::Class::Manual::Component - Developing DBIC Components
=head1 WHAT IS A COMPONENT
-A component is a module that can be added in to your DBIx::Class
+A component is a module that can be added in to your L<DBIC|DBIx::Class>
classes to provide extra functionality. A good example is the PK::Auto
component which automatically retrieves primary keys that the database
itself creates, after the insert has happened.
=head1 USING
Components are loaded using the load_components() method within your
-DBIx::Class classes.
+L<DBIC|DBIx::Class> classes.
package My::Thing;
use base qw( DBIx::Class::Core );
__PACKAGE__->load_components(qw/InflateColumn::DateTime TimeStamp/);
Generally you do not want to specify the full package name
-of a component, instead take off the DBIx::Class:: part of
+of a component, instead take off the C<DBIx::Class::> part of
it and just include the rest. If you do want to load a
component outside of the normal namespace you can do so
by prepending the component name with a +.
L<DBIx::Class::Manual::Cookbook>
-=head1 AUTHOR
+=head1 AUTHOR AND CONTRIBUTORS
-Aran Clary Deltac <bluefeet@cpan.org>
+See L<AUTHOR|DBIx::Class/AUTHOR> and L<CONTRIBUTORS|DBIx::Class/CONTRIBUTORS> in DBIx::Class
=head2 Paged results
-When you expect a large number of results, you can ask L<DBIx::Class> for a
+When you expect a large number of results, you can ask L<DBIC|DBIx::Class> for a
paged resultset, which will fetch only a defined number of records at a time:
my $rs = $schema->resultset('Artist')->search(
=head2 Grouping results
-L<DBIx::Class> supports C<GROUP BY> as follows:
+L<DBIC|DBIx::Class> supports C<GROUP BY> as follows:
my $rs = $schema->resultset('Artist')->search(
{},
be automatically loaded.
If however you are still using L<DBIx::Class::Schema/load_classes>, first tell
-DBIx::Class to create an instance of the ResultSet class for you, in your
+L<DBIC|DBIx::Class> to create an instance of the ResultSet class for you, in your
My::DBIC::Schema::CD class:
# class definition as normal
good idea since it requires a scan of the entire table. (Unless your RDBMS
supports indexes on expressions - including return values of functions - and
you create an index on the return value of the function in question.) However,
-it can be accomplished with C<DBIx::Class> when necessary by resorting to
+it can be accomplished with L<DBIC|DBIx::Class> when necessary by resorting to
literal SQL:
$rs->search(\[ 'YEAR(date_of_birth) = ?', [ plain_value => 1979 ] ]);
You can use the C<join> attribute to allow searching on, or sorting your
results by, one or more columns in a related table.
-This requires that you have defined the L<DBIx::Class::Relationship>. For example :
+This requires that you have defined the L<Relationship|DBIx::Class::Relationship>.
+For example:
My::Schema::CD->has_many( artists => 'My::Schema::Artist', 'artist_id');
There is a problem however. We have searched both the C<cd> and C<artist> tables
in our main query, but we have only returned data from the C<cd> table. To get
-the artist name for any of the CD objects returned, L<DBIx::Class> will go back
+the artist name for any of the CD objects returned, L<DBIC|DBIx::Class> will go back
to the database:
SELECT artist.* FROM artist WHERE artist.id = ?
main query. Five CDs, five extra queries. A hundred CDs, one hundred extra
queries!
-Thankfully, L<DBIx::Class> has a C<prefetch> attribute to solve this problem.
+Thankfully, L<DBIC|DBIx::Class> has a C<prefetch> attribute to solve this problem.
This allows you to fetch results from related tables in advance:
my $rs = $schema->resultset('CD')->search(
print "CD: " . $cd->title . ", Artist: " . $cd->artist->name;
}
-L<DBIx::Class> has now prefetched all matching data from the C<artist> table,
+L<DBIC|DBIx::Class> has now prefetched all matching data from the C<artist> table,
so no additional SQL statements are executed. You now have a much more
efficient query.
# do whatever else you wanted if it was a new row
}
-=head2 Static sub-classing DBIx::Class result classes
+=head2 Static sub-classing DBIC result classes
AKA adding additional relationships/methods/etc. to a model for a
specific usage of the (shared) model.
1;
-=head2 Dynamic Sub-classing DBIx::Class proxy classes
+=head2 Dynamic Sub-classing DBIC proxy classes
AKA multi-class object inflation from one table
-L<DBIx::Class> classes are proxy classes, therefore some different
+L<DBIC|DBIx::Class> classes are proxy classes, therefore some different
techniques need to be employed for more than basic subclassing. In
this example we have a single user table that carries a boolean bit
for admin. We would like like to give the admin users
=head2 Skip result object creation for faster results
-DBIx::Class is not built for speed, it's built for convenience and
+L<DBIC|DBIx::Class> is not built for speed, it's built for convenience and
ease of use, but sometimes you just need to get the data, and skip the
fancy objects.
=head2 Get raw data for blindingly fast results
If the L<HashRefInflator|DBIx::Class::ResultClass::HashRefInflator> solution
-above is not fast enough for you, you can use a DBIx::Class to return values
+above is not fast enough for you, you can use L<DBIC|DBIx::Class> to return values
exactly as they come out of the database with none of the convenience methods
wrapped round them.
1;
-By overridding the L<connection|DBIx::Class::Schama/connection>
-method and extracting a custom option from the provided \%attr hashref one can
+By overridding the L<connection|DBIx::Class::Schema/connection>
+method and extracting a custom option from the provided \%attr hashref, one can
then simply iterate over all the Schema's ResultSources, renaming them as
needed.
To use this facility, simply add or modify the \%attr hashref that is passed to
-L<connection|DBIx::Class::Schama/connect>, as follows:
+L<connection|DBIx::Class::Schema/connect>, as follows:
my $schema
= MyDatabase::Schema->connect(
=head2 Schema versioning
-The following example shows simplistically how you might use DBIx::Class to
-deploy versioned schemas to your customers. The basic process is as follows:
+The following example shows simplistically how you might use L<DBIC|DBIx::Class>
+to deploy versioned schemas to your customers. The basic process is as follows:
=over 4
=item 1.
-Create a DBIx::Class schema
+Create a L<DBIC schema|DBIx::Class::Schema>
=item 2.
As your application evolves, it may be necessary to modify your schema
to change functionality. Once the changes are made to your schema in
-DBIx::Class, export the modified schema and the conversion scripts as
-in L</Creating DDL SQL>.
+L<DBIC|DBIx::Class>, export the modified schema and the conversion scripts
+as in L</Creating DDL SQL>.
B<Deploy update to customers>
See L<SQL::Abstract/array_datatypes> and L<SQL::Abstract/Literal SQL with
placeholders and bind values (subqueries)> for more explanation. Note that
-L<DBIx::Class> sets L<SQL::Abstract/bindtype> to C<columns>, so you must pass
+L<DBIC|DBIx::Class> sets L<SQL::Abstract/bindtype> to C<columns>, so you must pass
the bind values (the C<[1, 2, 3]> arrayref in the above example) wrapped in
arrayrefs together with the column name, like this:
C<< [column_name => value] >>.
The Catalyst Wiki Unicode page at
L<http://wiki.catalystframework.org/wiki/tutorialsandhowtos/using_unicode>
has additional information on the use of Unicode with Catalyst and
-DBIx::Class.
+L<DBIC|DBIx::Class>.
The following databases do correctly handle unicode data:-
=head2 Easy migration from class-based to schema-based setup
-You want to start using the schema-based approach to L<DBIx::Class>
+You want to start using the schema-based approach to L<DBIC|DBIx::Class>
(see L<DBIx::Class::Manual::Intro/Setting it up manually>), but have an
established class-based setup with lots of existing classes that you don't
want to move by hand. Try this nifty script instead:
=head1 OVERLOADING METHODS
-L<DBIx::Class> uses the L<Class::C3> package, which provides for redispatch of
+L<DBIC|DBIx::Class> uses the L<Class::C3> package, which provides for redispatch of
method calls, useful for things like default values and triggers. You have to
use calls to C<next::method> to overload methods. More information on using
-L<Class::C3> with L<DBIx::Class> can be found in
+L<Class::C3> with L<DBIC|DBIx::Class> can be found in
L<DBIx::Class::Manual::Component>.
=head2 Setting default values for a row
documentation. See also L<DBIx::Class::Manual::Component> for more
ways to write your own base classes to do this.
-People looking for ways to do "triggers" with DBIx::Class are probably
+People looking for ways to do "triggers" with L<DBIC|DBIx::Class> are probably
just looking for this.
=head2 Changing one field whenever another changes
=head1 DEBUGGING AND PROFILING
-=head2 DBIx::Class objects with Data::Dumper
+=head2 DBIC objects with Data::Dumper
L<Data::Dumper> can be a very useful tool for debugging, but sometimes it can
be hard to find the pertinent data in all the data it can generate.
=head1 STARTUP SPEED
-L<DBIx::Class|DBIx::Class> programs can have a significant startup delay
+L<DBIC|DBIx::Class> programs can have a significant startup delay
as the ORM loads all the relevant classes. This section examines
techniques for reducing the startup delay.
=head2 Move Common Startup into a Base Class
-Typically L<DBIx::Class> result classes start off with
+Typically L<DBIC|DBIx::Class> result classes start off with
use base qw/DBIx::Class::Core/;
__PACKAGE__->load_components(qw/InflateColumn::DateTime/);
=head2 Cached statements
-L<DBIx::Class> normally caches all statements with L<< prepare_cached()|DBI/prepare_cached >>.
+L<DBIC|DBIx::Class> normally caches all statements with L<< prepare_cached()|DBI/prepare_cached >>.
This is normally a good idea, but if too many statements are cached, the database may use too much
memory and may eventually run out and fail entirely. If you suspect this may be the case, you may want
to examine DBI's L<< CachedKids|DBI/CachedKidsCachedKids_(hash_ref) >> hash:
=item L<DBIx::Class::Manual::Example> - Full example Schema.
-=item L<DBIx::Class::Manual::SQLHackers> - How to use DBIx::Class if you know SQL (external, available on CPAN)
+=item L<DBIx::Class::Manual::SQLHackers> - How to use DBIC if you know SQL (external, available on CPAN)
=item L<DBIx::Class::Manual::Glossary> - What do all those terms mean?
=head2 Installation
-Install DBIx::Class via CPAN should be sufficient.
+Install L<DBIC|DBIx::Class> via CPAN should be sufficient.
=head3 Create the database/tables
=head1 Notes
A reference implementation of the database and scripts in this example
-are available in the main distribution for DBIx::Class under the
+are available in the main distribution for L<DBIC|DBIx::Class> under the
directory F<t/examples/Schema>.
With these scripts we're relying on @INC looking in the current
=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
+know what you want to do, but not how to do it in L<DBIC|DBIx::Class>, then
look here. It does B<not> contain much code or examples, it just gives
explanations and pointers to the correct pieces of documentation to
read.
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
+L<DBIC schema|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>?
+=item .. use DBIC with L<Catalyst>?
Install L<Catalyst::Model::DBIC::Schema> from CPAN. See its
documentation, or below, for further details.
-=item .. set up my DBIx::Class classes automatically from my database?
+=item .. set up my DBIC classes automatically from my database?
Install L<DBIx::Class::Schema::Loader> from CPAN, and read its documentation.
-=item .. set up my DBIx::Class classes manually?
+=item .. set up my DBIC classes manually?
Look at the L<DBIx::Class::Manual::Example> and come back here if you get lost.
-=item .. create my database tables from my DBIx::Class schema?
+=item .. create my database tables from my DBIC schema?
Create your classes manually, as above. Write a script that calls
L<DBIx::Class::Schema/deploy>. See there for details, or the
be alarmed if the error from incorrect connection details happens a
lot later.
-=item .. use DBIx::Class across multiple databases?
+=item .. use DBIC across multiple databases?
If your database server allows you to run querys across multiple
-databases at once, then so can DBIx::Class. All you need to do is make
-sure you write the database name as part of the
+databases at once, then so can L<DBIC|DBIx::Class>. All you need to do
+is make sure you write the database name as part of the
L<DBIx::Class::ResultSource/table> call. Eg:
__PACKAGE__->table('mydb.mytablename');
And load all the Result classes for both / all databases using one
L<DBIx::Class::Schema/load_namespaces> call.
-=item .. use DBIx::Class across PostgreSQL/DB2/Oracle schemas?
+=item .. use DBIC across PostgreSQL/DB2/Oracle schemas?
Add the name of the schema to the L<DBIx::Class::ResultSource/table>
as part of the name, and make sure you give the one user you are going
=over 4
-=item .. tell DBIx::Class about relationships between my tables?
+=item .. tell DBIC about relationships between my tables?
There are a variety of relationship types that come pre-defined for
you to use. These are all listed in L<DBIx::Class::Relationship>. If
The term 'relationship' is used loosely with many_to_many as it is not considered a
relationship in the fullest sense. For more info, read the documentation on L<DBIx::Class::Relationship/many_to_many>.
-=item .. stop DBIx::Class from attempting to cascade deletes on my has_many and might_have relationships?
+=item .. stop DBIC from attempting to cascade deletes on my has_many and might_have relationships?
-By default, DBIx::Class cascades deletes and updates across
+By default, L<DBIC|DBIx::Class> cascades deletes and updates across
C<has_many> and C<might_have> relationships. You can disable this
behaviour on a per-relationship basis by supplying
C<< cascade_delete => 0 >> in the relationship attributes.
The cascaded operations are performed after the requested delete or
update, so if your database has a constraint on the relationship, it
will have deleted/updated the related records or raised an exception
-before DBIx::Class gets to perform the cascaded operation.
+before L<DBIC|DBIx::Class> gets to perform the cascaded operation.
See L<DBIx::Class::Relationship>.
=item .. create joins with conditions other than column equality?
-Currently, L<DBIx::Class> can only create join conditions using
+Currently, L<DBIC|DBIx::Class> can only create join conditions using
equality, so you're probably better off creating a C<view> in your
database, and using that as your source. A C<view> is a stored SQL
query, which can be accessed similarly to a table, see your database
=item .. find more help on constructing searches?
-Behind the scenes, DBIx::Class uses L<SQL::Abstract> to help construct
+Behind the scenes, L<DBIC|DBIx::Class> uses L<SQL::Abstract> to help construct
its SQL searches. So if you fail to find help in the
L<DBIx::Class::Manual::Cookbook>, try looking in the SQL::Abstract
documentation.
=over 4
-=item How do I store my own (non-db) data in my DBIx::Class objects?
+=item How do I store my own (non-db) data in my DBIC objects?
You can add your own data accessors to your Result classes.
One method is to use the built in mk_group_accessors (via L<Class::Accessor::Grouped>)
- package App::Schema::Result::MyTable;
+ package App::Schema::Result::MyTable;
- use parent 'DBIx::Class::Core';
+ use parent 'DBIx::Class::Core';
- __PACKAGE__->table('foo'); #etc
- __PACKAGE__->mk_group_accessors('simple' => qw/non_column_data/); # must use simple group
+ __PACKAGE__->table('foo'); #etc
+ __PACKAGE__->mk_group_accessors('simple' => qw/non_column_data/); # must use simple group
-An another method is to use L<Moose> with your L<DBIx::Class> package.
+An another method is to use L<Moose> with your L<DBIC|DBIx::Class> package.
- package App::Schema::Result::MyTable;
+ package App::Schema::Result::MyTable;
- use Moose; # import Moose
- use Moose::Util::TypeConstraint; # import Moose accessor type constraints
+ use Moose; # import Moose
+ use Moose::Util::TypeConstraint; # import Moose accessor type constraints
- extends 'DBIx::Class::Core'; # Moose changes the way we define our parent (base) package
+ extends 'DBIx::Class::Core'; # Moose changes the way we define our parent (base) package
- has 'non_column_data' => ( is => 'rw', isa => 'Str' ); # define a simple attribute
+ has 'non_column_data' => ( is => 'rw', isa => 'Str' ); # define a simple attribute
- __PACKAGE__->table('foo'); # etc
+ __PACKAGE__->table('foo'); # etc
With either of these methods the resulting use of the accesssor would be
- my $row;
+ my $row;
- # assume that somewhere in here $row will get assigned to a MyTable row
+ # assume that somewhere in here $row will get assigned to a MyTable row
- $row->non_column_data('some string'); # would set the non_column_data accessor
+ $row->non_column_data('some string'); # would set the non_column_data accessor
- # some other stuff happens here
+ # some other stuff happens here
- $row->update(); # would not inline the non_column_data accessor into the update
+ $row->update(); # would not inline the non_column_data accessor into the update
-=item How do I use DBIx::Class objects in my TT templates?
+=item How do I use DBIC objects in my TT templates?
-Like normal objects, mostly. However you need to watch out for TT
-calling methods in list context. When calling relationship accessors
+Like normal objects, mostly. However, you need to watch out for TT
+calling methods in list context. When calling relationship accessors,
you will not get resultsets, but a list of all the related objects.
Use the L<DBIx::Class::ResultSet/search_rs> method, or the
=item See the SQL statements my code is producing?
Set the shell environment variable C<DBIC_TRACE> to a true value.
+B<< Not the C<DBI_TRACE> variable; >> this has to do with debugging
+on the L<DBI> end of things.
For more info see L<DBIx::Class::Storage> for details of how
to turn on debugging in the environment, pass your own filehandle to
=item Why didn't my search run any SQL?
-L<DBIx::Class> runs the actual SQL statement as late as possible, thus
+L<DBIC|DBIx::Class> runs the actual SQL statement as late as possible, thus
if you create a resultset using C<search> in scalar context, no query
is executed. You can create further resultset refinements by calling
search again or relationship accessors. The SQL query is only run when
=item How do I deal with tables that lack a primary key?
-If your table lacks a primary key, DBIx::Class can't work out which row
+If your table lacks a primary key, L<DBIC|DBIx::Class> can't work out which row
it should operate on, for example to delete or update. However, a
-UNIQUE constraint on one or more columns allows DBIx::Class to uniquely
+UNIQUE constraint on one or more columns allows L<DBIC|DBIx::Class> to uniquely
identify the row, so you can tell L<DBIx::Class::ResultSource> these
columns act as a primary key, even if they don't from the database's
point of view:
=item How do I reduce the overhead of database queries?
-You can reduce the overhead of object creation within L<DBIx::Class>
+You can reduce the overhead of object creation within L<DBIC|DBIx::Class>
using the tips in L<DBIx::Class::Manual::Cookbook/"Skip result object creation for faster results">
and L<DBIx::Class::Manual::Cookbook/"Get raw data for blindingly fast results">
=head1 NAME
-DBIx::Class::Manual::Features - A boatload of DBIx::Class features with links to respective documentation
+DBIx::Class::Manual::Features - A boatload of DBIC features with links to respective documentation
=head1 META
=head1 General ORM
These are things that are in most other ORMs, but are still reasons to use
-DBIC over raw SQL.
+L<DBIC|DBIx::Class> over raw SQL.
=head2 Cross DB
=back
-=head1 DBIx::Class Specific Features
+=head1 DBIC Specific Features
These things may be in other ORM's, but they are very specific, so doubtful
=head2 ->deploy
-Create a database from your DBIx::Class schema.
+Create a database from your L<DBIC schema|DBIx::Class::Schema>.
my $schema = Frew::Schema->connect( $dsn, $user, $pass );
=head2 Schema::Loader
-Create a DBIx::Class schema from your database.
+Create a L<DBIC schema|DBIx::Class::Schema> from your database.
package Frew::Schema;
=head2 Extensible
-DBIx::Class helped pioneer fast MI in Perl 5 with Class::C3, so it is made to
+L<DBIC|DBIx::Class> helped pioneer fast MI in Perl 5 with Class::C3, so it is made to
allow extensions to nearly every part of it.
=head2 Extensibility example: DBIx::Class::Helpers
=head1 DBIx::Class TERMS
+=head2 DBIC
+
+Shorthand for L<DBIx::Class>.
+
=head2 DB schema
Refers to a single physical schema within an RDBMS. Synonymous with the terms
=head2 Inflation
The act of turning database row data into objects in
-language-space. DBIx::Class result classes can be set up to inflate
-your data into perl objects which more usefully represent their
-contents. For example: L<DBIx::Class::InflateColumn::DateTime> for
+language-space. L<DBIC result classes|DBIx::Class::Manual::ResultClass> can
+be set up to inflate your data into Perl objects which more usefully represent
+their contents. For example: L<DBIx::Class::InflateColumn::DateTime> for
datetime or timestamp column data.
See also L<DBIx::Class::InflateColumn>.
=head2 Deflation
-The opposite of L</Inflation>. Existing perl objects that represent
-column values can be passed to DBIx::Class methods to store into the
-database. For example a L<DateTime> object can be automatically
+The opposite of L</Inflation>. Existing Perl objects that represent
+column values can be passed to L<DBIC|DBIx::Class> methods to store into the
+database. For example, a L<DateTime> object can be automatically
deflated into a datetime string for insertion.
See L<DBIx::Class::InflateColumn> and other modules in that namespace.
Object-relational mapping, or Object-relationship modelling. Either
way it's a method of mapping the contents of database tables (rows),
-to objects in programming-language-space. DBIx::Class is an ORM.
+to objects in programming-language-space. L<DBIC|DBIx::Class> is an ORM.
=head2 Relationship
-In DBIx::Class a relationship defines the connection between exactly
+In L<DBIC|DBIx::Class>, a relationship defines the connection between exactly
two tables. The relationship condition lists the columns in each table
that contain the same values. It is used to output an SQL JOIN
condition between the tables.
Result objects contain your actual data. They are returned from
ResultSet objects. These are sometimes (incorrectly) called
-row objects, including older versions of the DBIC documentation.
+row objects, including older versions of the L<DBIC|DBIx::Class>
+documentation.
See also: L<DBIx::Class::Manual::ResultClass>
=item * L<DBIx::Class::Manual::ResultClass>
-=back
+=head1 AUTHOR AND CONTRIBUTORS
-=cut
+See L<AUTHOR|DBIx::Class/AUTHOR> and L<CONTRIBUTORS|DBIx::Class/CONTRIBUTORS> in DBIx::Class
=head1 DESCRIPTION
-This document should help you to use L<DBIx::Class> if you are trying
-to convert your normal SQL queries into DBIx::Class based queries, if
+This document should help you to use L<DBIC|DBIx::Class> if you are trying
+to convert your normal SQL queries into L<DBIC|DBIx::Class> based queries, if
you use joins extensively (and also probably if you don't).
=head1 WHAT ARE JOINS
=head1 DEFINING JOINS AND RELATIONSHIPS
-In L<DBIx::Class> each relationship between two tables needs to first
+In L<DBIC|DBIx::Class> each relationship between two tables needs to first
be defined in the L<ResultSource|DBIx::Class::Manual::Glossary/ResultSource> for the
table. If the relationship needs to be accessed in both directions
(i.e. Fetch all tracks of a CD, and fetch the CD data for a Track),
=head2 Table aliases
-As an aside to all the discussion on joins, note that L<DBIx::Class>
+As an aside to all the discussion on joins, note that L<DBIC|DBIx::Class>
uses the C<relation names> as table aliases. This is important when
you need to add grouping or ordering to your queries:
=head1 NAME
-DBIx::Class::Manual::Reading - How to read and write DBIx::Class POD.
+DBIx::Class::Manual::Reading - How to read and write DBIC POD.
=head1 DESCRIPTION
This doc should help users to understand how the examples and
-documentation found in the L<DBIx::Class> distribution can be
+documentation found in the L<DBIC|DBIx::Class> distribution can be
interpreted.
-Writers of DBIx::Class POD should also check here to make sure their
-additions are consistent with the rest of the documentation.
+Writers of L<DBIC|DBIx::Class> POD should also check here to make sure
+their additions are consistent with the rest of the documentation.
=head1 METHODS
=head1 DESCRIPTION
-In L<DBIx::Class>, a user normally receives query results as instances of a
+In L<DBIC|DBIx::Class>, a user normally receives query results as instances of a
certain C<Result Class>, depending on the main query source. Besides being
the primary "toolset" for interaction with your data, a C<Result Class> also
serves to establish source metadata, which is then used during initialization
$rs->search( {}, { order_by => [ 'name DESC' ] } );
-Since L<DBIx::Class> >= 0.08100 and L<SQL::Abstract> >= 1.50 the above
+Since L<DBIC|DBIx::Class> >= 0.08100 and L<SQL::Abstract> >= 1.50 the above
should be written as:
$rs->search( {}, { order_by => { -desc => 'name' } } );
This issue is due to perl doing an exhaustive search of blessed objects
under certain circumstances. The problem shows up as performance
-degradation exponential to the number of L<DBIx::Class> result objects in
+degradation exponential to the number of L<DBIC|DBIx::Class> result objects in
memory, so can be unnoticeable with certain data sets, but with huge
performance impacts on other datasets.
A pair of tests for susceptibility to the issue and performance effects
-of the bless/overload problem can be found in the L<DBIx::Class> test
+of the bless/overload problem can be found in the L<DBIC|DBIx::Class> test
suite, in the C<t/99rh_perl_perf_bug.t> file.
Further information on this issue can be found in
},
pod => {
title => 'DBIx::Class::Admin',
- desc => 'Modules required for the DBIx::Class administrative library',
+ desc => 'Modules required for the DBIC administrative library',
},
},
},
pod => {
title => 'dbicadmin',
- desc => 'Modules required for the CLI DBIx::Class interface dbicadmin',
+ desc => 'Modules required for the CLI DBIC interface dbicadmin',
},
},
EOS
'=head1 DESCRIPTION',
<<'EOD',
-Some of the less-frequently used features of L<DBIx::Class> have external
+Some of the less-frequently used features of L<DBIC|DBIx::Class> have external
module dependencies on their own. In order not to burden the average user
with modules he will never use, these optional dependencies are not included
in the base Makefile.PL. Instead an exception with a descriptive message is
thrown when a specific feature is missing one or several modules required for
its operation. This module is the central holding place for the current list
-of such dependencies, for DBIx::Class core authors, and DBIx::Class extension
-authors alike.
+of such dependencies, for L<DBIC|DBIx::Class> core authors, and DBIx::Class
+extension authors alike.
EOD
'=head1 CURRENT REQUIREMENT GROUPS',
<<'EOD',
'=item Return Value: \%list_of_requirement_groups',
'=back',
<<'EOD',
-This method should be used by DBIx::Class packagers, to get a hashref of all
+This method should be used by L<DBIC|DBIx::Class> packagers, to get a hashref of all
dependencies keyed by dependency group. Each key (group name) can be supplied
to one of the group-specific methods below.
EOD
'=item Return Value: \%list_of_module_version_pairs',
'=back',
<<'EOD',
-This method should be used by DBIx::Class extension authors, to determine the
+This method should be used by L<DBIC|DBIx::Class> extension authors, to determine the
version of modules a specific feature requires in the B<current> version of
DBIx::Class. See the L</SYNOPSIS> for a real-world
example.
'=back',
<<"EOD",
Returns a single line string suitable for inclusion in larger error messages.
-This method would normally be used by DBIx::Class core-module author, to
+This method would normally be used by L<DBIC|DBIx::Class> core-module author, to
indicate to the user that he needs to install specific modules before he will
be able to use a specific feature.
=head1 DESCRIPTION
This module provides a simple interface for modifying the ordered
-position of DBIx::Class objects.
+position of L<DBIC|DBIx::Class> objects.
=head1 AUTO UPDATE
=head2 insert
-Overrides the DBIC insert() method by providing a default
+Overrides the L<DBIC insert method|DBIx::Class::Row/insert> by providing a default
position number. The default will be the number of rows in
the table +1, thus positioning the new record at the last position.
=head2 update
-Overrides the DBIC update() method by checking for a change
+Overrides the L<DBIC update method|DBIx::Class::Row/update> by checking for a change
to the position and/or group columns. Movement within a
group or to another group is handled by repositioning
the appropriate siblings. Position defaults to the end
=head2 delete
-Overrides the DBIC delete() method by first moving the object
+Overrides the L<DBIC delete method|DBIx::Class::Row/delete> by first moving the object
to the last position, then deleting it, thus ensuring the
integrity of the positions.
This class provides methods to set up relationships between the tables
in your database model. Relationships are the most useful and powerful
-technique that L<DBIx::Class> provides. To create efficient database queries,
+technique that L<DBIC|DBIx::Class> provides. To create efficient database queries,
create relationships between any and all tables that have something in
common, for example if you have a table Authors:
relationship. To turn them on, pass C<< cascade_delete => 1 >>
in the $attr hashref.
-By default, DBIC will return undef and avoid querying the database if a
+By default, L<DBIC|DBIx::Class> will return undef and avoid querying the database if a
C<belongs_to> accessor is called when any part of the foreign key IS NULL. To
disable this behavior, pass C<< undef_on_null_fk => 0 >> in the C<\%attrs>
hashref.
The cascaded operations are performed after the requested delete or
update, so if your database has a constraint on the relationship, it
will have deleted/updated the related records or raised an exception
-before DBIx::Class gets to perform the cascaded operation.
+before L<DBIC|DBIx::Class> gets to perform the cascaded operation.
If you copy an object in a class with a C<has_many> relationship, all
the related objects will be copied as well. To turn this behaviour off,
The cascaded operations are performed after the requested delete or
update, so if your database has a constraint on the relationship, it
will have deleted/updated the related records or raised an exception
-before DBIx::Class gets to perform the cascaded operation.
+before L<DBIC|DBIx::Class> gets to perform the cascaded operation.
See L<DBIx::Class::Relationship::Base/attributes> for documentation on
relationship methods and valid relationship attributes. Also see
=item cascade_delete
-By default, DBIx::Class cascades deletes across C<has_many>,
+By default, L<DBIC|DBIx::Class> cascades deletes across C<has_many>,
C<has_one> and C<might_have> relationships. You can disable this
behaviour on a per-relationship basis by supplying
C<< cascade_delete => 0 >> in the relationship attributes.
The cascaded operations are performed after the requested delete,
so if your database has a constraint on the relationship, it will
have deleted/updated the related records or raised an exception
-before DBIx::Class gets to perform the cascaded operation.
+before L<DBIC|DBIx::Class> gets to perform the cascaded operation.
=item cascade_update
-By default, DBIx::Class cascades updates across C<has_one> and
+By default, L<DBIC|DBIx::Class> cascades updates across C<has_one> and
C<might_have> relationships. You can disable this behaviour on a
per-relationship basis by supplying C<< cascade_update => 0 >> in
the relationship attributes.
=head1 DESCRIPTION
-DBIx::Class is faster than older ORMs like Class::DBI but it still isn't
+L<DBIC|DBIx::Class> is faster than older ORMs like L<Class::DBI> but it still isn't
designed primarily for speed. Sometimes you need to quickly retrieve the data
from a massive resultset, while skipping the creation of fancy result objects.
Specifying this class as a C<result_class> for a resultset will change C<< $rs->next >>
=head1 DESCRIPTION
A ResultSet is an object which stores a set of conditions representing
-a query. It is the backbone of DBIx::Class (i.e. the really
+a query. It is the backbone of L<DBIC|DBIx::Class> (i.e. the really
important/useful bit).
No SQL is executed on the database when a ResultSet is created, it
L<unique constraint|DBIx::Class::ResultSource/add_unique_constraint> (the
unique constraint corresponding to the
L<primary columns|DBIx::Class::ResultSource/primary_columns> is always named
-C<primary>). If the C<key> attribute has been supplied, and DBIC is unable
-to construct a query that satisfies the named unique constraint fully (
-non-NULL values for each column member of the constraint) an exception is
+C<primary>). If the C<key> attribute has been supplied, and L<DBIC|DBIx::Class>
+is unable to construct a query that satisfies the named unique constraint
+fully (non-NULL values for each column member of the constraint) an exception is
thrown.
If no C<key> is specified, the search is carried over all unique constraints
=back
Fetches all objects and updates them one at a time via
-L<DBIx::Class::Row/update>. Note that C<update_all> will run DBIC defined
-triggers, while L</update> will not.
+L<DBIx::Class::Row/update>. Note that C<update_all> will run L<DBIC|DBIx::Class>
+defined triggers, while L</update> will not.
=cut
=back
Fetches all objects and deletes them one at a time via
-L<DBIx::Class::Row/delete>. Note that C<delete_all> will run DBIC defined
-triggers, while L</delete> will not.
+L<DBIx::Class::Row/delete>. Note that C<delete_all> will run L<DBIC|DBIx::Class>
+defined triggers, while L</delete> will not.
=cut
L</search>/L</find> family method depends on how you got to the resultset: it's
C<me> by default, but eg. L</search_related> aliases it to the related result
source name (and keeps C<me> referring to the original result set). The long
-term goal is to make L<DBIx::Class> always alias the current resultset as C<me>
+term goal is to make L<DBIC|DBIx::Class> always alias the current resultset as C<me>
(and make this method unnecessary).
Thus it's currently necessary to use this method in predefined queries (see
SELECT name, COUNT( employeeid ), MAX( LENGTH( name ) ) AS longest_name FROM employee
B<NOTE:> You will almost always need a corresponding L</as> attribute when you
-use L</select>, to instruct DBIx::Class how to store the result of the column.
+use L</select>, to instruct L<DBIC|DBIx::Class> how to store the result of the column.
Also note that the L</as> attribute has nothing to do with the SQL-side 'AS'
identifier aliasing. You can however alias a function, so you can use it in
e.g. an C<ORDER BY> clause. This is done via the C<-as> B<select function
If an L</order_by> is already declared, and orders the resultset in a way that
makes collapsing as described above impossible (e.g. C<< ORDER BY
-has_many_rel.column >> or C<ORDER BY RANDOM()>), DBIC will automatically
+has_many_rel.column >> or C<ORDER BY RANDOM()>), L<DBIC|DBIx::Class> will automatically
switch to "eager" mode and slurp the entire resultset before consturcting the
first object returned by L</next>.
When combined with L</rows> and/or L</offset> the generated SQL will not
include any limit dialect stanzas. Instead the entire result will be selected
-as if no limits were specified, and DBIC will perform the limit locally, by
-artificially advancing and finishing the resulting L</cursor>.
+as if no limits were specified, and L<DBIC|DBIx::Class> will perform the limit
+locally, by artificially advancing and finishing the resulting L</cursor>.
This is the recommended way of performing resultset limiting when no sane RDBMS
implementation is available (e.g.
=head1 PREFETCHING
-DBIx::Class supports arbitrary related data prefetching from multiple related
+L<DBIC|DBIx::Class> supports arbitrary related data prefetching from multiple related
sources. Any combination of relationship types and column sets are supported.
If L<collapsing|/collapse> is requested, there is an additional requirement of
selecting enough data to make every individual object uniquely identifiable.
JOIN cd ON tag.cd = cd.cdid
JOIN artist ON cd.artist = artist.artistid
-L<DBIx::Class> has no need to go back to the database when we access the
+L<DBIC|DBIx::Class> has no need to go back to the database when we access the
C<cd> or C<artist> relationships, which saves us two SQL statements in this
case.
=head1 DBIC BIND VALUES
-Because DBIC may need more information to bind values than just the column name
-and value itself, it uses a special format for both passing and receiving bind
-values. Each bind value should be composed of an arrayref of
+Because L<DBIC|DBIx::Class> may need more information to bind values than just
+the column name and value itself, it uses a special format for both passing and
+receiving bind values. Each bind value should be composed of an arrayref of
C<< [ \%args => $val ] >>. The format of C<< \%args >> is currently:
=over 4
{ retrieve_on_insert => 1 }
-For every column where this is set to true, DBIC will retrieve the RDBMS-side
+For every column where this is set to true, L<DBIC|DBIx::Class> will retrieve the RDBMS-side
value upon a new row insertion (normally only the autoincrement PK is
retrieved on insert). C<INSERT ... RETURNING> is used automatically if
supported by the underlying storage, otherwise an extra SELECT statement is
Please note that if a value is not passed to new, no value will be sent
in the SQL INSERT call, and the column will therefore assume whatever
-default value was specified in your database. While DBIC will retrieve the
-value of autoincrement columns, it will never make an explicit database
-trip to retrieve default values assigned by the RDBMS. You can explicitly
-request that all values be fetched back from the database by calling
-L</discard_changes>, or you can supply an explicit C<undef> to columns
-with NULL as the default, and save yourself a SELECT.
+default value was specified in your database. While L<DBIC|DBIx::Class>
+will retrieve the value of autoincrement columns, it will never make an
+explicit database trip to retrieve default values assigned by the RDBMS.
+You can explicitly request that all values be fetched back from the
+database by calling L</discard_changes>, or you can supply an explicit
+C<undef> to columns with NULL as the default, and save yourself a SELECT.
CAVEAT:
=item L<DBIx::Class::SQLMaker> - Parent module
-=item L<DBIx::Class> - Duh
+=item L<DBIC|DBIx::Class> - Duh
=back
=head1 DESCRIPTION
Creates database classes based on a schema. This is the recommended way to
-use L<DBIx::Class> and allows you to use more than one concurrent connection
+use L<DBIC|DBIx::Class> and allows you to use more than one concurrent connection
with your classes.
NB: If you're used to L<Class::DBI> it's worth reading the L</SYNOPSIS>
-carefully, as DBIx::Class does things a little differently. Note in
+carefully, as L<DBIC|DBIx::Class> does things a little differently. Note in
particular which module inherits off which.
=head1 SETUP METHODS
created. For quoting purposes supply C<quote_table_names> and
C<quote_field_names>.
-Additionally, the DBIx::Class parser accepts a C<sources> parameter as a hash
+Additionally, the L<DBIC|DBIx::Class> parser accepts a C<sources> parameter as a hash
ref or an array ref, containing a list of source to deploy. If present, then
only the sources listed will get deployed. Furthermore, you can use the
C<add_fk_index> parser parameter to prevent the parser from creating an index for each
WARNING
- Prior to DBIx::Class version 0.08100 this method had a different signature:
+ Prior to DBIx::Class version 0.08100, this method had a different signature:
my $filename = $table->ddl_filename($type, $dir, $version, $preversion)
A table called I<dbix_class_schema_versions> is created and maintained by the
module. This is used to determine which version your database is currently at.
-Similarly the $VERSION in your DBIC schema class is used to determine the
-current DBIC schema version.
+Similarly the $VERSION in your L<DBIC schema class|DBIx::Class::Schema> is used
+to determine the current L<DBIC schema|DBIx::Class::Schema> version.
The upgrade is initiated manually by calling C<upgrade> on your schema object,
this will attempt to upgrade the database from its current version to the current
=head2 upgrade
Call this to attempt to upgrade your database from the version it
-is at to the version this DBIC schema is at. If they are the same
-it does nothing.
+is at to the version this L<DBIC schema|DBIx::Class::Schema> is at. If
+they are the same it does nothing.
It will call L</ordered_schema_versions> to retrieve an ordered
list of schema versions (if ordered_schema_versions returns nothing
=head2 connection
-Overloaded method. This checks the DBIC schema version against the DB version and
-warns if they are not the same or if the DB is unversioned. It also provides
-compatibility between the old versions table (SchemaVersions) and the new one
-(dbix_class_schema_versions).
+Overloaded method. This checks the L<DBIC schema class|DBIx::Class::Schema>
+version against the DB version and warns if they are not the same or if the
+DB is unversioned. It also provides compatibility between the old versions
+table (SchemaVersions) and the new one (dbix_class_schema_versions).
To avoid the checks on connect, set the environment var DBIC_NO_VERSION_CHECK or alternatively you can set the ignore_version attr in the forth argument like so:
The same 4-element argument set one would normally pass to
L<DBI/connect>, optionally followed by
-L<extra attributes|/DBIx::Class specific connection attributes>
+L<extra attributes|/DBIC specific connection attributes>
recognized by DBIx::Class:
$connect_info_args = [ $dsn, $user, $password, \%dbi_attributes?, \%extra_attributes? ];
A single code reference which returns a connected
L<DBI database handle|DBI/connect> optionally followed by
-L<extra attributes|/DBIx::Class specific connection attributes> recognized
+L<extra attributes|/DBIC specific connection attributes> recognized
by DBIx::Class:
$connect_info_args = [ sub { DBI->connect (...) }, \%extra_attributes? ];
=back
Please note that the L<DBI> docs recommend that you always explicitly
-set C<AutoCommit> to either I<0> or I<1>. L<DBIx::Class> further
+set C<AutoCommit> to either I<0> or I<1>. L<DBIC|DBIx::Class> further
recommends that it be set to I<1>, and that you perform transactions
-via our L<DBIx::Class::Schema/txn_do> method. L<DBIx::Class> will set it
+via our L<DBIx::Class::Schema/txn_do> method. L<DBIC|DBIx::Class> will set it
to I<1> if you do not do explicitly set it to zero. This is the default
-for most DBDs. See L</DBIx::Class and AutoCommit> for details.
+for most DBDs. See L</DBIC and AutoCommit> for details.
-=head3 DBIx::Class specific connection attributes
+=head3 DBIC specific connection attributes
In addition to the standard L<DBI|DBI/ATTRIBUTES COMMON TO ALL HANDLES>
-L<connection|DBI/Database Handle Attributes> attributes, DBIx::Class recognizes
+L<connection|DBI/Database Handle Attributes> attributes, DBIC recognizes
the following connection options. These options can be mixed in with your other
L<DBI> connection attributes, or placed in a separate hashref
(C<\%extra_attributes>) as shown above.
=item auto_savepoint
-If this option is true, L<DBIx::Class> will use savepoints when nesting
+If this option is true, L<DBIC|DBIx::Class> will use savepoints when nesting
transactions, making it possible to recover from failure in the inner
transaction without having to abort all outer transactions.
=back
-L<DBIx::Class> uses L<DBIx::Class::Relationship> names as table aliases in
+L<DBIC|DBIx::Class> uses L<DBIx::Class::Relationship> names as table aliases in
queries.
This hook is to allow specific L<DBIx::Class::Storage> drivers to change the
=head1 USAGE NOTES
-=head2 DBIx::Class and AutoCommit
+=head2 DBIC and AutoCommit
-DBIx::Class can do some wonderful magic with handling exceptions,
+L<DBIC|DBIx::Class> can do some wonderful magic with handling exceptions,
disconnections, and transactions when you use C<< AutoCommit => 1 >>
(the default) combined with L<txn_do|DBIx::Class::Storage/txn_do> for
transaction support.
L<DBD::ADO>.
See the documentation for L<DBIx::Class::Storage::DBI::ACCESS> for
-information on the MS Access driver for L<DBIx::Class>.
+information on the MS Access driver for L<DBIC|DBIx::Class>.
This driver implements workarounds for C<TEXT/IMAGE/MEMO> columns, sets the
L<cursor_class|DBIx::Class::Storage::DBI/cursor_class> to
L<DBD::InterBase> C<ib_softcommit> option.
You need either this option or C<< disable_sth_caching => 1 >> for
-L<DBIx::Class> code to function correctly (otherwise you may get C<no statement
+L<DBIC|DBIx::Class> code to function correctly (otherwise you may get C<no statement
executing> errors.) Or use the L<ODBC|DBIx::Class::Storage::DBI::ODBC::Firebird>
driver.
=head2 relname_to_table_alias
-L<DBIx::Class> uses L<DBIx::Class::Relationship> names as table aliases in
+L<DBIC|DBIx::Class> uses L<DBIx::Class::Relationship> names as table aliases in
queries.
Unfortunately, Oracle doesn't support identifiers over 30 chars in length, so
=head1 SYNOPSIS
-DBIx::Class should automagically detect Oracle and use this module with no
-work from you.
+L<DBIC|DBIx::Class> should automagically detect Oracle and use this module
+with no work from you.
=head1 DESCRIPTION
=item L<DBIx::Class::Storage::DBI::Oracle::Generic>
-=item L<DBIx::Class>
+=item L<DBIC|DBIx::Class>
=back
=head1 REQUIREMENTS
Replicated Storage has additional requirements not currently part of
-L<DBIx::Class>. See L<DBIx::Class::Optional::Dependencies> for more details.
+L<DBIC|DBIx::Class>. See L<DBIx::Class::Optional::Dependencies> for more details.
=head1 ATTRIBUTES
=head1 DESCRIPTION
-L<DBIx::Class> supports a framework for using database replication. This system
+L<DBIC|DBIx::Class> supports a framework for using database replication. This system
is integrated completely, which means once it's setup you should be able to
automatically just start using a replication cluster without additional work or
changes to your code. Some caveats apply, primarily related to the proper use
=head1 REPLICATED STORAGE
-By default, when you start L<DBIx::Class>, your Schema (L<DBIx::Class::Schema>)
+By default, when you start L<DBIC|DBIx::Class>, your Schema (L<DBIx::Class::Schema>)
is assigned a storage_type, which when fully connected will reflect your
underlying storage engine as defined by your chosen database driver. For
example, if you connect to a MySQL database, your storage_type will be
L<DBIx::Class::Storage::DBI::mysql> Your storage type class will contain
database specific code to help smooth over the differences between databases
-and let L<DBIx::Class> do its thing.
+and let L<DBIC|DBIx::Class> do its thing.
If you want to use replication, you will override this setting so that the
replicated storage engine will 'wrap' your underlying storages and present
=head1 MAXIMUM CURSORS
-A L<DBIx::Class> application can use a lot of cursors, due to the usage of
+A L<DBIC|DBIx::Class> application can use a lot of cursors, due to the usage of
L<prepare_cached|DBI/prepare_cached>.
The default cursor maximum is C<50>, which can be a bit too low. This limit can
in the background. By default the number of such connections is limited to 25,
on both the client side and the server side.
-This is a bit too low for a complex L<DBIx::Class> application, so on connection
+This is a bit too low for a complex L<DBIC|DBIx::Class> application, so on connection
the client side setting is set to C<256> (see L<DBD::Sybase/maxConnect>.) You
can override it to whatever setting you like in the DSN.
=head2 Warning - Module does not function properly on create/insert
-Recently (April 2010) a bug was found deep in the core of L<DBIx::Class>
+Recently (April 2010) a bug was found deep in the core of L<DBIC|DBIx::Class>
which affects any component attempting to perform encoding/decoding by
overloading L<store_column|DBIx::Class::Row/store_column> and
L<get_columns|DBIx::Class::Row/get_columns>. As a result of this problem
It is unclear how this bug went undetected for so long (it was
introduced in March 2006), No attempts to fix it will be made while the
-implications of changing such a fundamental behavior of DBIx::Class are
-being evaluated. However in this day and age you should not be using
-this module anyway as Unicode is properly supported by all major
+implications of changing such a fundamental behavior of L<DBIC|DBIx::Class>
+are being evaluated. However, in this day and age you should not be using
+this module anyway, as Unicode is properly supported by all major
database engines, as explained below.
If you have specific questions about the integrity of your data in light
Note that this module overloads L<DBIx::Class::Row/store_column> in a way
that may prevent other components overloading the same method from working
correctly. This component must be the last one before L<DBIx::Class::Row>
-(which is provided by L<DBIx::Class::Core>). DBIx::Class will detect such
-incorrect component order and issue an appropriate warning, advising which
-components need to be loaded differently.
+(which is provided by L<DBIx::Class::Core>). L<DBIC|DBIx::Class> will detect
+such incorrect component order and issue an appropriate warning, advising
+which components need to be loaded differently.
=head1 SEE ALSO
This class requires L<SQL::Translator> installed to work.
-C<SQL::Translator::Parser::DBIx::Class> reads a DBIx::Class schema,
+C<SQL::Translator::Parser::DBIx::Class> reads a L<DBIC schema|DBIx::Class::Schema>,
interrogates the columns, and stuffs it all in an $sqlt_schema object.
Its primary use is in deploying database layouts described as a set
-of L<DBIx::Class> classes, to a database. To do this, see
+of L<DBIC|DBIx::Class> classes, to a database. To do this, see
L<DBIx::Class::Schema/deploy>.
-This can also be achieved by having DBIx::Class export the schema as a
+This can also be achieved by having L<DBIC|DBIx::Class> export the schema as a
set of SQL files ready for import into your database, or passed to
other machines that need to have your application installed but don't
have SQL::Translator installed. To do this see
=head2 dbic_schema
-The DBIx::Class schema (either an instance or a class name) to be parsed.
+The L<DBIC schema|DBIx::Class::Schema> (either an instance or a class name) to be parsed.
This argument is in fact optional - instead one can supply it later at
translation time as an argument to L<SQL::Translator/translate>. In
other words both of the following invocations are valid and will produce
projects / dbsrgits/DBIx-Class.git / commitdiff