view release on metacpan or  search on metacpan

lib/DBIx/Class/Schema/Loader/Base.pm  view on Meta::CPAN

=head2 pod_comment_mode

Controls where table comments appear in the generated POD. Smaller table
comments are appended to the C<NAME> section of the documentation, and larger
ones are inserted into C<DESCRIPTION> instead. You can force a C<DESCRIPTION>
section to be generated with the comment always, only use C<NAME>, or choose
the length threshold at which the comment is forced into the description.

=over 4

=item name

Use C<NAME> section only.

=item description

Force C<DESCRIPTION> always.

=item auto

Use C<DESCRIPTION> if length > L</pod_comment_spillover_length>, this is the
default.

=back

=head2 pod_comment_spillover_length

When pod_comment_mode is set to C<auto>, this is the length of the comment at
which it will be forced into a separate description section.

The default is C<60>

=head2 table_comments_table

The table to look for comments about tables in.  By default C<table_comments>.
See L</generate_pod> for details.

This must not be a fully qualified name, the table will be looked for in the
same database and schema as the table whose comment is being retrieved.

=head2 column_comments_table

The table to look for comments about columns in.  By default C<column_comments>.
See L</generate_pod> for details.

This must not be a fully qualified name, the table will be looked for in the
same database and schema as the table/column whose comment is being retrieved.

=head2 relationship_attrs

Hashref of attributes to pass to each generated relationship, listed by type.
Also supports relationship type 'all', containing options to pass to all
generated relationships.  Attributes set for more specific relationship types
override those set in 'all', and any attributes specified by this option
override the introspected attributes of the foreign key if any.

For example:

    relationship_attrs => {
        has_many   => { cascade_delete => 1, cascade_copy => 1 },
        might_have => { cascade_delete => 1, cascade_copy => 1 },
    },

use this to turn L<DBIx::Class> cascades to on on your
L<has_many|DBIx::Class::Relationship/has_many> and
L<might_have|DBIx::Class::Relationship/might_have> relationships, they default
to off.

Can also be a coderef, for more precise control, in which case the coderef gets
this hash of parameters (as a list):

    rel_name        # the name of the relationship
    rel_type        # the type of the relationship: 'belongs_to', 'has_many' or 'might_have'
    local_source    # the DBIx::Class::ResultSource object for the source the rel is *from*
    remote_source   # the DBIx::Class::ResultSource object for the source the rel is *to*
    local_table     # the DBIx::Class::Schema::Loader::Table object for the table of the source the rel is from
    local_cols      # an arrayref of column names of columns used in the rel in the source it is from
    remote_table    # the DBIx::Class::Schema::Loader::Table object for the table of the source the rel is to
    remote_cols     # an arrayref of column names of columns used in the rel in the source it is to
    attrs           # the attributes that would be set

it should return the new hashref of attributes, or nothing for no changes.

For example:

    relationship_attrs => sub {
        my %p = @_;

        say "the relationship name is: $p{rel_name}";
        say "the relationship is a: $p{rel_type}";
        say "the local class is: ",  $p{local_source}->result_class;
        say "the remote class is: ", $p{remote_source}->result_class;
        say "the local table is: ", $p{local_table}->sql_name;
        say "the rel columns in the local table are: ", (join ", ", @{$p{local_cols}});
        say "the remote table is: ", $p{remote_table}->sql_name;
        say "the rel columns in the remote table are: ", (join ", ", @{$p{remote_cols}});

        if ($p{local_table} eq 'dogs' && @{$p{local_cols}} == 1 && $p{local_cols}[0] eq 'name') {
            $p{attrs}{could_be_snoopy} = 1;

            return $p{attrs};
        }
    },

These are the default attributes:

    has_many => {
        cascade_delete => 0,
        cascade_copy   => 0,
    },
    might_have => {
        cascade_delete => 0,
        cascade_copy   => 0,
    },
    belongs_to => {
        on_delete => 'CASCADE',
        on_update => 'CASCADE',
        is_deferrable => 1,
    },

For L<belongs_to|DBIx::Class::Relationship/belongs_to> relationships, these
defaults are overridden by the attributes introspected from the foreign key in
the database, if this information is available (and the driver is capable of
retrieving it.)

This information overrides the defaults mentioned above, and is then itself
overridden by the user's L</relationship_attrs> for C<belongs_to> if any are
specified.

In general, for most databases, for a plain foreign key with no rules, the
values for a L<belongs_to|DBIx::Class::Relationship/belongs_to> relationship
will be:

    on_delete     => 'NO ACTION',
    on_update     => 'NO ACTION',
    is_deferrable => 0,

In the cases where an attribute is not supported by the DB, a value matching
the actual behavior is used, for example Oracle does not support C<ON UPDATE>
rules, so C<on_update> is set to C<NO ACTION>. This is done so that the
behavior of the schema is preserved when cross deploying to a different RDBMS
such as SQLite for testing.

In the cases where the DB does not support C<DEFERRABLE> foreign keys, the
value is set to C<1> if L<DBIx::Class> has a working C<<
$storage->with_deferred_fk_checks >>. This is done so that the same
L<DBIx::Class> code can be used, and cross deployed from and to such databases.

=head2 debug

If set to true, each constructive L<DBIx::Class> statement the loader
decides to execute will be C<warn>-ed before execution.

=head2 db_schema

Set the name of the schema to load (schema in the sense that your database
vendor means it).

Can be set to an arrayref of schema names for multiple schemas, or the special
value C<%> for all schemas.

For MSSQL, Sybase ASE, and Informix can be set to a hashref of databases as
keys and arrays of owners as values, set to the value:

    { '%' => '%' }

for all owners in all databases.

Name clashes resulting from the same table name in different databases/schemas
will be resolved automatically by prefixing the moniker with the database
and/or schema.

To prefix/suffix all monikers with the database and/or schema, see