1DBIx::Class::Manual::QuUiscekrStCaorntt(r3i)buted Perl DDoBcIuxm:e:nCtlaatsiso:n:Manual::QuickStart(3)
2
3
4

NAME

6       DBIx::Class::Manual::QuickStart - up and running with DBIC in 10
7       minutes
8

DESCRIPTION

10       This document shows the minimum amount of code to make you a productive
11       DBIC user. It requires you to be familiar with just the basics of
12       database programming (what database tables, rows and columns are) and
13       the basics of Perl object-oriented programming (calling methods on an
14       object instance).  It also helps if you already know a bit of SQL and
15       how to connect to a database through DBI.
16
17       Follow along with the example database shipping with this distribution,
18       see directory examples/Schema. This database is also used through-out
19       the rest of the documentation.
20
21   Preparation
22       First, install DBIx::Class like you do with any other CPAN
23       distribution.  See <http://www.cpan.org/modules/INSTALL.html> and
24       perlmodinstall.
25
26       Then open the distribution in your shell and change to the subdirectory
27       mentioned earlier, the next command will download and unpack it:
28
29           $ perl -mCPAN -e'CPAN::Shell->look("DBIx::Class")'
30           DBIx-Class$ cd examples/Schema
31
32       Inspect the database:
33
34           DBIx-Class/examples/Schema$ sqlite3 db/example.db .dump
35
36       You can also use a GUI database browser such as SQLite Manager
37       <https://addons.mozilla.org/firefox/addon/sqlite-manager>.
38
39       Have a look at the schema classes files in the subdirectory MyApp. The
40       "MyApp::Schema" class is the entry point for loading the other classes
41       and interacting with the database through DBIC and the "Result" classes
42       correspond to the tables in the database. DBIx::Class::Manual::Example
43       shows how to write all that Perl code. That is almost never necessary,
44       though. Instead use dbicdump (part of the distribution
45       DBIx::Class::Schema::Loader) to automatically create schema classes
46       files from an existing database. The chapter "Resetting the database"
47       below shows an example invocation.
48
49   Connecting to the database
50       A schema object represents the database.
51
52           use MyApp::Schema qw();
53           my $schema = MyApp::Schema->connect('dbi:SQLite:db/example.db');
54
55       The first four arguments are the same as for "connect" in DBI.
56
57   Working with data
58       Almost all actions go through a resultset object.
59
60       Adding data
61
62       Via intermediate result objects:
63
64           my $artist_ma = $schema->resultset('Artist')->create({
65               name => 'Massive Attack',
66           });
67           my $cd_mezz = $artist_ma->create_related(cds => {
68               title => 'Mezzanine',
69           });
70           for ('Angel', 'Teardrop') {
71               $cd_mezz->create_related(tracks => {
72                   title => $_
73               });
74           }
75
76       Via relation accessors:
77
78           $schema->resultset('Artist')->create({
79               name => 'Metallica',
80               cds => [
81                   {
82                       title => q{Kill 'Em All},
83                       tracks => [
84                           { title => 'Jump in the Fire' },
85                           { title => 'Whiplash' },
86                       ],
87                   },
88                   {
89                       title => 'ReLoad',
90                       tracks => [
91                           { title => 'The Memory Remains' },
92                           { title => 'The Unforgiven II' },
93                           { title => 'Fuel' },
94                       ],
95                   },
96               ],
97           });
98
99       Columns that are not named are filled with default values. The value
100       "undef" acts as a "NULL" in the database.
101
102       See the chapter "Introspecting the schema classes" below to find out
103       where the non-obvious source name strings such as "Artist" and
104       accessors such as "cds" and "tracks" come from.
105
106       Set the environment variable "DBI_TRACE='1|SQL'" to see the generated
107       queries.
108
109       Retrieving data
110
111       Set up a condition.
112
113           my $artists_starting_with_m = $schema->resultset('Artist')->search(
114               {
115                   name => { like => 'M%' }
116               }
117           );
118
119       Iterate over result objects of class "MyApp::Schema::Result::Artist".
120       Result objects represent a row and automatically get accessors for
121       their column names.
122
123           for my $artist ($artists_starting_with_m->all) {
124               say $artist->name;
125           }
126
127       Changing data
128
129       Change the release year of all CDs titled ReLoad.
130
131           $schema->resultset('Cd')->search(
132               {
133                   title => 'ReLoad',
134               }
135           )->update_all(
136               {
137                   year => 1997,
138               }
139           );
140
141       Removing data
142
143       Removes all tracks titled Fuel regardless of which CD the belong to.
144
145           $schema->resultset('Track')->search(
146               {
147                   title => 'Fuel',
148               }
149           )->delete_all;
150
151   Introspecting the schema classes
152       This is useful for getting a feel for the naming of things in a REPL or
153       during explorative programming.
154
155       From the root to the details:
156
157           $schema->sources;                       # returns qw(Cd Track Artist)
158           $schema->source('Cd')->columns;         # returns qw(cdid artist title year)
159           $schema->source('Cd')->relationships;   # returns qw(artist tracks)
160
161       From a detail to the root:
162
163           $some_result->result_source;            # returns appropriate source
164           $some_resultset->result_source;
165           $some_resultsource->schema;             # returns appropriate schema
166
167   Resetting the database
168           # delete database file
169           DBIx-Class/examples/Schema$ rm -f db/example.db
170
171           # create database and set up tables from definition
172           DBIx-Class/examples/Schema$ sqlite3 db/example.db < db/example.sql
173
174           # fill them with data
175           DBIx-Class/examples/Schema$ perl ./insertdb.pl
176
177           # delete the schema classes files
178           DBIx-Class/examples/Schema$ rm -rf MyApp
179
180           # recreate schema classes files from database file
181           DBIx-Class/examples/Schema$ dbicdump \
182               -o dump_directory=. MyApp::Schema dbi:SQLite:db/example.db
183
184   Where to go next
185       If you want to exercise what you learned with a more complicated
186       schema, load Northwind <http://code.google.com/p/northwindextended/>
187       into your database.
188
189       If you want to transfer your existing SQL knowledge, read
190       DBIx::Class::Manual::SQLHackers.
191
192       Continue with DBIx::Class::Tutorial and "WHERE TO START READING" in
193       DBIx::Class.
194

FURTHER QUESTIONS?

196       Check the list of additional DBIC resources.
197
199       This module is free software copyright by the DBIx::Class (DBIC)
200       authors. You can redistribute it and/or modify it under the same terms
201       as the DBIx::Class library.
202
203
204
205perl v5.36.0                      2023-01-20DBIx::Class::Manual::QuickStart(3)
Impressum