/usr/share/perl5/DBIx/Class/Manual/QuickStart.pod is in libdbix-class-perl 0.082840-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 | =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>.
|