This document provides an overview of using DBIx::Class, an Object Relational Mapper (ORM) for Perl, targeting beginners with some background in Perl and databases. It covers table setup, CRUD operations, schema creation, relationships, and debugging tips, along with practical examples to illustrate the concepts. The talk aims to help users avoid common mistakes and accelerate their learning process within DBIx::Class.

1. DBIx::Class (aka DBIC)
for (advanced) beginners
Leo Lapworth @ YAPC::EU 2010
http://leo.cuckoo.org/projects/

2. assumptions
You know a little about Perl
and using objects
You know a little bit about
databases and using foreign
keys

3. DBIx::Class?
• ORM (object relational mapper)
• SQL <-> OO (using objects instead of SQL)
• Simple, powerful, complex, fab and confusing
• There are many ORMs, DBIx::Class just happens to
be the best in Perl (personal opinion)

4. why this talk?
• Help avoid mistakes I made!
• Help learn DBIx::Class faster
• Make your coding easier

5. table setup

6. example...
Books
Authors

7. authors table
CREATE TABLE authors(
id int(8) primary key auto_increment,
name varchar(255)
) engine = InnoDB DEFAULT CHARSET=utf8;

8. tips
Name tables as simple plurals (add an S) -
makes relationships easier to understand
(issue: Matt Trout "Tables should not be plural as gives you plurals for Result::
package names which represent a single row" - talk may be rewritten in future
to reflect this as this is better once you understand the relationship setup -
either way, consistency is important)
Use a character set (UTF8) from the start
(for international characters)

9. authors table
CREATE TABLE author s(
id int(8) primary key auto_increment,
name varchar(255)
) engine = InnoDB DEFAULT CHARSET= utf8;

10. books table
CREATE TABLE books(
id int(8) primary key auto_increment,
title varchar(255),
author int(8),
foreign key (author)
references authors(id)
) engine = InnoDB DEFAULT CHARSET=utf8;

11. tips
Name link fields as singular
Check foreign key is the same field type and
size in both tables

12. books table
CREATE TABLE books(
id int(8) primary key auto_increment,
title varchar(255),
author int(8),
foreign key ( author)
references authors(id)
) engine = InnoDB DEFAULT CHARSET=utf8;

13. CRUD compared
C - Create
R - Retrieve
U - Update
D - Delete

14. Manual (SQL)

15. manual: create
my $sth = $dbh->prepare('
INSERT INTO books
(title, author)
values (?,?)
');
$sth->execute(
'A book title',$author_id
);

16. manual: create
my $sth = $dbh->prepare('
INSERT INTO books
(title, author)
values (?,?)
');
$sth->execute(
'A book title', $author_id
);

17. manual: retrieve
my $sth = $dbh->prepare('
SELECT title,
authors.name as author_name
FROM books, authors
WHERE books.author = authors.id
');

18. manual: retrieve
while( my $book = $sth->fetchrow_hashref() )
{
print 'Author of '
. $book->{title}
. ' is '
. $book->{author_name}
. "n";
}

19. manual: update
my $update = $dbh->prepare('
UPDATE books
SET title = ?
WHERE id = ?
');
$update->execute(
'New title', $book_id);

20. manual: delete
my $delete = $dbh->prepare('
DELETE FROM books
WHERE id = ?
');
$delete->execute( $book_id);

21. DBIx::Class

22. DBIC: create
my $book = $book_model->create({
title => 'A book title',
author => $author_id,
});
Look ma, no SQL!
Tip: do not pass in primary_key field, even if its empty/undef as the
object returned will have an empty id, even if your field is auto
increment.

23. DBIC: create
my $book = $book_model->create({
title => 'A book title',
author => $author_id,
});

24. DBIC: create
my $pratchett = $author_model->create({
name => 'Terry Pratchett',
});

25. DBIC: create
my $book = $pratchett->create_related(
'books', {
title => 'Another Discworld book',
});
or
my $book = $pratchett->add_to_books({
title => 'Another Discworld book',
});

26. DBIC: create
my $book = $pratchett->create_related(
'books', {
title => 'Another Discworld book',
});
or
my $book = $pratchett->add_to_books({
title => 'Another Discworld book',
});

27. DBIC: retrieve
DBIx::Class - Lots of ways to do the same thing...
"There is more than one way to do it (TIMTOWTDI,
usually pronounced "Tim Toady") is a Perl motto"

28. DBIC: retrieve
my $book = $book_model->find($book_id);
my $book = $book_model->search({
title => 'A book title',
})->single();
my @books = $book_model->search({
author => $author_id,
})->all();

29. DBIC: retrieve
while( my $book = $books_rs->next() ) {
print 'Author of '
. $book->title()
. ' is '
. $book->author()->name()
. "n";
}

30. DBIC: retrieve
my $books_rs = $book_model->search({
author => $author_id,
});
Search takes SQL::Abstract formatted queries
> perldoc SQL::Abstract

31. DBIC: update
$book->update({
title => 'New title',
});

32. DBIC: delete
$book->delete();

33. Creating schemas

36. too much
typing!
too much
maintenance!

37. Schema::Loader
Database introspection -> Code

38. Use namespaces

39. Use Namespaces
Splits logic cleanly
Bookstore::Schema::Result::X
= an individual row
Bookstore::Schema:: ResultSet::X
= searches / results

43. You can edit this line

44. Connection details

45. using your Schema

48. DEBUGGING
DBIC_TRACE=1 ./your_script.pl

49. SQL - debugging
INSERT INTO authors (name)
VALUES (?): 'Douglas Adams'
INSERT INTO books (author, title)
VALUES (?, ?): '1', '42'

50. overloading
Bookstore::Schema::Result::Books
Bookstore::Schema::ResultSet::Books
Bookstore::Schema::Result::Authors
Bookstore::Schema::ResultSet::Authors

51. Result::
package Bookstore::Schema::Result::Books;
use base 'DBIx::Class';
#...
# Created by DBIx::Class::Schema::Loader v0.04005 @ 2010-08-01 09:19:1
# DO NOT MODIFY THIS OR ANYTHING ABOVE! md5sum:ta+cEh31lDfqcue3OmUCfQ
sub isbn {
my $self = shift;
# search amazon or something
my $api = Amazon::API->book({
title => $self->title()
});
return $api->isbn();
}
1;

52. Result::
package Bookstore::Schema::Result::Books;
use base 'DBIx::Class';
#...
# Created by DBIx::Class::Schema::Loader v0.04005 @ 2010-08-01 09:19:1
# DO NOT MODIFY THIS OR ANYTHING ABOVE! md5sum:ta+cEh31lDfqcue3OmUCfQ
sub isbn {
my $self = shift;
# search amazon or something
my $api = Amazon::API->book({
title => $self->title()
});
return $api->isbn();
}
1;

53. Result::
print $book->isbn();

54. Result:: (inflating)
package Bookstore::Schema::Result::Books;
use base 'DBIx::Class';
#...
use DateTime::Format::MySQL;
__PACKAGE__->inflate_column(
'date_published',
{ inflate => sub {
DateTime::Format::MySQL->parse_date(shift);
},
deflate => sub {
shift->ymd();
},
}
);
# Automatic see: DBIx::Class::InflateColumn::DateTime

55. Result:: (inflating)
package Bookstore::Schema::Result::Books;
use base 'DBIx::Class';
#...
use DateTime::Format::MySQL;
__PACKAGE__->inflate_column(
'date_published',
{ inflate => sub {
DateTime::Format::MySQL->parse_date(shift);
},
deflate => sub {
shift->ymd();
},
}
);
# Automatic see: DBIx::Class::InflateColumn::DateTime

56. Result:: (deflating)
$book->date_published(DateTime->now);
$book->update();
2008-12-31

57. Result:: (inflating)
my $date_published = $book->date_published()
print $date_published->month_abbr();
Nov

58. ResultSets::
package Bookstore::Schema::ResultSet::Books;
use base 'DBIx::Class::ResultSet';
#...
sub the_ultimate_books {
my $self = shift;
return $self->search(
{ title => {
'like', '%42%'
}
});
}
sub by_author {
my ( $self, $author ) = @_;
return $self->search( { author => $author->id(), } );
}

59. ResultSets::
package Bookstore::Schema::ResultSet::Books;
use base 'DBIx::Class::ResultSet';
#...
sub the_ultimate_books {
my $self = shift;
return $self->search(
{ title => {
'like', '%42%'
}
});
}
sub by_author {
my ( $self, $author ) = @_;
return $self->search( { author => $author->id(), } );
}

60. ResultSets::
package Bookstore::Schema::ResultSet::Books;
use base 'DBIx::Class::ResultSet';
#...
sub the_ultimate_books {
my $self = shift;
return $self->search(
{ title => {
'like', '%42%'
}
});
}
sub by_author {
my ( $self, $author ) = @_;
return $self->search( {
author => $author->id(),
} );
}

61. ResultSets::
use Bookstore::Schema;
my $book_model = Bookstore::Schema->resultset('Books');
my $book_rs = $book_model->the_ultimate_books();
my @books = $book_rs->all();

62. ResultSets::chaining
use Bookstore::Schema;
my $book_model = Bookstore::Schema->resultset('Books');
my $author_model = Bookstore::Schema->resultset('Authors');
my $author = $author_model->search({
name => 'Douglas Adams',
})->single();
my $book_rs = $book_model->the_ultimate_books()
->by_author($author);
my @books = $book_rs->all();

63. ResultSets::chaining
my $book_rs = $book_model
->the_ultimate_books()
->by_author($author);
or
my $book_rs = $book_model
->the_ultimate_books();
$book_rs = $book_rs->by_author($author);
# Debug (SQL):
# SELECT me.id, me.title, me.date_published, me.author
# FROM books me
# WHERE ( ( ( author = ? ) AND ( title LIKE ? ) ) ): '1', '%42%'

64. ResultSets::chaining
my $rs = $book_model
->category('childrens')
->by_author($author)
->published_after('1812')
->first_page_contains('once upon')
->rating_greater_than(4);
my @books = $rs->all();

65. overloading before
new record

66. overloading before
new record
package Bookstore::Schema::Result::Authors;
use base 'DBIx::Class';
sub new {
my ( $class, $attrs ) = @_;
# Mess with $attrs
my $new = $class->next::method($attrs);
return $new;
}
1;

67. relationships

68. multiple authors

69. a few relationships
has_many has_many
Authors Authors_and_Books Books
belongs_to belongs_to
many_to_many

70. a few relationships
!

71. new join table
CREATE TABLE author_and_books(
id int(8) primary key auto_increment,
book ! int(8),
author int(8),
foreign key (book) references books(id),
foreign key (author) references authors(id)
) engine = InnoDB DEFAULT CHARSET=utf8;
ALTER TABLE `books` DROP COLUMN `author`;

72. new join table
CREATE TABLE author_and_books(
id int(8) primary key auto_increment,
book ! int(8),
author int(8),
foreign key (book) references books(id),
foreign key (author) references authors(id)
) engine = InnoDB DEFAULT CHARSET=utf8;

73. has_many
has_many
Books Authors_and_Books
belongs_to

74. has_many
package Bookstore::Schema::Result::Books;
__PACKAGE__->has_many(
"author_and_books",
"Bookstore::Schema::Result::AuthorAndBooks",
{ "foreign.book" => "self.id" },
);
# This is auto generated by Schema::Loader

75. has_many
package Bookstore::Schema::Result::Books;
__PACKAGE__->has_many(
"author_and_books",
# Name of accessor
"Bookstore::Schema::Result::AuthorAndBooks",
# Related class
{ "foreign.book" => "self.id" },
# Relationship (magic often works if not
# specified, but avoid!)
);

76. belongs_to
has_many
Books Authors_and_Books
belongs_to

77. belongs_to
package Bookstore::Schema::Result::AuthorAndBooks;
__PACKAGE__->belongs_to(
"book",
"Bookstore::Schema::Result::Books",
{ id => "book" }
);
# This is auto generated by Schema::Loader

78. belongs_to
package Bookstore::Schema::Result::AuthorAndBooks;
__PACKAGE__->belongs_to(
"book", # Accessor name
"Bookstore::Schema::Result::Books",
# Related class
{ id => "book" } # Relationship
);

79. same for Authors
has_many
Authors Authors_and_Books
belongs_to

80. with no coding...
has_many has_many
Authors Authors_and_Books Books
belongs_to belongs_to

81. many_to_many
has_many has_many
Authors Authors_and_Books Books
belongs_to belongs_to
many_to_many

82. many_to_many
package Bookstore::Schema::Result::Books;
use base 'DBIx::Class';
__PACKAGE__->many_to_many(
"authors"
=> "author_and_books",
'author'
);
1;
# This is NOT auto generated by Schema::Loader

83. many_to_many
package Bookstore::Schema::Result::Books;
use base 'DBIx::Class';
__PACKAGE__->many_to_many(
"authors"
# Accessor Name
=> "author_and_books",
# has_many accessor_name
'author'
# foreign relationship name
);
1;

84. many_to_many
package Bookstore::Schema::Result::Authors;
use base 'DBIx::Class';
__PACKAGE__->many_to_many(
"books"
# Accessor Name
=> "author_and_books",
# has_many accessor_name
'book'
# foreign relationship name
);
1;
# This is NOT auto generated by Schema::Loader

85. using many_to_many
#!/usr/bin/perl
use Bookstore::Schema;
my $author_model = Bookstore::Schema->resultset('Authors');
my $author = $author_model->search({
name => 'Douglas Adams',
})->single();
$author->add_to_books({
title => 'A new book',
});

86. using many_to_many
my $author = $author_model->search({
name => 'Douglas Adams',
})->single();
$author->add_to_books({
title => 'A new book',
});
# SELECT me.id, me.name FROM authors me
# WHERE ( name = ? ): 'Douglas Adams';
# INSERT INTO books (title) VALUES (?): 'A new book';
# INSERT INTO author_and_books (author, book)
# VALUES (?, ?): '5', '2';

87. using many_to_many
$author->add_to_books($book);
$book->add_to_authors($author_1);
$book->add_to_authors($author_2);

88. in 16 lines of code
has_many has_many
Authors Authors_and_Books Books
belongs_to belongs_to
many_to_many

89. errors
Read them closely!

90. error messages
DBIx::Class::Schema::Loader::connection
(): Failed to load external class
definition for
'Bookstore::Schema::Result::Authors':
Can't locate object method
"many_to_many" via package
"Bookstore::Schema::Result::Author" at
lib/Bookstore/Schema/Result/Authors.pm
line 9.
Compilation failed in require at /
Library/Perl/5.8.8/DBIx/Class/Schema/
Loader/Base.pm line 292.

91. error messages
DBIx::Class::Schema::Loader::connection
(): Failed to load external class
definition for
'Bookstore::Schema::Result::Authors':
Can't locate object method
"many_to_many" via package
"Bookstore::Schema::Result::Author" at
lib/Bookstore/Schema/Result/Authors.pm
line 9.
Compilation failed in require at /
Library/Perl/5.8.8/DBIx/Class/Schema/
Loader/Base.pm line 292.

92. errors
• Turn on debugging
• Read error messages (sometimes useful!)
• Check field names
• Check package names
• Check which database you are connected
to (development/test/live?) - repeat above

93. thanks
http://leo.cuckoo.org/projects/
Time for bonus slides?

94. Template Toolkit
• [% author.books.count %] not working?
• TT all methods are called in list context
• [% author.books_rs.count %] scalar context
Available for all relationships

95. Catalyst
package Your::App::Model::Bookstore;
use base qw(Catalyst::Model::DBIC::Schema);
use strict;
use warnings;
__PACKAGE__->config(
schema_class => 'Bookstore::Schema',
);
1;

96. Catalyst
package Your::App::Model::Bookstore;
use base qw(Catalyst::Model::DBIC::Schema);
use strict;
use warnings;
__PACKAGE__->config(
schema_class => 'Bookstore::Schema',
);
1;
Keep your Scheme in a separate
package to your Catalyst application

97. Catalyst
sub action_name : Local {
my ($self, $c) = @_;
my $model = $c->model('Bookstore');
my $author_model = $model->resultset('Authors');
}
1;

98. thanks!
http://leo.cuckoo.org/projects/