Initial Commit

database/perl/vendor/lib/DBIx/Class/Manual/QuickStart.pod

@@ -0,0 +1,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>.