point out where in the docs a user is most likely to spend reading time

[dbsrgits/DBIx-Class.git] / lib / DBIx / Class / Manual / QuickStart.pod

=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$ echo .dump | sqlite3 db/example.db

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<MyDatabase>. The
C<MyDatabase::Main> 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 C<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 MyDatabase::Main qw();
    my $schema = MyDatabase::Main->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<MyDatabase::Main::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 MyDatabase/

    # recreate schema classes files from database file
    DBIx-Class/examples/Schema$ dbicdump \
        -o dump_directory=. MyDatabase::Main 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">.