206 lines
6.3 KiB
Plaintext
206 lines
6.3 KiB
Plaintext
=head1 NAME
|
|
|
|
DBIx::Class::Manual::QuickStart - up and running with DBIC in 10 minutes
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
This document shows the minimum amount of code to make you a productive DBIC
|
|
user. It requires you to be familiar with just the basics of database
|
|
programming (what database tables, rows and columns are) and the basics of
|
|
Perl object-oriented programming (calling methods on an object instance).
|
|
It also helps if you already know a bit of SQL and how to connect to a
|
|
database through DBI.
|
|
|
|
Follow along with the example database shipping with this distribution,
|
|
see directory F<examples/Schema>. This database is also used through-out the
|
|
rest of the documentation.
|
|
|
|
=head2 Preparation
|
|
|
|
First, install DBIx::Class like you do with any other CPAN distribution.
|
|
See L<http://www.cpan.org/modules/INSTALL.html> and L<perlmodinstall>.
|
|
|
|
Then open the distribution in your shell and change to the subdirectory
|
|
mentioned earlier, the next command will download and unpack it:
|
|
|
|
$ perl -mCPAN -e'CPAN::Shell->look("DBIx::Class")'
|
|
DBIx-Class$ cd examples/Schema
|
|
|
|
Inspect the database:
|
|
|
|
DBIx-Class/examples/Schema$ sqlite3 db/example.db .dump
|
|
|
|
You can also use a GUI database browser such as
|
|
L<SQLite Manager|https://addons.mozilla.org/firefox/addon/sqlite-manager>.
|
|
|
|
Have a look at the schema classes files in the subdirectory F<MyApp>. The
|
|
C<MyApp::Schema> class is the entry point for loading the other classes and
|
|
interacting with the database through DBIC and the C<Result> classes correspond
|
|
to the tables in the database. L<DBIx::Class::Manual::Example> shows how to
|
|
write all that Perl code. That is almost never necessary, though. Instead use
|
|
L<dbicdump> (part of the distribution L<DBIx::Class::Schema::Loader>) to
|
|
automatically create schema classes files from an existing database. The
|
|
chapter L</"Resetting the database"> below shows an example invocation.
|
|
|
|
=head2 Connecting to the database
|
|
|
|
A L<schema|DBIx::Class::Manual::Glossary/Schema> object represents the database.
|
|
|
|
use MyApp::Schema qw();
|
|
my $schema = MyApp::Schema->connect('dbi:SQLite:db/example.db');
|
|
|
|
The first four arguments are the same as for L<DBI/connect>.
|
|
|
|
=head2 Working with data
|
|
|
|
Almost all actions go through a
|
|
L<resultset|DBIx::Class::Manual::Glossary/ResultSet> object.
|
|
|
|
=head3 Adding data
|
|
|
|
Via intermediate result objects:
|
|
|
|
my $artist_ma = $schema->resultset('Artist')->create({
|
|
name => 'Massive Attack',
|
|
});
|
|
my $cd_mezz = $artist_ma->create_related(cds => {
|
|
title => 'Mezzanine',
|
|
});
|
|
for ('Angel', 'Teardrop') {
|
|
$cd_mezz->create_related(tracks => {
|
|
title => $_
|
|
});
|
|
}
|
|
|
|
Via relation accessors:
|
|
|
|
$schema->resultset('Artist')->create({
|
|
name => 'Metallica',
|
|
cds => [
|
|
{
|
|
title => q{Kill 'Em All},
|
|
tracks => [
|
|
{ title => 'Jump in the Fire' },
|
|
{ title => 'Whiplash' },
|
|
],
|
|
},
|
|
{
|
|
title => 'ReLoad',
|
|
tracks => [
|
|
{ title => 'The Memory Remains' },
|
|
{ title => 'The Unforgiven II' },
|
|
{ title => 'Fuel' },
|
|
],
|
|
},
|
|
],
|
|
});
|
|
|
|
Columns that are not named are filled with default values. The value C<undef>
|
|
acts as a C<NULL> in the database.
|
|
|
|
See the chapter L</"Introspecting the schema classes"> below to find out where
|
|
the non-obvious source name strings such as C<Artist> and accessors such as
|
|
C<cds> and C<tracks> come from.
|
|
|
|
Set the environment variable C<DBI_TRACE='1|SQL'> to see the generated queries.
|
|
|
|
=head3 Retrieving data
|
|
|
|
Set up a condition.
|
|
|
|
my $artists_starting_with_m = $schema->resultset('Artist')->search(
|
|
{
|
|
name => { like => 'M%' }
|
|
}
|
|
);
|
|
|
|
Iterate over result objects of class C<MyApp::Schema::Result::Artist>.
|
|
L<Result|DBIx::Class::Manual::Glossary/Result> objects represent a row and
|
|
automatically get accessors for their column names.
|
|
|
|
for my $artist ($artists_starting_with_m->all) {
|
|
say $artist->name;
|
|
}
|
|
|
|
=head3 Changing data
|
|
|
|
Change the release year of all CDs titled I<ReLoad>.
|
|
|
|
$schema->resultset('Cd')->search(
|
|
{
|
|
title => 'ReLoad',
|
|
}
|
|
)->update_all(
|
|
{
|
|
year => 1997,
|
|
}
|
|
);
|
|
|
|
=head3 Removing data
|
|
|
|
Removes all tracks titled I<Fuel> regardless of which CD the belong to.
|
|
|
|
$schema->resultset('Track')->search(
|
|
{
|
|
title => 'Fuel',
|
|
}
|
|
)->delete_all;
|
|
|
|
=head2 Introspecting the schema classes
|
|
|
|
This is useful for getting a feel for the naming of things in a REPL or during
|
|
explorative programming.
|
|
|
|
From the root to the details:
|
|
|
|
$schema->sources; # returns qw(Cd Track Artist)
|
|
$schema->source('Cd')->columns; # returns qw(cdid artist title year)
|
|
$schema->source('Cd')->relationships; # returns qw(artist tracks)
|
|
|
|
From a detail to the root:
|
|
|
|
$some_result->result_source; # returns appropriate source
|
|
$some_resultset->result_source;
|
|
$some_resultsource->schema; # returns appropriate schema
|
|
|
|
=head2 Resetting the database
|
|
|
|
# delete database file
|
|
DBIx-Class/examples/Schema$ rm -f db/example.db
|
|
|
|
# create database and set up tables from definition
|
|
DBIx-Class/examples/Schema$ sqlite3 db/example.db < db/example.sql
|
|
|
|
# fill them with data
|
|
DBIx-Class/examples/Schema$ perl ./insertdb.pl
|
|
|
|
# delete the schema classes files
|
|
DBIx-Class/examples/Schema$ rm -rf MyApp
|
|
|
|
# recreate schema classes files from database file
|
|
DBIx-Class/examples/Schema$ dbicdump \
|
|
-o dump_directory=. MyApp::Schema dbi:SQLite:db/example.db
|
|
|
|
=head2 Where to go next
|
|
|
|
If you want to exercise what you learned with a more complicated schema,
|
|
load L<Northwind|http://code.google.com/p/northwindextended/> into your
|
|
database.
|
|
|
|
If you want to transfer your existing SQL knowledge, read
|
|
L<DBIx::Class::Manual::SQLHackers>.
|
|
|
|
Continue with L<DBIx::Class::Tutorial> and
|
|
L<DBIx::Class/"WHERE TO START READING">.
|
|
|
|
=head1 FURTHER QUESTIONS?
|
|
|
|
Check the list of L<additional DBIC resources|DBIx::Class/GETTING HELP/SUPPORT>.
|
|
|
|
=head1 COPYRIGHT AND LICENSE
|
|
|
|
This module is free software L<copyright|DBIx::Class/COPYRIGHT AND LICENSE>
|
|
by the L<DBIx::Class (DBIC) authors|DBIx::Class/AUTHORS>. You can
|
|
redistribute it and/or modify it under the same terms as the
|
|
L<DBIx::Class library|DBIx::Class/COPYRIGHT AND LICENSE>.
|