.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "DBIx::Class::ResultSource 3pm"
.TH DBIx::Class::ResultSource 3pm "2018-04-19" "perl v5.26.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
DBIx::Class::ResultSource \- Result source object
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  # Create a table based result source, in a result class.
\&
\&  package MyApp::Schema::Result::Artist;
\&  use base qw/DBIx::Class::Core/;
\&
\&  _\|_PACKAGE_\|_\->table(\*(Aqartist\*(Aq);
\&  _\|_PACKAGE_\|_\->add_columns(qw/ artistid name /);
\&  _\|_PACKAGE_\|_\->set_primary_key(\*(Aqartistid\*(Aq);
\&  _\|_PACKAGE_\|_\->has_many(cds => \*(AqMyApp::Schema::Result::CD\*(Aq);
\&
\&  1;
\&
\&  # Create a query (view) based result source, in a result class
\&  package MyApp::Schema::Result::Year2000CDs;
\&  use base qw/DBIx::Class::Core/;
\&
\&  _\|_PACKAGE_\|_\->load_components(\*(AqInflateColumn::DateTime\*(Aq);
\&  _\|_PACKAGE_\|_\->table_class(\*(AqDBIx::Class::ResultSource::View\*(Aq);
\&
\&  _\|_PACKAGE_\|_\->table(\*(Aqyear2000cds\*(Aq);
\&  _\|_PACKAGE_\|_\->result_source_instance\->is_virtual(1);
\&  _\|_PACKAGE_\|_\->result_source_instance\->view_definition(
\&      "SELECT cdid, artist, title FROM cd WHERE year =\*(Aq2000\*(Aq"
\&      );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A ResultSource is an object that represents a source of data for querying.
.PP
This class is a base class for various specialised types of result
sources, for example DBIx::Class::ResultSource::Table. Table is the
default result source type, so one is created for you when defining a
result class as described in the synopsis above.
.PP
More specifically, the DBIx::Class::Core base class pulls in the
DBIx::Class::ResultSourceProxy::Table component, which defines
the table method.
When called, \f(CW\*(C`table\*(C'\fR creates and stores an instance of
DBIx::Class::ResultSource::Table. Luckily, to use tables as result
sources, you don't need to remember any of this.
.PP
Result sources representing select queries, or views, can also be
created, see DBIx::Class::ResultSource::View for full details.
.SS "Finding result source objects"
.IX Subsection "Finding result source objects"
As mentioned above, a result source instance is created and stored for
you when you define a
Result Class.
.PP
You can retrieve the result source at runtime in the following ways:
.IP "From a Schema object:" 4
.IX Item "From a Schema object:"
.Vb 1
\&   $schema\->source($source_name);
.Ve
.IP "From a Result object:" 4
.IX Item "From a Result object:"
.Vb 1
\&   $result\->result_source;
.Ve
.IP "From a ResultSet object:" 4
.IX Item "From a ResultSet object:"
.Vb 1
\&   $rs\->result_source;
.Ve
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
.Vb 1
\&  $class\->new();
\&
\&  $class\->new({attribute_name => value});
.Ve
.PP
Creates a new ResultSource object.  Not normally called directly by end users.
.SS "add_columns"
.IX Subsection "add_columns"
.ie n .IP "Arguments: @columns" 4
.el .IP "Arguments: \f(CW@columns\fR" 4
.IX Item "Arguments: @columns"
.PD 0
.ie n .IP "Return Value: $result_source" 4
.el .IP "Return Value: \f(CW$result_source\fR" 4
.IX Item "Return Value: $result_source"
.PD
.PP
.Vb 1
\&  $source\->add_columns(qw/col1 col2 col3/);
\&
\&  $source\->add_columns(\*(Aqcol1\*(Aq => \e%col1_info, \*(Aqcol2\*(Aq => \e%col2_info, ...);
\&
\&  $source\->add_columns(
\&    \*(Aqcol1\*(Aq => { data_type => \*(Aqinteger\*(Aq, is_nullable => 1, ... },
\&    \*(Aqcol2\*(Aq => { data_type => \*(Aqtext\*(Aq,    is_auto_increment => 1, ... },
\&  );
.Ve
.PP
Adds columns to the result source. If supplied colname => hashref
pairs, uses the hashref as the \*(L"column_info\*(R" for that column. Repeated
calls of this method will add more columns, not replace them.
.PP
The column names given will be created as accessor methods on your
Result objects. You can change the name of the accessor
by supplying an \*(L"accessor\*(R" in the column_info hash.
.PP
If a column name beginning with a plus sign ('+col1') is provided, the
attributes provided will be merged with any existing attributes for the
column, with the new attributes taking precedence in the case that an
attribute already exists. Using this without a hashref
(\f(CW\*(C`$source\->add_columns(qw/+col1 +col2/)\*(C'\fR) is legal, but useless \*(--
it does the same thing it would do without the plus.
.PP
The contents of the column_info are not set in stone. The following
keys are currently recognised/used by DBIx::Class:
.IP "accessor" 4
.IX Item "accessor"
.Vb 1
\&   { accessor => \*(Aq_name\*(Aq }
\&
\&   # example use, replace standard accessor with one of your own:
\&   sub name {
\&       my ($self, $value) = @_;
\&
\&       die "Name cannot contain digits!" if($value =~ /\ed/);
\&       $self\->_name($value);
\&
\&       return $self\->_name();
\&   }
.Ve
.Sp
Use this to set the name of the accessor method for this column. If unset,
the name of the column will be used.
.IP "data_type" 4
.IX Item "data_type"
.Vb 1
\&   { data_type => \*(Aqinteger\*(Aq }
.Ve
.Sp
This contains the column type. It is automatically filled if you use the
SQL::Translator::Producer::DBIx::Class::File producer, or the
DBIx::Class::Schema::Loader module.
.Sp
Currently there is no standard set of values for the data_type. Use
whatever your database supports.
.IP "size" 4
.IX Item "size"
.Vb 1
\&   { size => 20 }
.Ve
.Sp
The length of your column, if it is a column type that can have a size
restriction. This is currently only used to create tables from your
schema, see \*(L"deploy\*(R" in DBIx::Class::Schema.
.Sp
.Vb 1
\&   { size => [ 9, 6 ] }
.Ve
.Sp
For decimal or float values you can specify an ArrayRef in order to
control precision, assuming your database's
SQL::Translator::Producer supports it.
.IP "is_nullable" 4
.IX Item "is_nullable"
.Vb 1
\&   { is_nullable => 1 }
.Ve
.Sp
Set this to a true value for a column that is allowed to contain \s-1NULL\s0
values, default is false. This is currently only used to create tables
from your schema, see \*(L"deploy\*(R" in DBIx::Class::Schema.
.IP "is_auto_increment" 4
.IX Item "is_auto_increment"
.Vb 1
\&   { is_auto_increment => 1 }
.Ve
.Sp
Set this to a true value for a column whose value is somehow
automatically set, defaults to false. This is used to determine which
columns to empty when cloning objects using
\&\*(L"copy\*(R" in DBIx::Class::Row. It is also used by
\&\*(L"deploy\*(R" in DBIx::Class::Schema.
.IP "is_numeric" 4
.IX Item "is_numeric"
.Vb 1
\&   { is_numeric => 1 }
.Ve
.Sp
Set this to a true or false value (not \f(CW\*(C`undef\*(C'\fR) to explicitly specify
if this column contains numeric data. This controls how set_column
decides whether to consider a column dirty after an update: if
\&\f(CW\*(C`is_numeric\*(C'\fR is true a numeric comparison \f(CW\*(C`!=\*(C'\fR will take place
instead of the usual \f(CW\*(C`eq\*(C'\fR
.Sp
If not specified the storage class will attempt to figure this out on
first access to the column, based on the column \f(CW\*(C`data_type\*(C'\fR. The
result will be cached in this attribute.
.IP "is_foreign_key" 4
.IX Item "is_foreign_key"
.Vb 1
\&   { is_foreign_key => 1 }
.Ve
.Sp
Set this to a true value for a column that contains a key from a
foreign table, defaults to false. This is currently only used to
create tables from your schema, see \*(L"deploy\*(R" in DBIx::Class::Schema.
.IP "default_value" 4
.IX Item "default_value"
.Vb 1
\&   { default_value => \e\*(Aqnow()\*(Aq }
.Ve
.Sp
Set this to the default value which will be inserted into a column by
the database. Can contain either a value or a function (use a
reference to a scalar e.g. \f(CW\*(C`\e\*(Aqnow()\*(Aq\*(C'\fR if you want a function). This
is currently only used to create tables from your schema, see
\&\*(L"deploy\*(R" in DBIx::Class::Schema.
.Sp
See the note on \*(L"new\*(R" in DBIx::Class::Row for more information about possible
issues related to db-side default values.
.IP "sequence" 4
.IX Item "sequence"
.Vb 1
\&   { sequence => \*(Aqmy_table_seq\*(Aq }
.Ve
.Sp
Set this on a primary key column to the name of the sequence used to
generate a new key value. If not specified, DBIx::Class::PK::Auto
will attempt to retrieve the name of the sequence from the database
automatically.
.IP "retrieve_on_insert" 4
.IX Item "retrieve_on_insert"
.Vb 1
\&  { retrieve_on_insert => 1 }
.Ve
.Sp
For every column where this is set to true, \s-1DBIC\s0 will retrieve the RDBMS-side
value upon a new row insertion (normally only the autoincrement \s-1PK\s0 is
retrieved on insert). \f(CW\*(C`INSERT ... RETURNING\*(C'\fR is used automatically if
supported by the underlying storage, otherwise an extra \s-1SELECT\s0 statement is
executed to retrieve the missing data.
.IP "auto_nextval" 4
.IX Item "auto_nextval"
.Vb 1
\&   { auto_nextval => 1 }
.Ve
.Sp
Set this to a true value for a column whose value is retrieved automatically
from a sequence or function (if supported by your Storage driver.) For a
sequence, if you do not use a trigger to get the nextval, you have to set the
\&\*(L"sequence\*(R" value as well.
.Sp
Also set this for \s-1MSSQL\s0 columns with the 'uniqueidentifier'
data_type whose values you want to
automatically generate using \f(CW\*(C`NEWID()\*(C'\fR, unless they are a primary key in which
case this will be done anyway.
.IP "extra" 4
.IX Item "extra"
This is used by \*(L"deploy\*(R" in DBIx::Class::Schema and SQL::Translator
to add extra non-generic data to the column. For example: \f(CW\*(C`extra
=> { unsigned => 1}\*(C'\fR is used by the MySQL producer to set an integer
column to unsigned. For more details, see
SQL::Translator::Producer::MySQL.
.SS "add_column"
.IX Subsection "add_column"
.ie n .IP "Arguments: $colname, \e%columninfo?" 4
.el .IP "Arguments: \f(CW$colname\fR, \e%columninfo?" 4
.IX Item "Arguments: $colname, %columninfo?"
.PD 0
.IP "Return Value: 1/0 (true/false)" 4
.IX Item "Return Value: 1/0 (true/false)"
.PD
.PP
.Vb 1
\&  $source\->add_column(\*(Aqcol\*(Aq => \e%info);
.Ve
.PP
Add a single column and optional column info. Uses the same column
info keys as \*(L"add_columns\*(R".
.SS "has_column"
.IX Subsection "has_column"
.ie n .IP "Arguments: $colname" 4
.el .IP "Arguments: \f(CW$colname\fR" 4
.IX Item "Arguments: $colname"
.PD 0
.IP "Return Value: 1/0 (true/false)" 4
.IX Item "Return Value: 1/0 (true/false)"
.PD
.PP
.Vb 1
\&  if ($source\->has_column($colname)) { ... }
.Ve
.PP
Returns true if the source has a column of this name, false otherwise.
.SS "column_info"
.IX Subsection "column_info"
.ie n .IP "Arguments: $colname" 4
.el .IP "Arguments: \f(CW$colname\fR" 4
.IX Item "Arguments: $colname"
.PD 0
.IP "Return Value: Hashref of info" 4
.IX Item "Return Value: Hashref of info"
.PD
.PP
.Vb 1
\&  my $info = $source\->column_info($col);
.Ve
.PP
Returns the column metadata hashref for a column, as originally passed
to \*(L"add_columns\*(R". See \*(L"add_columns\*(R" above for information on the
contents of the hashref.
.SS "columns"
.IX Subsection "columns"
.IP "Arguments: none" 4
.IX Item "Arguments: none"
.PD 0
.IP "Return Value: Ordered list of column names" 4
.IX Item "Return Value: Ordered list of column names"
.PD
.PP
.Vb 1
\&  my @column_names = $source\->columns;
.Ve
.PP
Returns all column names in the order they were declared to \*(L"add_columns\*(R".
.SS "columns_info"
.IX Subsection "columns_info"
.IP "Arguments: \e@colnames ?" 4
.IX Item "Arguments: @colnames ?"
.PD 0
.IP "Return Value: Hashref of column name/info pairs" 4
.IX Item "Return Value: Hashref of column name/info pairs"
.PD
.PP
.Vb 1
\&  my $columns_info = $source\->columns_info;
.Ve
.PP
Like \*(L"column_info\*(R" but returns information for the requested columns. If
the optional column-list arrayref is omitted it returns info on all columns
currently defined on the ResultSource via \*(L"add_columns\*(R".
.SS "remove_columns"
.IX Subsection "remove_columns"
.ie n .IP "Arguments: @colnames" 4
.el .IP "Arguments: \f(CW@colnames\fR" 4
.IX Item "Arguments: @colnames"
.PD 0
.IP "Return Value: not defined" 4
.IX Item "Return Value: not defined"
.PD
.PP
.Vb 1
\&  $source\->remove_columns(qw/col1 col2 col3/);
.Ve
.PP
Removes the given list of columns by name, from the result source.
.PP
\&\fBWarning\fR: Removing a column that is also used in the sources primary
key, or in one of the sources unique constraints, \fBwill\fR result in a
broken result source.
.SS "remove_column"
.IX Subsection "remove_column"
.ie n .IP "Arguments: $colname" 4
.el .IP "Arguments: \f(CW$colname\fR" 4
.IX Item "Arguments: $colname"
.PD 0
.IP "Return Value: not defined" 4
.IX Item "Return Value: not defined"
.PD
.PP
.Vb 1
\&  $source\->remove_column(\*(Aqcol\*(Aq);
.Ve
.PP
Remove a single column by name from the result source, similar to
\&\*(L"remove_columns\*(R".
.PP
\&\fBWarning\fR: Removing a column that is also used in the sources primary
key, or in one of the sources unique constraints, \fBwill\fR result in a
broken result source.
.SS "set_primary_key"
.IX Subsection "set_primary_key"
.ie n .IP "Arguments: @cols" 4
.el .IP "Arguments: \f(CW@cols\fR" 4
.IX Item "Arguments: @cols"
.PD 0
.IP "Return Value: not defined" 4
.IX Item "Return Value: not defined"
.PD
.PP
Defines one or more columns as primary key for this source. Must be
called after \*(L"add_columns\*(R".
.PP
Additionally, defines a unique constraint
named \f(CW\*(C`primary\*(C'\fR.
.PP
Note: you normally do want to define a primary key on your sources
\&\fBeven if the underlying database table does not have a primary key\fR.
See
\&\*(L"The Significance and Importance of Primary Keys\*(R" in DBIx::Class::Manual::Intro
for more info.
.SS "primary_columns"
.IX Subsection "primary_columns"
.IP "Arguments: none" 4
.IX Item "Arguments: none"
.PD 0
.IP "Return Value: Ordered list of primary column names" 4
.IX Item "Return Value: Ordered list of primary column names"
.PD
.PP
Read-only accessor which returns the list of primary keys, supplied by
\&\*(L"set_primary_key\*(R".
.SS "sequence"
.IX Subsection "sequence"
Manually define the correct sequence for your table, to avoid the overhead
associated with looking up the sequence automatically. The supplied sequence
will be applied to the \*(L"column_info\*(R" of each primary_key
.ie n .IP "Arguments: $sequence_name" 4
.el .IP "Arguments: \f(CW$sequence_name\fR" 4
.IX Item "Arguments: $sequence_name"
.PD 0
.IP "Return Value: not defined" 4
.IX Item "Return Value: not defined"
.PD
.SS "add_unique_constraint"
.IX Subsection "add_unique_constraint"
.ie n .IP "Arguments: $name?, \e@colnames" 4
.el .IP "Arguments: \f(CW$name\fR?, \e@colnames" 4
.IX Item "Arguments: $name?, @colnames"
.PD 0
.IP "Return Value: not defined" 4
.IX Item "Return Value: not defined"
.PD
.PP
Declare a unique constraint on this source. Call once for each unique
constraint.
.PP
.Vb 4
\&  # For UNIQUE (column1, column2)
\&  _\|_PACKAGE_\|_\->add_unique_constraint(
\&    constraint_name => [ qw/column1 column2/ ],
\&  );
.Ve
.PP
Alternatively, you can specify only the columns:
.PP
.Vb 1
\&  _\|_PACKAGE_\|_\->add_unique_constraint([ qw/column1 column2/ ]);
.Ve
.PP
This will result in a unique constraint named
\&\f(CW\*(C`table_column1_column2\*(C'\fR, where \f(CW\*(C`table\*(C'\fR is replaced with the table
name.
.PP
Unique constraints are used, for example, when you pass the constraint
name as the \f(CW\*(C`key\*(C'\fR attribute to \*(L"find\*(R" in DBIx::Class::ResultSet. Then
only columns in the constraint are searched.
.PP
Throws an error if any of the given column names do not yet exist on
the result source.
.SS "add_unique_constraints"
.IX Subsection "add_unique_constraints"
.ie n .IP "Arguments: @constraints" 4
.el .IP "Arguments: \f(CW@constraints\fR" 4
.IX Item "Arguments: @constraints"
.PD 0
.IP "Return Value: not defined" 4
.IX Item "Return Value: not defined"
.PD
.PP
Declare multiple unique constraints on this source.
.PP
.Vb 4
\&  _\|_PACKAGE_\|_\->add_unique_constraints(
\&    constraint_name1 => [ qw/column1 column2/ ],
\&    constraint_name2 => [ qw/column2 column3/ ],
\&  );
.Ve
.PP
Alternatively, you can specify only the columns:
.PP
.Vb 4
\&  _\|_PACKAGE_\|_\->add_unique_constraints(
\&    [ qw/column1 column2/ ],
\&    [ qw/column3 column4/ ]
\&  );
.Ve
.PP
This will result in unique constraints named \f(CW\*(C`table_column1_column2\*(C'\fR and
\&\f(CW\*(C`table_column3_column4\*(C'\fR, where \f(CW\*(C`table\*(C'\fR is replaced with the table name.
.PP
Throws an error if any of the given column names do not yet exist on
the result source.
.PP
See also \*(L"add_unique_constraint\*(R".
.SS "name_unique_constraint"
.IX Subsection "name_unique_constraint"
.IP "Arguments: \e@colnames" 4
.IX Item "Arguments: @colnames"
.PD 0
.IP "Return Value: Constraint name" 4
.IX Item "Return Value: Constraint name"
.PD
.PP
.Vb 4
\&  $source\->table(\*(Aqmytable\*(Aq);
\&  $source\->name_unique_constraint([\*(Aqcol1\*(Aq, \*(Aqcol2\*(Aq]);
\&  # returns
\&  \*(Aqmytable_col1_col2\*(Aq
.Ve
.PP
Return a name for a unique constraint containing the specified
columns. The name is created by joining the table name and each column
name, using an underscore character.
.PP
For example, a constraint on a table named \f(CW\*(C`cd\*(C'\fR containing the columns
\&\f(CW\*(C`artist\*(C'\fR and \f(CW\*(C`title\*(C'\fR would result in a constraint name of \f(CW\*(C`cd_artist_title\*(C'\fR.
.PP
This is used by \*(L"add_unique_constraint\*(R" if you do not specify the
optional constraint name.
.SS "unique_constraints"
.IX Subsection "unique_constraints"
.IP "Arguments: none" 4
.IX Item "Arguments: none"
.PD 0
.IP "Return Value: Hash of unique constraint data" 4
.IX Item "Return Value: Hash of unique constraint data"
.PD
.PP
.Vb 1
\&  $source\->unique_constraints();
.Ve
.PP
Read-only accessor which returns a hash of unique constraints on this
source.
.PP
The hash is keyed by constraint name, and contains an arrayref of
column names as values.
.SS "unique_constraint_names"
.IX Subsection "unique_constraint_names"
.IP "Arguments: none" 4
.IX Item "Arguments: none"
.PD 0
.IP "Return Value: Unique constraint names" 4
.IX Item "Return Value: Unique constraint names"
.PD
.PP
.Vb 1
\&  $source\->unique_constraint_names();
.Ve
.PP
Returns the list of unique constraint names defined on this source.
.SS "unique_constraint_columns"
.IX Subsection "unique_constraint_columns"
.ie n .IP "Arguments: $constraintname" 4
.el .IP "Arguments: \f(CW$constraintname\fR" 4
.IX Item "Arguments: $constraintname"
.PD 0
.IP "Return Value: List of constraint columns" 4
.IX Item "Return Value: List of constraint columns"
.PD
.PP
.Vb 1
\&  $source\->unique_constraint_columns(\*(Aqmyconstraint\*(Aq);
.Ve
.PP
Returns the list of columns that make up the specified unique constraint.
.SS "sqlt_deploy_callback"
.IX Subsection "sqlt_deploy_callback"
.ie n .IP "Arguments: $callback_name | \e&callback_code" 4
.el .IP "Arguments: \f(CW$callback_name\fR | \e&callback_code" 4
.IX Item "Arguments: $callback_name | &callback_code"
.PD 0
.ie n .IP "Return Value: $callback_name | \e&callback_code" 4
.el .IP "Return Value: \f(CW$callback_name\fR | \e&callback_code" 4
.IX Item "Return Value: $callback_name | &callback_code"
.PD
.PP
.Vb 1
\&  _\|_PACKAGE_\|_\->sqlt_deploy_callback(\*(Aqmycallbackmethod\*(Aq);
\&
\&   or
\&
\&  _\|_PACKAGE_\|_\->sqlt_deploy_callback(sub {
\&    my ($source_instance, $sqlt_table) = @_;
\&    ...
\&  } );
.Ve
.PP
An accessor to set a callback to be called during deployment of
the schema via \*(L"create_ddl_dir\*(R" in DBIx::Class::Schema or
\&\*(L"deploy\*(R" in DBIx::Class::Schema.
.PP
The callback can be set as either a code reference or the name of a
method in the current result class.
.PP
Defaults to \*(L"default_sqlt_deploy_hook\*(R".
.PP
Your callback will be passed the \f(CW$source\fR object representing the
ResultSource instance being deployed, and the
SQL::Translator::Schema::Table object being created from it. The
callback can be used to manipulate the table object or add your own
customised indexes. If you need to manipulate a non-table object, use
the \*(L"sqlt_deploy_hook\*(R" in DBIx::Class::Schema.
.PP
See \*(L"Adding Indexes And Functions To
Your \s-1SQL\*(R"\s0 in DBIx::Class::Manual::Cookbook for examples.
.PP
This sqlt deployment callback can only be used to manipulate
SQL::Translator objects as they get turned into \s-1SQL.\s0 To execute
post-deploy statements which SQL::Translator does not currently
handle, override \*(L"deploy\*(R" in DBIx::Class::Schema in your Schema class
and call dbh_do.
.SS "default_sqlt_deploy_hook"
.IX Subsection "default_sqlt_deploy_hook"
This is the default deploy hook implementation which checks if your
current Result class has a \f(CW\*(C`sqlt_deploy_hook\*(C'\fR method, and if present
invokes it \fBon the Result class directly\fR. This is to preserve the
semantics of \f(CW\*(C`sqlt_deploy_hook\*(C'\fR which was originally designed to expect
the Result class name and the
\&\f(CW$sqlt_table\fR instance of the table being
deployed.
.SS "result_class"
.IX Subsection "result_class"
.ie n .IP "Arguments: $classname" 4
.el .IP "Arguments: \f(CW$classname\fR" 4
.IX Item "Arguments: $classname"
.PD 0
.ie n .IP "Return Value: $classname" 4
.el .IP "Return Value: \f(CW$classname\fR" 4
.IX Item "Return Value: $classname"
.PD
.PP
.Vb 2
\& use My::Schema::ResultClass::Inflator;
\& ...
\&
\& use My::Schema::Artist;
\& ...
\& _\|_PACKAGE_\|_\->result_class(\*(AqMy::Schema::ResultClass::Inflator\*(Aq);
.Ve
.PP
Set the default result class for this source. You can use this to create
and use your own result inflator. See \*(L"result_class\*(R" in DBIx::Class::ResultSet
for more details.
.PP
Please note that setting this to something like
DBIx::Class::ResultClass::HashRefInflator will make every result unblessed
and make life more difficult.  Inflators like those are better suited to
temporary usage via \*(L"result_class\*(R" in DBIx::Class::ResultSet.
.SS "resultset"
.IX Subsection "resultset"
.IP "Arguments: none" 4
.IX Item "Arguments: none"
.PD 0
.ie n .IP "Return Value: $resultset" 4
.el .IP "Return Value: \f(CW$resultset\fR" 4
.IX Item "Return Value: $resultset"
.PD
.PP
Returns a resultset for the given source. This will initially be created
on demand by calling
.PP
.Vb 1
\&  $self\->resultset_class\->new($self, $self\->resultset_attributes)
.Ve
.PP
but is cached from then on unless resultset_class changes.
.SS "resultset_class"
.IX Subsection "resultset_class"
.ie n .IP "Arguments: $classname" 4
.el .IP "Arguments: \f(CW$classname\fR" 4
.IX Item "Arguments: $classname"
.PD 0
.ie n .IP "Return Value: $classname" 4
.el .IP "Return Value: \f(CW$classname\fR" 4
.IX Item "Return Value: $classname"
.PD
.PP
.Vb 3
\&  package My::Schema::ResultSet::Artist;
\&  use base \*(AqDBIx::Class::ResultSet\*(Aq;
\&  ...
\&
\&  # In the result class
\&  _\|_PACKAGE_\|_\->resultset_class(\*(AqMy::Schema::ResultSet::Artist\*(Aq);
\&
\&  # Or in code
\&  $source\->resultset_class(\*(AqMy::Schema::ResultSet::Artist\*(Aq);
.Ve
.PP
Set the class of the resultset. This is useful if you want to create your
own resultset methods. Create your own class derived from
DBIx::Class::ResultSet, and set it here. If called with no arguments,
this method returns the name of the existing resultset class, if one
exists.
.SS "resultset_attributes"
.IX Subsection "resultset_attributes"
.IP "Arguments: \e%attrs" 4
.IX Item "Arguments: %attrs"
.PD 0
.IP "Return Value: \e%attrs" 4
.IX Item "Return Value: %attrs"
.PD
.PP
.Vb 2
\&  # In the result class
\&  _\|_PACKAGE_\|_\->resultset_attributes({ order_by => [ \*(Aqid\*(Aq ] });
\&
\&  # Or in code
\&  $source\->resultset_attributes({ order_by => [ \*(Aqid\*(Aq ] });
.Ve
.PP
Store a collection of resultset attributes, that will be set on every
DBIx::Class::ResultSet produced from this result source.
.PP
\&\fB\s-1CAVEAT\s0\fR: \f(CW\*(C`resultset_attributes\*(C'\fR comes with its own set of issues and
bugs! While \f(CW\*(C`resultset_attributes\*(C'\fR isn't deprecated per se, its usage is
not recommended!
.PP
Since relationships use attributes to link tables together, the \*(L"default\*(R"
attributes you set may cause unpredictable and undesired behavior.  Furthermore,
the defaults cannot be turned off, so you are stuck with them.
.PP
In most cases, what you should actually be using are project-specific methods:
.PP
.Vb 3
\&  package My::Schema::ResultSet::Artist;
\&  use base \*(AqDBIx::Class::ResultSet\*(Aq;
\&  ...
\&
\&  # BAD IDEA!
\&  #_\|_PACKAGE_\|_\->resultset_attributes({ prefetch => \*(Aqtracks\*(Aq });
\&
\&  # GOOD IDEA!
\&  sub with_tracks { shift\->search({}, { prefetch => \*(Aqtracks\*(Aq }) }
\&
\&  # in your code
\&  $schema\->resultset(\*(AqArtist\*(Aq)\->with_tracks\->...
.Ve
.PP
This gives you the flexibility of not using it when you don't need it.
.PP
For more complex situations, another solution would be to use a virtual view
via DBIx::Class::ResultSource::View.
.SS "name"
.IX Subsection "name"
.IP "Arguments: none" 4
.IX Item "Arguments: none"
.PD 0
.ie n .IP "Result value: $name" 4
.el .IP "Result value: \f(CW$name\fR" 4
.IX Item "Result value: $name"
.PD
.PP
Returns the name of the result source, which will typically be the table
name. This may be a scalar reference if the result source has a non-standard
name.
.SS "source_name"
.IX Subsection "source_name"
.ie n .IP "Arguments: $source_name" 4
.el .IP "Arguments: \f(CW$source_name\fR" 4
.IX Item "Arguments: $source_name"
.PD 0
.ie n .IP "Result value: $source_name" 4
.el .IP "Result value: \f(CW$source_name\fR" 4
.IX Item "Result value: $source_name"
.PD
.PP
Set an alternate name for the result source when it is loaded into a schema.
This is useful if you want to refer to a result source by a name other than
its class name.
.PP
.Vb 4
\&  package ArchivedBooks;
\&  use base qw/DBIx::Class/;
\&  _\|_PACKAGE_\|_\->table(\*(Aqbooks_archive\*(Aq);
\&  _\|_PACKAGE_\|_\->source_name(\*(AqBooks\*(Aq);
\&
\&  # from your schema...
\&  $schema\->resultset(\*(AqBooks\*(Aq)\->find(1);
.Ve
.SS "from"
.IX Subsection "from"
.IP "Arguments: none" 4
.IX Item "Arguments: none"
.PD 0
.IP "Return Value: \s-1FROM\s0 clause" 4
.IX Item "Return Value: FROM clause"
.PD
.PP
.Vb 1
\&  my $from_clause = $source\->from();
.Ve
.PP
Returns an expression of the source to be supplied to storage to specify
retrieval from this source. In the case of a database, the required \s-1FROM\s0
clause contents.
.SS "source_info"
.IX Subsection "source_info"
Stores a hashref of per-source metadata.  No specific key names
have yet been standardized, the examples below are purely hypothetical
and don't actually accomplish anything on their own:
.PP
.Vb 4
\&  _\|_PACKAGE_\|_\->source_info({
\&    "_tablespace" => \*(Aqfast_disk_array_3\*(Aq,
\&    "_engine" => \*(AqInnoDB\*(Aq,
\&  });
.Ve
.SS "schema"
.IX Subsection "schema"
.ie n .IP "Arguments: $schema?" 4
.el .IP "Arguments: \f(CW$schema\fR?" 4
.IX Item "Arguments: $schema?"
.PD 0
.ie n .IP "Return Value: $schema" 4
.el .IP "Return Value: \f(CW$schema\fR" 4
.IX Item "Return Value: $schema"
.PD
.PP
.Vb 1
\&  my $schema = $source\->schema();
.Ve
.PP
Sets and/or returns the DBIx::Class::Schema object to which this
result source instance has been attached to.
.SS "storage"
.IX Subsection "storage"
.IP "Arguments: none" 4
.IX Item "Arguments: none"
.PD 0
.ie n .IP "Return Value: $storage" 4
.el .IP "Return Value: \f(CW$storage\fR" 4
.IX Item "Return Value: $storage"
.PD
.PP
.Vb 1
\&  $source\->storage\->debug(1);
.Ve
.PP
Returns the storage handle for the current schema.
.SS "add_relationship"
.IX Subsection "add_relationship"
.ie n .IP "Arguments: $rel_name, $related_source_name, \e%cond, \e%attrs?" 4
.el .IP "Arguments: \f(CW$rel_name\fR, \f(CW$related_source_name\fR, \e%cond, \e%attrs?" 4
.IX Item "Arguments: $rel_name, $related_source_name, %cond, %attrs?"
.PD 0
.IP "Return Value: 1/true if it succeeded" 4
.IX Item "Return Value: 1/true if it succeeded"
.PD
.PP
.Vb 1
\&  $source\->add_relationship(\*(Aqrel_name\*(Aq, \*(Aqrelated_source\*(Aq, $cond, $attrs);
.Ve
.PP
DBIx::Class::Relationship describes a series of methods which
create pre-defined useful types of relationships. Look there first
before using this method directly.
.PP
The relationship name can be arbitrary, but must be unique for each
relationship attached to this result source. 'related_source' should
be the name with which the related result source was registered with
the current schema. For example:
.PP
.Vb 3
\&  $schema\->source(\*(AqBook\*(Aq)\->add_relationship(\*(Aqreviews\*(Aq, \*(AqReview\*(Aq, {
\&    \*(Aqforeign.book_id\*(Aq => \*(Aqself.id\*(Aq,
\&  });
.Ve
.PP
The condition \f(CW$cond\fR needs to be an SQL::Abstract\-style
representation of the join between the tables. For example, if you're
creating a relation from Author to Book,
.PP
.Vb 1
\&  { \*(Aqforeign.author_id\*(Aq => \*(Aqself.id\*(Aq }
.Ve
.PP
will result in the \s-1JOIN\s0 clause
.PP
.Vb 1
\&  author me JOIN book foreign ON foreign.author_id = me.id
.Ve
.PP
You can specify as many foreign => self mappings as necessary.
.PP
Valid attributes are as follows:
.IP "join_type" 4
.IX Item "join_type"
Explicitly specifies the type of join to use in the relationship. Any
\&\s-1SQL\s0 join type is valid, e.g. \f(CW\*(C`LEFT\*(C'\fR or \f(CW\*(C`RIGHT\*(C'\fR. It will be placed in
the \s-1SQL\s0 command immediately before \f(CW\*(C`JOIN\*(C'\fR.
.IP "proxy" 4
.IX Item "proxy"
An arrayref containing a list of accessors in the foreign class to proxy in
the main class. If, for example, you do the following:
.Sp
.Vb 3
\&  CD\->might_have(liner_notes => \*(AqLinerNotes\*(Aq, undef, {
\&    proxy => [ qw/notes/ ],
\&  });
.Ve
.Sp
Then, assuming LinerNotes has an accessor named notes, you can do:
.Sp
.Vb 3
\&  my $cd = CD\->find(1);
\&  # set notes \-\- LinerNotes object is created if it doesn\*(Aqt exist
\&  $cd\->notes(\*(AqNotes go here\*(Aq);
.Ve
.IP "accessor" 4
.IX Item "accessor"
Specifies the type of accessor that should be created for the
relationship. Valid values are \f(CW\*(C`single\*(C'\fR (for when there is only a single
related object), \f(CW\*(C`multi\*(C'\fR (when there can be many), and \f(CW\*(C`filter\*(C'\fR (for
when there is a single related object, but you also want the relationship
accessor to double as a column accessor). For \f(CW\*(C`multi\*(C'\fR accessors, an
add_to_* method is also created, which calls \f(CW\*(C`create_related\*(C'\fR for the
relationship.
.PP
Throws an exception if the condition is improperly supplied, or cannot
be resolved.
.SS "relationships"
.IX Subsection "relationships"
.IP "Arguments: none" 4
.IX Item "Arguments: none"
.PD 0
.ie n .IP "Return Value: @rel_names" 4
.el .IP "Return Value: \f(CW@rel_names\fR" 4
.IX Item "Return Value: @rel_names"
.PD
.PP
.Vb 1
\&  my @rel_names = $source\->relationships();
.Ve
.PP
Returns all relationship names for this source.
.SS "relationship_info"
.IX Subsection "relationship_info"
.ie n .IP "Arguments: $rel_name" 4
.el .IP "Arguments: \f(CW$rel_name\fR" 4
.IX Item "Arguments: $rel_name"
.PD 0
.IP "Return Value: \e%rel_data" 4
.IX Item "Return Value: %rel_data"
.PD
.PP
Returns a hash of relationship information for the specified relationship
name. The keys/values are as specified for \*(L"add_relationship\*(R" in DBIx::Class::Relationship::Base.
.SS "has_relationship"
.IX Subsection "has_relationship"
.ie n .IP "Arguments: $rel_name" 4
.el .IP "Arguments: \f(CW$rel_name\fR" 4
.IX Item "Arguments: $rel_name"
.PD 0
.IP "Return Value: 1/0 (true/false)" 4
.IX Item "Return Value: 1/0 (true/false)"
.PD
.PP
Returns true if the source has a relationship of this name, false otherwise.
.SS "reverse_relationship_info"
.IX Subsection "reverse_relationship_info"
.ie n .IP "Arguments: $rel_name" 4
.el .IP "Arguments: \f(CW$rel_name\fR" 4
.IX Item "Arguments: $rel_name"
.PD 0
.IP "Return Value: \e%rel_data" 4
.IX Item "Return Value: %rel_data"
.PD
.PP
Looks through all the relationships on the source this relationship
points to, looking for one whose condition is the reverse of the
condition on this relationship.
.PP
A common use of this is to find the name of the \f(CW\*(C`belongs_to\*(C'\fR relation
opposing a \f(CW\*(C`has_many\*(C'\fR relation. For definition of these look in
DBIx::Class::Relationship.
.PP
The returned hashref is keyed by the name of the opposing
relationship, and contains its data in the same manner as
\&\*(L"relationship_info\*(R".
.SS "related_source"
.IX Subsection "related_source"
.ie n .IP "Arguments: $rel_name" 4
.el .IP "Arguments: \f(CW$rel_name\fR" 4
.IX Item "Arguments: $rel_name"
.PD 0
.ie n .IP "Return Value: $source" 4
.el .IP "Return Value: \f(CW$source\fR" 4
.IX Item "Return Value: $source"
.PD
.PP
Returns the result source object for the given relationship.
.SS "related_class"
.IX Subsection "related_class"
.ie n .IP "Arguments: $rel_name" 4
.el .IP "Arguments: \f(CW$rel_name\fR" 4
.IX Item "Arguments: $rel_name"
.PD 0
.ie n .IP "Return Value: $classname" 4
.el .IP "Return Value: \f(CW$classname\fR" 4
.IX Item "Return Value: $classname"
.PD
.PP
Returns the class name for objects in the given relationship.
.SS "handle"
.IX Subsection "handle"
.IP "Arguments: none" 4
.IX Item "Arguments: none"
.PD 0
.ie n .IP "Return Value: $source_handle" 4
.el .IP "Return Value: \f(CW$source_handle\fR" 4
.IX Item "Return Value: $source_handle"
.PD
.PP
Obtain a new result source handle instance
for this source. Used as a serializable pointer to this resultsource, as it is not
easy (nor advisable) to serialize CODErefs which may very well be present in e.g.
relationship definitions.
.SS "throw_exception"
.IX Subsection "throw_exception"
See \*(L"throw_exception\*(R" in DBIx::Class::Schema.
.SS "column_info_from_storage"
.IX Subsection "column_info_from_storage"
.IP "Arguments: 1/0 (default: 0)" 4
.IX Item "Arguments: 1/0 (default: 0)"
.PD 0
.IP "Return Value: 1/0" 4
.IX Item "Return Value: 1/0"
.PD
.PP
.Vb 1
\&  _\|_PACKAGE_\|_\->column_info_from_storage(1);
.Ve
.PP
Enables the on-demand automatic loading of the above column
metadata from storage as necessary.  This is *deprecated*, and
should not be used.  It will be removed before 1.0.
.SH "FURTHER QUESTIONS?"
.IX Header "FURTHER QUESTIONS?"
Check the list of additional \s-1DBIC\s0 resources.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This module is free software copyright
by the DBIx::Class (\s-1DBIC\s0) authors. You can
redistribute it and/or modify it under the same terms as the
DBIx::Class library.