1Storm::Tutorial(3) User Contributed Perl Documentation Storm::Tutorial(3)
2
6 Storm::Tutorial - Getting started with Storm
7
9 Storm is a Moose based library for storing and retrieving Moose based
10 objects using a DBI connection.
11
13 Storm connects to databases using the uqiquitous DBI module. Database
14 handles are spawned using a Storm::Source object which holds connection
15 information. In the example below, the Storm::Source object is coerced
16 from the arguments passed to the Storm constructor.
17 use Storm;
19 $storm->new(
21 source => ['DBI:mysql:timsdev:10.0.1.11:3306', 'user', 'pass']
22 );
23
25 Storm is for storing Moose based objects. It is required that the
26 objects have the Storm roles and meta-roles applied.
27 Storm::Object is an extension of Moose which applies the appropriate
29 roles and meta-roles, as well as providing some sugar for defining
30 relationships.
31 Simple example
33 package Person;
34 use Storm::Object;
35 storm_table( 'Person' );
36 has 'id' => (
38 is => 'rw',
39 traits => [qw(PrimaryKey AutoIncrement)],
40 );
41 has 'name' => (
43 is => 'rw',
44 );
45 has 'dob' => (
47 is => 'rw',
48 column => 'birth_date',
49 );
50 This is a very simple example, but demonstrates a few key concepts:
52 • Every class definition must have a meta-table defined. Storm uses
54 this information to determine what table to store the object to in
55 the database.
56 • It is recomended that every class provide a primary key (via the
58 PrimaryKey attribute trait.) If you do not provide a primary key,
59 you will not be able to use lookup queries to restore objects, nor
60 will any other Storm enabled object be able to store references to
61 it.
62 • Storm avoids requiring a separate schema by defining elements of a
64 schema in the object definition. By default, object attributes are
65 assigned a table column with the same name as the attribute. The
66 default behavior can be changed by setting the column option.
67 Circular references
69 package Person;
70 use Storm::Object;
71 storm_table( 'People' );
72 has 'id' => (
74 is => 'rw',
75 traits => [qw(PrimaryKey AutoIncrement)],
76 );
77 has 'spouse' => (
79 is => 'rw',
80 isa => 'Person',
81 weak_ref => 1,
82 );
83 • References to other Storm enabled classes are serialized
85 automatically using the primary key. This is accomplished by
86 setting the "isa" option to a Storm enabled class (type).
87 • In a scenario such as this, where two objects will reference each
89 other in a circular structure, it is necessary to set the weak_ref
90 option to avoid memory leaks. When constructing and using objects
91 with circular references, it is necessary to manage the "scope".
92 The scope stops objects from being garbage collected to early (i.e.
93 when the only references to them are weak.)
94
96 Relationships are devised in two ways. We demonstrated one manner in
97 the example above by setting an attributes "isa" option to a Storm
98 enabled class. This allows you to referance a singular object. Here we
99 will demonstrate making "one-to-many" and "many-to-many" relationships
100 using the "has_many" keyword.
101 One-to-many
103 package Person;
104 use Storm::Object;
105 storm_table( 'People' );
106 has 'id' => (
108 is => 'rw',
109 traits => [qw(PrimaryKey AutoIncrement)],
110 );
111 one_to_many 'pokemon' => (
113 foreign_class => 'Pokemon',
114 match_on => 'master',
115 handles => {
116 pokemon => 'iter',
117 }
118 );
119 package Pokemon;
121 use Storm::Object;
122 storm_->table( 'Pokemon' );
123 has 'id' => (
125 is => 'rw',
126 traits => [qw(PrimaryKey AutoIncrement)],
127 );
128 has 'master' => (
130 is => 'rw',
131 isa => 'Person',
132 weak_ref => 1,
133 );
134 Here, we define the components of a relationship between the Person
136 class and the Pokemon class uing the "one_to_many" keyword.
137 • The "foreign_key => master" denotes that the relationship is made
139 by matching the primary key of the Person with the c<master>
140 attribute of the Pokemon.
141 • Using the "handles" option, we create the "pokemon" method for
143 Person. This method returns a Person's Pokemon in the form of a
144 Storm::Query::Select::Iterator object.
145 • To add another Pokemon to a Person, create a new Pokemon and set
147 the "master" attribute to a $person.
148 Many-to-many
150 package Person;
151 use Storm::Object;
152 storm_table( 'People' );
153 has 'id' => (
155 is => 'rw',
156 traits => [qw(PrimaryKey AutoIncrement)],
157 );
158 many_to_many 'pets' => (
160 foreign_class => 'Pets',
161 junction_table => 'PeoplesPets',
162 local_match => 'person',
163 foreign_match => 'pet',
164 handles => {
165 parents => 'iter',
166 add_pet => 'add',
167 remove_pet => 'remove',
168 }
169 )
170 package Pet;
172 use Storm::Object;
173 storm_table( 'Pets' );
174 has 'id' => (
176 is => 'rw',
177 traits => [qw(PrimaryKey AutoIncrement)],
178 );
179 many_to_many 'care_takers' => (
181 foreign_class => 'Pets',
182 junction_table => 'PeoplesPets',
183 local_match => 'person',
184 foreign_match => 'pets',
185 handles => {
186 care_takers => 'iter',
187 add_care_taker => 'add',
188 remove_care_taker => 'remove',
189 }
190 )
191 • In a many-to-many relationship, a junction_table is required to
193 form the relationship. This is specified as an option to the
194 "many_to_many" keyword.
195 • We also need to define the columns in the junction_table that will
197 be used to identify the components of the relationship. This is
198 done with local_match and foreign_match options. local_match is the
199 column in the junction table to match with the primary key of
200 defining class, while foreign_match is the the column to match with
201 the primary key of the foregin class.
202 • Using the "handles" option, we create methods for retrieving a
204 Storm::Query::Select::Iterator, as well as methods for adding and
205 removing pets/caretakers. "$pet->add_care_taker( $person )" is
206 synanamous with "$person->add_pet( $pet )" and
207 "$pet->remove_care_taker( $person )" is synanamous with
208 "$person->remove_pet( $pet )".
209 • As of version 0.05, Storm will automatically fill in the
211 "junction_table", "local_match", and forerign match if you do not
212 supply them.
213 package Person;
215 use Storm::Object;
216 storm_table( 'People' );
217 has 'id' => (
219 is => 'rw',
220 traits => [qw(PrimaryKey AutoIncrement)],
221 );
222 many_to_many 'pets' => (
224 foreign_class => 'Pets',
225 handles => {
226 parents => 'iter',
227 add_pet => 'add',
228 remove_pet => 'remove',
229 }
230 )
231 package Pet;
233 use Storm::Object;
234 storm_table( 'Pets' );
235 has 'id' => (
237 is => 'rw',
238 traits => [qw(PrimaryKey AutoIncrement)],
239 );
240 many_to_many 'care_takers' => (
242 foreign_class => 'Pets',
243 handles => {
244 care_takers => 'iter',
245 add_care_taker => 'add',
246 remove_care_taker => 'remove',
247 }
248 )
249
251 Storm provides queries for the four basic data operations Create, Read,
252 Update, and Delete (CRUD) as well as a "select" query for searching.
253 Insert
255 $storm->insert( @objects );
256 Inserts @objects into the database. Objects may onle be inserted if
258 they do not already exist in the database. An error will be thrown if
259 you try to insert an object that already exists. An error will also be
260 thrown if the object has a primary key and it is undef (unless using
261 the AutoIncrement trait.)
262 Lookup
264 $storm->lookup( $class, @object_ids );
265 Retrieves object from the database by primary key. The $class attribute
267 is required so Storm knows where to find and how to inflate the
268 objects. If any of the object's attributes reference other Storm
269 enabled objects, they will be looked up and inflated as well. This will
270 continue until all dependent object have been retrieved and inflated.
271 Update
273 $storm->update( @objects );
274 Updates the state of the @objects in the database. If you try to call
276 "update" on an object that is not already in the database, an error
277 will be thrown. Only the @objects passed to "update" will be affected,
278 any Storm enabled objects they reference will not updated in the
279 database. You must call "update" on them yourself.
280 Delete
282 $storm->delete( @objects );
283 Deletes the @objects from the database. The local references to them
285 will still exists until you destroy them or they go out of scope.
286
288 Searching is possible using a select query. The select query is a
289 little more complex than it's counterparts.
290 Iterators
292 $query = $storm->select( 'Person' );
293 $iter = $query->results;
294 while ( $object = $iter->next ) {
296 ... do stuff with $object ...
298 }
300 Calling the "results" method on a select query returns a
302 Storm::Query::Select::Iterator for iterating over the result set.
303 Where
305 $query = $storm->select( 'Person' );
306 $query->where( '.last_name', '=', 'Simpson' );
307 $query->where( '.age', '>', 10 );
308 $iter = $query->results;
309 Use Storm::Query::Select's "where" method to select specific objects.
311 • The following comparisons are supported: =, <>, <, <=, =>, IN, NOT
313 IN, BETWEEN, LIKE, NOT LIKE
314 • It is possible to use attributes in a comparison with the
316 ".attribute" notation (to distinguish them from regular strings.)
317 $query->where( '.spouse.first_name', '=', 'Marge' );
319 If the attribute is also a Storm enabled object you can can
321 reference it's attributes in the comparison as well.
322 Placeholders
324 $query->where( '.age', '>', '?' );
325 $iter = $query->results( 10 );
326 You can use a "?" as placeholder. Supply the arguments to replace the
328 placeholders when calling the "results" method.
329 Order-by
331 $query->order_by( '.lastname', '.age DESC' );
332 Use the "order_by" method to sort the results.
334
336 The scope ensures that objects aren't garbage collected to early. As
337 objects are inflated from the database, the are pushed onto the live
338 object scope, increasing their reference count.
339 Let's define out person class to use as an example.
341 package Person;
343 use Storm::Object;
344 has 'id' => (
346 is => 'rw',
347 traits => [qw(PrimaryKey AutoIncrement)],
348 );
349 has 'name' => (
351 is => 'rw',
352 );
353 has 'spouse' => (
355 is => 'rw',
356 isa => 'Person',
357 weak_ref => 1,
358 );
359 Now, insert some objects into the database.
361 $storm->insert(
363 Person->new( name = 'Homer' ),
364 Person->new( name = 'Marge' )
365 );
366 And then we can link them together:
368 {
370 my $scope = $storm->new_scope;
371 my ( $homer, $marge ) = $storm->lookup( $homer_id, $marge_id );
373 $homer->spouse( $marge );
374 $marge->spouse( $homer );
375 $storm->update( $homer, $marge );
376 }
377 Now we can we can load the objects from the database like this:
379 {
381 my $scope = $storm->new_scope;
382 my $homer = $storm->lookup( $homer_id );
384 print $homer->spouse->name; # Marge
386 }
387 {
389 my $scope = $storm->new_scope;
390 my $marge = $storm->lookup( $marge_id );
392 print $marge->spouse->name; # Homer Simpson
394 refaddr( $marge ) == refaddr( $marge->spouse->spouse ); # true
396 }
397 When the initial object is loaded, all the objects that the initial
399 object depends on will be loaded. This will continue until all
400 dependent objects have been inflated from the database.
401 If we did not use a scope, by the time $homer his spouse attribute
403 would have been cleared because there is no other reference to Marge.
404 Here is a code snippet that demonstrates why:
405 sub get_homer {
407 my $homer = Person->new( name => 'Homer' );
408 my $marge = Person->new( name => 'Marge' );
409 $homer->spouse( $marge );
411 $marge->spouse( $homer );
412 return $homer;
414 # at this point $homer and $marge go out of scope
416 # $homer has a refcount of 1 because it's the return value
417 # $marge has a refcount of 0, and gets destroyed
418 # the weak reference in $homer->spouse is cleared
419 }
420 my $homer = get_homer();
422 $homer->spouse; # this returns undef
424 By using this idiom:
426 {
428 my $scope = Storm->new_scope;
429 ... do all Storm work in here ...
431 }
432 You are ensuring that the objects live at least as long as necessary.
434 In a web application context, you usually create one new scope per
436 request.
437 Credit
439 The live object scope was largely inspired by the KiokuDB module. Some
440 of the code and documentation for this functionality was taken directly
441 from the KiokuDB source (and possibly modified.)
442
444 When using a supporting databse, you can use the "do_transaction"
445 method to execute a code block and commit the transaction.
446 eval {
448 $storm->do_transaction( sub {
449 ... do work on $storm ...
451 });
453 }
454 print $@ if $@; # prints error
456 The transaction will only be committed if they block executes
458 successfully. If any exceptions are thrown, the transaction will be
459 rolled back. It is recommended that you execute the transaction inside
460 an eval block to trap any errors that are thrown. Alternatively, you
461 can use a module like TryCatch or Try::Tiny to trap errors.
462
464 The policy is used to determine what data type is used by the DBMS to
465 store a value. The policy also determines how different types of values
466 are inflated/deflated.
467 package My::Policy;
469 use Storm::Policy;
470 define 'DateTime', 'DATETIME';
472 transform 'DateTime',
474 inflate { DateTime::Form::SQLite->parse_datetime( $_ ) },
475 deflate { DateTime::Form::SQLite->format_datetime( $_ ) };
476 package main;
479 use Storm;
480 $storm->new( source => ..., policy => 'My::Policy' );
482 "define"
484 Use the "define" keyword to determine what data type the DBMS
485 should used to store a value of the given type. In this case we
486 want DateTime objects to be stored in the database using the
487 "DATETIME" data type.
488 "transform"
490 Use the "transform" keyword for setting a custom inflator/deflator
491 for a type.
492 The inflator is defined using the "inflate" keyword. The $_ special
494 variable will be set to the value to be inflated. The inflator is
495 expected to return the inflated value.
496 The deflator is defined using the "deflate" keyword. The $_ special
498 variable will be set to the value to be deflated. The deflator is
499 expected to return the deflated value.
500 Credit
502 The policy was inspired by the Fey::ORM module. Some of the code this
503 functionality was taken directly from theFey::ORM source (and possibly
504 modified.)
505
507 Aeolus is the greek god of the wind. Aeolus helps manage your database
508 installation. With Aeolus you can easily install and remove the tables
509 your classes need to store their data.
510 $storm->aeolus->install_class( 'Person' );
512 See Storm::Aeolus for more information.
514
516 Jeffrey Ray Hallock <jeffrey.hallock at gmail dot com>
517 Dave Rolsky <autarch@urth.org>
519 Yuval Kogman <nothingmuch@woobling.org>
521
523 Copyright (c) 2010-2011 Jeffrey Ray Hallock.
524 Copyright (c) 2010-2011 Dave Rolsky.
526 Copyright (c) 2008, 2009 Yuval Kogman, Infinity Interactive.
528 All rights reserved. This program is free software; you can redistribute it
530 and/or modify it under the same terms as Perl itself.
531
533 Hey! The above document had some coding errors, which are explained
534 below:
535 Around line 252:
537 '=item' outside of any '=over'
538perl v5.32.1 2021-01-27 Storm::Tutorial(3)