.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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 >0, 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
.\" ========================================================================
.\"
.IX Title "DBIx::Class::Manual::QuickStart 3pm"
.TH DBIx::Class::Manual::QuickStart 3pm "2022-05-21" "perl v5.34.0" "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.