NAME

DBIx::Mint::Schema - Class and relationship definitions for DBIx::Mint

SYNOPSIS

 # Using the schema from the default Mint object:
 my $schema = DBIx::Mint->instance->schema;

 # Using a named schema:
 my $schema = DBIx::Mint->instance->schema( 'other' );

 # which is the same as this:
 my $mint   = DBIx::Mint->instance('other');
 my $schema = $mint->schema;
 
 
 $schema->add_class(
    class => 'Bloodbowl::Coach',
    table => 'coaches',
    pk    => 'id',
    auto_pk => 1
 );
 
 $schema->one_to_many(
    conditions     => 
        [ 'Bloodbowl::Team', { id => 'team' }, 'Bloodbowl::Player' ],
    method         => 'get_players',
    inverse_method => 'get_team', 
    insert_into    => 'add_player'
 );
 
  $schema->many_to_many(
    conditions     => [ 'Bloodbowl::Player',      { id => 'player'},
                        'Bloodbowl::PlayerSkills, { skill => 'skill' },
                        'Bloodbowl::Skill' ],
    method         => 'get_skills',
    inverse_method => 'get_players'
 );

 $schema->add_relationship(
    conditions   => 
        ['Bloodbowl::Team', { id => 'team' }, 'Bloodbowl::Players'],
    method       => 'players_rs',
    result_as    => 'result_set'
 );

DESCRIPTION

This module lets you declare the mapping between classes and database tables, and it creates methods that act on the relationships you define. It is an essential part of DBIx::Mint.

METHODS

add_class

Defines the mapping between a class and a database table. It expects the following arguments:

class

The name of the class. Required.

table

The name of the table it points to. Required.

pk

Defines the primary key in the database. It can be a single field name or an array reference of field names. Required.

auto_pk

Lets DBIx::Mint know that the pk is automatically generated by the database. It expects a boolean value. Optional; defaults to false.

not_in_db

Receives a list of attributes of the given class which are not stored in the database. They will be removed from the data before inserting or updating it into the database.

one_to_many

Builds a one-to-many relationship between two classes. Internally, it is built using the method add_relationship, which builds closures that contain a DBIx::Mint::ResultSet object to fetch related records and, optionally, an insert_into method. It expects the following parameters:

conditions

Defines both the classes that the relationship binds and the fields that are used to link them. These conditions are then used to build DBIx::Mint::ResultSet joins.

The attribute receives an array reference with the following format:

 [ 'Class::One', { from_field => 'to_field' }, 'Class::Many' ]

one_to_many will insert a method into Class::One which will return the (many) related records of Class::Many, using from_field and to_field to link the classes.

This parameter is required.

method

Defines the name of the method that is inserted into the 'one' class defined in conditions. This method will return a list of all the related records of the 'many' class, blessed. Required.

inverse_method

It creates a method in the 'many' side of the relationship that returns the related record from the 'one' side. The returned record is a blessed object. Optional.

insert_into

If present, this parameter defines the name of a method which is inserted into the 'one' class which allows it to insert related records into the 'many' class. It expects hash references as input. Note that they should have the same keys in order to benefit from a prepared insert statement.

many_to_many

Builds a many-to-many relationship between two classes. Internally, it is built using the method add_relationship, which builds closures that contain a DBIx::Mint::ResultSet object to fetch related records. It expects the following parameters:

conditions

Defines the chain of classes that the relationship binds and the fields that are used to link them. These conditions are then used to build DBIx::Mint::ResultSet joins.

The attribute receives an array reference with the following format:

 [ 'Class::One', { from_field => 'to_field' }, 
   'Class::Two', { from_two   => 'to_three' },
   'Class::Three' ]

many_to_many will insert a method into Class::One which will return the (many) related records of Class::Three, joined through Class::Two. The size of the array can be arbitrarily long.

This parameter is required.

method

Defines the name of the method that is inserted into the first class defined in conditions. This method will return a list of all the related records of the last class, blessed. Required.

inverse_method

It creates a method in the last class that returns a list of all the related records from the first. The records are blessed objects. Optional.

add_relationship

This method creates a one-to-one, one-to-many or many-to-many relationship and it allows you to define the returned form of the resulting records.

conditions

Same as many_to_many relationships.

method, inverse_method

These parameters receive the name of the methods that will be inserted into the first and last classes defined for the relationship. The difference with one_to_many and many_to_many is that, by default, you will get a DBIx::Mint::ResultSet object. See result_as and inv_result_as for other options.

insert_into

Same as one_to_many. It will insert records into the second class you define which are related to the first class. In a many-to-many relationship that uses a single link class, this method will allow you to insert objects into the link class.

result_as, inv_result_as

These two parameters define the results that you will get from the created method and inverse_method. The allowed options are:

resultset

This is the default. The method will return a DBIx::Mint::ResultSet object suitable for chaining conditions or paging. It offers the most flexibility.

single

Methods will return a single, blessed object from your set of results.

all

Methods will return all the related records from your set of results.

as_iterator

Methods will return a DBIx::Mint::ResultSet object with an iterator to fetch one record at a time from your set of results. It is used as follows:

 my $rs = $obj->method;
 while (my $record = $rs->next) {
     say $record->name;
 }

as_sql

This form will return the generated select SQL statement and the list of bind values. Useful for debugging.

SEE ALSO

This module is part of DBIx::Mint.

AUTHOR

Julio Fraire, <julio.fraire@gmail.com>

LICENCE AND COPYRIGHT

Copyright (c) 2013, Julio Fraire. All rights reserved.

LICENSE

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.