.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "DBIx::Class::Manual::QuickStart 3pm"
.TH DBIx::Class::Manual::QuickStart 3pm "2014-10-23" "perl v5.20.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
DBIx::Class::Manual::QuickStart \- up and running with DBIC in 10 minutes
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This document shows the minimum amount of code to make you a productive \s-1DBIC\s0
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 \s-1SQL\s0 and how to connect to a
database through \s-1DBI.\s0
.PP
Follow along with the example database shipping with this distribution,
see directory \fIexamples/Schema\fR. This database is also used through-out the
rest of the documentation.
.SS "Preparation"
.IX Subsection "Preparation"
First, install DBIx::Class like you do with any other \s-1CPAN\s0 distribution.
See <http://www.cpan.org/modules/INSTALL.html> and perlmodinstall.
.PP
Then open the distribution in your shell and change to the subdirectory
mentioned earlier, the next command will download and unpack it:
.PP
.Vb 2
\&    $ perl \-mCPAN \-e\*(AqCPAN::Shell\->look("DBIx::Class")\*(Aq
\&    DBIx\-Class$ cd examples/Schema
.Ve
.PP
Inspect the database:
.PP
.Vb 1
\&    DBIx\-Class/examples/Schema$ sqlite3 db/example.db .dump
.Ve
.PP
You can also use a \s-1GUI\s0 database browser such as
SQLite Manager <https://addons.mozilla.org/firefox/addon/sqlite-manager>.
.PP
Have a look at the schema classes files in the subdirectory \fIMyApp\fR. The
\&\f(CW\*(C`MyApp::Schema\*(C'\fR class is the entry point for loading the other classes and
interacting with the database through \s-1DBIC\s0 and the \f(CW\*(C`Result\*(C'\fR classes correspond
to the tables in the database. DBIx::Class::Manual::Example shows how to
write all that Perl code. That is almost never necessary, though. Instead use
dbicdump (part of the distribution DBIx::Class::Schema::Loader) to
automatically create schema classes files from an existing database. The
chapter \*(L"Resetting the database\*(R" below shows an example invocation.
.SS "Connecting to the database"
.IX Subsection "Connecting to the database"
A schema object represents the database.
.PP
.Vb 2
\&    use MyApp::Schema qw();
\&    my $schema = MyApp::Schema\->connect(\*(Aqdbi:SQLite:db/example.db\*(Aq);
.Ve
.PP
The first four arguments are the same as for \*(L"connect\*(R" in \s-1DBI\s0.
.SS "Working with data"
.IX Subsection "Working with data"
Almost all actions go through a
resultset object.
.PP
\fIAdding data\fR
.IX Subsection "Adding data"
.PP
Via intermediate result objects:
.PP
.Vb 11
\&    my $artist_ma = $schema\->resultset(\*(AqArtist\*(Aq)\->create({
\&        name => \*(AqMassive Attack\*(Aq,
\&    });
\&    my $cd_mezz = $artist_ma\->create_related(cds => {
\&        title => \*(AqMezzanine\*(Aq,
\&    });
\&    for (\*(AqAngel\*(Aq, \*(AqTeardrop\*(Aq) {
\&        $cd_mezz\->create_related(tracks => {
\&            title => $_
\&        });
\&    }
.Ve
.PP
Via relation accessors:
.PP
.Vb 10
\&    $schema\->resultset(\*(AqArtist\*(Aq)\->create({
\&        name => \*(AqMetallica\*(Aq,
\&        cds => [
\&            {
\&                title => q{Kill \*(AqEm All},
\&                tracks => [
\&                    { title => \*(AqJump in the Fire\*(Aq },
\&                    { title => \*(AqWhiplash\*(Aq },
\&                ],
\&            },
\&            {
\&                title => \*(AqReLoad\*(Aq,
\&                tracks => [
\&                    { title => \*(AqThe Memory Remains\*(Aq },
\&                    { title => \*(AqThe Unforgiven II\*(Aq },
\&                    { title => \*(AqFuel\*(Aq },
\&                ],
\&            },
\&        ],
\&    });
.Ve
.PP
Columns that are not named are filled with default values. The value \f(CW\*(C`undef\*(C'\fR
acts as a \f(CW\*(C`NULL\*(C'\fR in the database.
.PP
See the chapter \*(L"Introspecting the schema classes\*(R" below to find out where
the non-obvious source name strings such as \f(CW\*(C`Artist\*(C'\fR and accessors such as
\&\f(CW\*(C`cds\*(C'\fR and \f(CW\*(C`tracks\*(C'\fR come from.
.PP
Set the environment variable \f(CW\*(C`DBI_TRACE=\*(Aq1|SQL\*(Aq\*(C'\fR to see the generated queries.
.PP
\fIRetrieving data\fR
.IX Subsection "Retrieving data"
.PP
Set up a condition.
.PP
.Vb 5
\&    my $artists_starting_with_m = $schema\->resultset(\*(AqArtist\*(Aq)\->search(
\&        {
\&            name => { like => \*(AqM%\*(Aq }
\&        }
\&    );
.Ve
.PP
Iterate over result objects of class \f(CW\*(C`MyApp::Schema::Result::Artist\*(C'\fR.
Result objects represent a row and
automatically get accessors for their column names.
.PP
.Vb 3
\&    for my $artist ($artists_starting_with_m\->all) {
\&        say $artist\->name;
\&    }
.Ve
.PP
\fIChanging data\fR
.IX Subsection "Changing data"
.PP
Change the release year of all CDs titled \fIReLoad\fR.
.PP
.Vb 9
\&    $schema\->resultset(\*(AqCd\*(Aq)\->search(
\&        {
\&            title => \*(AqReLoad\*(Aq,
\&        }
\&    )\->update_all(
\&        {
\&            year => 1997,
\&        }
\&    );
.Ve
.PP
\fIRemoving data\fR
.IX Subsection "Removing data"
.PP
Removes all tracks titled \fIFuel\fR regardless of which \s-1CD\s0 the belong to.
.PP
.Vb 5
\&    $schema\->resultset(\*(AqTrack\*(Aq)\->search(
\&        {
\&            title => \*(AqFuel\*(Aq,
\&        }
\&    )\->delete_all;
.Ve
.SS "Introspecting the schema classes"
.IX Subsection "Introspecting the schema classes"
This is useful for getting a feel for the naming of things in a \s-1REPL\s0 or during
explorative programming.
.PP
From the root to the details:
.PP
.Vb 3
\&    $schema\->sources;                       # returns qw(Cd Track Artist)
\&    $schema\->source(\*(AqCd\*(Aq)\->columns;         # returns qw(cdid artist title year)
\&    $schema\->source(\*(AqCd\*(Aq)\->relationships;   # returns qw(artist tracks)
.Ve
.PP
From a detail to the root:
.PP
.Vb 3
\&    $some_result\->result_source;            # returns appropriate source
\&    $some_resultset\->result_source;
\&    $some_resultsource\->schema;             # returns appropriate schema
.Ve
.SS "Resetting the database"
.IX Subsection "Resetting the database"
.Vb 2
\&    # 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 \e
\&        \-o dump_directory=. MyApp::Schema dbi:SQLite:db/example.db
.Ve
.SS "Where to go next"
.IX Subsection "Where to go next"
If you want to exercise what you learned with a more complicated schema,
load Northwind <http://code.google.com/p/northwindextended/> into your
database.
.PP
If you want to transfer your existing \s-1SQL\s0 knowledge, read
DBIx::Class::Manual::SQLHackers.
.PP
Continue with DBIx::Class::Tutorial and
\&\*(L"\s-1WHERE TO START READING\*(R"\s0 in DBIx::Class.
.SH "FURTHER QUESTIONS?"
.IX Header "FURTHER QUESTIONS?"
Check the list of additional \s-1DBIC\s0 resources.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This module is free software copyright
by the DBIx::Class (\s-1DBIC\s0) authors. You can
redistribute it and/or modify it under the same terms as the
DBIx::Class library.