DBIC Tutorial

DBIx::Class Tutorial

Overview

DBIx::Class (DBIC) is an object relational mapper for Perl.

Schema

The first thing one needs to use DBIC is a subclass of DBIx::Class::Schema that one connects with to gain access to the database. An example is:

package MyApp::Schema;

use warnings;
use strict;

use parent 'DBIx::Class::Schema';

__PACKAGE__->load_namespaces;

1;

This use of load_namespaces will look for ResultSource classes in MyApp/Schema/Result and MyApp/Schema/ResultSet. We’ll talk about ResultSources and ResultSets in a minute, but first how to connect to the database using the schema:

use MyApp::Schema;
my $schema =
  MyApp::Schema->connect( 'DBI:Pg:dbname=my_db;host=localhost;port=5432', 'user', 'pass' );

ResultSource

A class that typically defines the schema for a table. Some of the common methods used are:

load_components¹

This tells what components to load. You almost certainly will want to load the ‘Core’ component.

Core Modules

As of March 2, 2009, the core modules are:

• DBIx::Class::InflateColumn - Useful for converting between DateTime objects and date/time fields among other things. See DBIx::Class::InflateColumn::DateTime for more sugar.
• DBIx::Class::Relationship - provides methods for defining inter-table relationships such as belongs_to and has_many.
• DBIx::Class::PK::Auto - enables automatic incremental primary keys.
• DBIx::Class::PK - methods for handling primary keys.
• DBIx::Class::Row - methods which act on rows derived from DBIx::Class::ResultSource objects.
• DBIx::Class::ResultSourceProxy::Table - provide class data table object and method proxies.

Other Interesting Components

• Timestamp - Works with InflateColumn::DateTime to automatically update and create time fields. For example:

__PACKAGE__->load_components(qw/TimeStamp Core/);

# later in ResultSource when defining a time based column
    "last_modified",
    {
        data_type     => "timestamp",
        set_on_create => '1',
        set_on_update => '1',
    },

• EncodedColumn - automatically encode a columns contents. Load before Core.

__PACKAGE__->load_components("EncodedColumn","Core");

# later in ResultSource when adding the password column

  "password",
  {
    data_type => "text",
    default_value => undef,
    is_nullable => 1,
    encode_column => 1,
    encode_class  => 'Crypt::Eksblowfish::Bcrypt',
    encode_args   => { key_nul => 0, cost => 8 },
    encode_check_method => 'check_password',
  },

table²

Set or get the table name.

add_columns²

Adds columns to the current class and create accessors for them. The accessors are simply the individual column names.

set_primary_key³

Defines one or more columns as the primary key for a source. Also defines a unique contraint named primary.

add_unique_constraint

Defines a unique constraint for a source.

__PACKAGE__->add_unique_constraint([qw/username/]);

ResultSource Example

An example of a ResultSource is:

package MyApp::Schema::Result::People::Student;

use strict;
use warnings;

use base 'DBIx::Class';

__PACKAGE__->load_components("Core");
__PACKAGE__->table("people.students");
__PACKAGE__->add_columns(
    "id",
    {
        data_type     => "integer",
        is_auto_increment => 1,
        is_nullable   => 0,
        size          => 4,
    },
    "person",
    {
        data_type     => "integer",
        default_value => undef,
        is_nullable   => 1,
        size          => 4
    },
);
__PACKAGE__->set_primary_key("id");

ResultSet

A DBIx::Class::ResultSet which acts like an iterator and a statement holder. Does not actually execute the SQL. This happens when a row object is called for.

Row

A class which provides methods on rows derived from a DBIC ResultSource. For example,

• insert
• update
• delete
• update_or_insert
• get_column
• result_source - get the ResultSource the object was created from.

Appendix

Using make_schema_at

Footnotes

¹ Comes from Class::C3::Componentised

² Comes from DBIx::Class::ResultSourceProxy::Table

³ Comes from DBIx::Class::ResultSource

My tags:

 

Popular tags: