1DBIx::Class::Manual::QuUiscekrStCaorntt(r3i)buted Perl DDoBcIuxm:e:nCtlaatsiso:n:Manual::QuickStart(3)
2
6 DBIx::Class::Manual::QuickStart - up and running with DBIC in 10
7 minutes
8
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 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 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 Then open the distribution in your shell and change to the subdirectory
27 mentioned earlier, the next command will download and unpack it:
28 $ perl -mCPAN -e'CPAN::Shell->look("DBIx::Class")'
30 DBIx-Class$ cd examples/Schema
31 Inspect the database:
33 DBIx-Class/examples/Schema$ sqlite3 db/example.db .dump
35 You can also use a GUI database browser such as SQLite Manager
37 <https://addons.mozilla.org/firefox/addon/sqlite-manager>.
38 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 Connecting to the database
50 A schema object represents the database.
51 use MyApp::Schema qw();
53 my $schema = MyApp::Schema->connect('dbi:SQLite:db/example.db');
54 The first four arguments are the same as for "connect" in DBI.
56 Working with data
58 Almost all actions go through a resultset object.
59 Adding data
61 Via intermediate result objects:
63 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 Via relation accessors:
77 $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 Columns that are not named are filled with default values. The value
100 "undef" acts as a "NULL" in the database.
101 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 Set the environment variable "DBI_TRACE='1|SQL'" to see the generated
107 queries.
108 Retrieving data
110 Set up a condition.
112 my $artists_starting_with_m = $schema->resultset('Artist')->search(
114 {
115 name => { like => 'M%' }
116 }
117 );
118 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 for my $artist ($artists_starting_with_m->all) {
124 say $artist->name;
125 }
126 Changing data
128 Change the release year of all CDs titled ReLoad.
130 $schema->resultset('Cd')->search(
132 {
133 title => 'ReLoad',
134 }
135 )->update_all(
136 {
137 year => 1997,
138 }
139 );
140 Removing data
142 Removes all tracks titled Fuel regardless of which CD the belong to.
144 $schema->resultset('Track')->search(
146 {
147 title => 'Fuel',
148 }
149 )->delete_all;
150 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 From the root to the details:
156 $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 From a detail to the root:
162 $some_result->result_source; # returns appropriate source
164 $some_resultset->result_source;
165 $some_resultsource->schema; # returns appropriate schema
166 Resetting the database
168 # delete database file
169 DBIx-Class/examples/Schema$ rm -f db/example.db
170 # create database and set up tables from definition
172 DBIx-Class/examples/Schema$ sqlite3 db/example.db < db/example.sql
173 # fill them with data
175 DBIx-Class/examples/Schema$ perl ./insertdb.pl
176 # delete the schema classes files
178 DBIx-Class/examples/Schema$ rm -rf MyApp
179 # 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 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 If you want to transfer your existing SQL knowledge, read
190 DBIx::Class::Manual::SQLHackers.
191 Continue with DBIx::Class::Tutorial and "WHERE TO START READING" in
193 DBIx::Class.
194
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.
202perl v5.36.0 2023-01-20DBIx::Class::Manual::QuickStart(3)