From: Lars Dɪᴇᴄᴋᴏᴡ 迪拉斯 Date: Sun, 24 Mar 2013 11:38:23 +0000 (+0100) Subject: quick-start documentation X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=113e8d16;p=dbsrgits%2FDBIx-Class-Historic.git quick-start documentation * ready-to-use database file and schema classes * introduce CD year column (already used in ::ResultSet docs) * link from main synopsis --- diff --git a/examples/Schema/MyDatabase/Main/Result/Cd.pm b/examples/Schema/MyDatabase/Main/Result/Cd.pm index 6a465a1..9dc1f4e 100644 --- a/examples/Schema/MyDatabase/Main/Result/Cd.pm +++ b/examples/Schema/MyDatabase/Main/Result/Cd.pm @@ -7,7 +7,7 @@ use base qw/DBIx::Class::Core/; __PACKAGE__->table('cd'); -__PACKAGE__->add_columns(qw/ cdid artist title/); +__PACKAGE__->add_columns(qw/ cdid artist title year /); __PACKAGE__->set_primary_key('cdid'); diff --git a/examples/Schema/db/example.db b/examples/Schema/db/example.db new file mode 100644 index 0000000..a7d8330 Binary files /dev/null and b/examples/Schema/db/example.db differ diff --git a/examples/Schema/db/example.sql b/examples/Schema/db/example.sql index 4bc6cb6..3aeba46 100644 --- a/examples/Schema/db/example.sql +++ b/examples/Schema/db/example.sql @@ -6,7 +6,8 @@ CREATE TABLE artist ( CREATE TABLE cd ( cdid INTEGER PRIMARY KEY, artist INTEGER NOT NULL REFERENCES artist(artistid), - title TEXT NOT NULL + title TEXT NOT NULL, + year DATETIME ); CREATE TABLE track ( diff --git a/lib/DBIx/Class.pm b/lib/DBIx/Class.pm index e7b505b..ff649a3 100644 --- a/lib/DBIx/Class.pm +++ b/lib/DBIx/Class.pm @@ -137,6 +137,11 @@ list below is sorted by "fastest response time": =head1 SYNOPSIS +For the very impatient: L + +This code in the next step can be generated automatically from an existing +database, see L from the distribution C. + =head2 Schema classes preparation Create a schema class called F: diff --git a/lib/DBIx/Class/Manual/QuickStart.pod b/lib/DBIx/Class/Manual/QuickStart.pod new file mode 100644 index 0000000..c589111 --- /dev/null +++ b/lib/DBIx/Class/Manual/QuickStart.pod @@ -0,0 +1,194 @@ +=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. 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 and L. + +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. + +Have a look at the schema classes files in the subdirectory F. The +C class is the entry point for loading the other classes and +interacting with the database through DBIC and the C classes correspond +to the tables in the database. L shows how to +write all that Perl code. That is almost never necessary, though. Instead use +L (part of the distribution C) to +automatically create schema classes files from an existing database. The +chapter L below shows an example invocation. + +=head2 Connecting to the database + +A L 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. + +=head2 Working with data + +Almost all actions go through a +L 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 +acts as a C in the database. + +See the chapter L below to find out where +the non-obvious source name strings such as C and accessors such as +C and C come from. + +Set the environment variable C 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. +L 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. + + $schema->resultset('Cd')->search( + { + title => 'ReLoad', + } + )->update_all( + { + year => 1997, + } + ); + +=head3 Removing data + +Removes all tracks titled I 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 into your +database. + +If you want to transfer your existing SQL knowledge, read +L. + +Continue with L and +L.