1DBIx::Class::Schema(3)User Contributed Perl DocumentationDBIx::Class::Schema(3)
2
6 DBIx::Class::Schema - composable schemas
7
9 package Library::Schema;
10 use base qw/DBIx::Class::Schema/;
11 # load all Result classes in Library/Schema/Result/
13 __PACKAGE__->load_namespaces();
14 package Library::Schema::Result::CD;
16 use base qw/DBIx::Class::Core/;
17 __PACKAGE__->load_components(qw/InflateColumn::DateTime/); # for example
19 __PACKAGE__->table('cd');
20 # Elsewhere in your code:
22 my $schema1 = Library::Schema->connect(
23 $dsn,
24 $user,
25 $password,
26 { AutoCommit => 1 },
27 );
28 my $schema2 = Library::Schema->connect($coderef_returning_dbh);
30 # fetch objects using Library::Schema::Result::DVD
32 my $resultset = $schema1->resultset('DVD')->search( ... );
33 my @dvd_objects = $schema2->resultset('DVD')->search( ... );
34
36 Creates database classes based on a schema. This is the recommended way
37 to use DBIx::Class and allows you to use more than one concurrent
38 connection with your classes.
39 NB: If you're used to Class::DBI it's worth reading the "SYNOPSIS"
41 carefully, as DBIx::Class does things a little differently. Note in
42 particular which module inherits off which.
43
45 load_namespaces
46 Arguments: %options?
47 package MyApp::Schema;
49 __PACKAGE__->load_namespaces();
50 __PACKAGE__->load_namespaces(
52 result_namespace => 'Res',
53 resultset_namespace => 'RSet',
54 default_resultset_class => '+MyApp::Othernamespace::RSet',
55 );
56 With no arguments, this method uses Module::Find to load all of the
58 Result and ResultSet classes under the namespace of the schema from
59 which it is called. For example, "My::Schema" will by default find and
60 load Result classes named "My::Schema::Result::*" and ResultSet classes
61 named "My::Schema::ResultSet::*".
62 ResultSet classes are associated with Result class of the same name.
64 For example, "My::Schema::Result::CD" will get the ResultSet class
65 "My::Schema::ResultSet::CD" if it is present.
66 Both Result and ResultSet namespaces are configurable via the
68 "result_namespace" and "resultset_namespace" options.
69 Another option, "default_resultset_class" specifies a custom default
71 ResultSet class for Result classes with no corresponding ResultSet.
72 All of the namespace and classname options are by default relative to
74 the schema classname. To specify a fully-qualified name, prefix it
75 with a literal "+". For example, "+Other::NameSpace::Result".
76 Warnings
78 You will be warned if ResultSet classes are discovered for which there
80 are no matching Result classes like this:
81 load_namespaces found ResultSet class $classname with no corresponding Result class
83 If a ResultSource instance is found to already have a ResultSet class
85 set using resultset_class to some other class, you will be warned like
86 this:
87 We found ResultSet class '$rs_class' for '$result_class', but it seems
89 that you had already set '$result_class' to use '$rs_set' instead
90 Examples
92 # load My::Schema::Result::CD, My::Schema::Result::Artist,
94 # My::Schema::ResultSet::CD, etc...
95 My::Schema->load_namespaces;
96 # Override everything to use ugly names.
98 # In this example, if there is a My::Schema::Res::Foo, but no matching
99 # My::Schema::RSets::Foo, then Foo will have its
100 # resultset_class set to My::Schema::RSetBase
101 My::Schema->load_namespaces(
102 result_namespace => 'Res',
103 resultset_namespace => 'RSets',
104 default_resultset_class => 'RSetBase',
105 );
106 # Put things in other namespaces
108 My::Schema->load_namespaces(
109 result_namespace => '+Some::Place::Results',
110 resultset_namespace => '+Another::Place::RSets',
111 );
112 To search multiple namespaces for either Result or ResultSet classes,
114 use an arrayref of namespaces for that option. In the case that the
115 same result (or resultset) class exists in multiple namespaces, later
116 entries in the list of namespaces will override earlier ones.
117 My::Schema->load_namespaces(
119 # My::Schema::Results_C::Foo takes precedence over My::Schema::Results_B::Foo :
120 result_namespace => [ 'Results_A', 'Results_B', 'Results_C' ],
121 resultset_namespace => [ '+Some::Place::RSets', 'RSets' ],
122 );
123 load_classes
125 Arguments: @classes?, { $namespace => [ @classes ] }+
126 "load_classes" is an alternative method to "load_namespaces", both of
128 which serve similar purposes, each with different advantages and
129 disadvantages. In the general case you should use "load_namespaces",
130 unless you need to be able to specify that only specific classes are
131 loaded at runtime.
132 With no arguments, this method uses Module::Find to find all classes
134 under the schema's namespace. Otherwise, this method loads the classes
135 you specify (using use), and registers them (using "register_class").
136 It is possible to comment out classes with a leading "#", but note that
138 perl will think it's a mistake (trying to use a comment in a qw list),
139 so you'll need to add "no warnings 'qw';" before your load_classes
140 call.
141 If any classes found do not appear to be Result class files, you will
143 get the following warning:
144 Failed to load $comp_class. Can't find source_name method. Is
146 $comp_class really a full DBIC result class? Fix it, move it elsewhere,
147 or make your load_classes call more specific.
148 Example:
150 My::Schema->load_classes(); # loads My::Schema::CD, My::Schema::Artist,
152 # etc. (anything under the My::Schema namespace)
153 # loads My::Schema::CD, My::Schema::Artist, Other::Namespace::Producer but
155 # not Other::Namespace::LinerNotes nor My::Schema::Track
156 My::Schema->load_classes(qw/ CD Artist #Track /, {
157 Other::Namespace => [qw/ Producer #LinerNotes /],
158 });
159 storage_type
161 Arguments: $storage_type|{$storage_type, \%args}
162 Return Value: $storage_type|{$storage_type, \%args}
163 Default value: DBIx::Class::Storage::DBI
164 Set the storage class that will be instantiated when "connect" is
166 called. If the classname starts with "::", the prefix
167 "DBIx::Class::Storage" is assumed by "connect".
168 You want to use this to set subclasses of DBIx::Class::Storage::DBI in
170 cases where the appropriate subclass is not autodetected.
171 If your storage type requires instantiation arguments, those are
173 defined as a second argument in the form of a hashref and the entire
174 value needs to be wrapped into an arrayref or a hashref. We support
175 both types of refs here in order to play nice with your Config::[class]
176 or your choice. See DBIx::Class::Storage::DBI::Replicated for an
177 example of this.
178 exception_action
180 Arguments: $code_reference
181 Return Value: $code_reference
182 Default value: None
183 When "throw_exception" is invoked and "exception_action" is set to a
185 code reference, this reference will be called instead of "throw" in
186 DBIx::Class::Exception, with the exception message passed as the only
187 argument.
188 Your custom throw code must rethrow the exception, as "throw_exception"
190 is an integral part of DBIC's internal execution control flow.
191 Example:
193 package My::Schema;
195 use base qw/DBIx::Class::Schema/;
196 use My::ExceptionClass;
197 __PACKAGE__->exception_action(sub { My::ExceptionClass->throw(@_) });
198 __PACKAGE__->load_classes;
199 # or:
201 my $schema_obj = My::Schema->connect( .... );
202 $schema_obj->exception_action(sub { My::ExceptionClass->throw(@_) });
203 stacktrace
205 Arguments: boolean
206 Whether "throw_exception" should include stack trace information.
208 Defaults to false normally, but defaults to true if $ENV{DBIC_TRACE} is
209 true.
210 sqlt_deploy_hook
212 Arguments: $sqlt_schema
213 An optional sub which you can declare in your own Schema class that
215 will get passed the SQL::Translator::Schema object when you deploy the
216 schema via "create_ddl_dir" or "deploy".
217 For an example of what you can do with this, see "Adding Indexes And
219 Functions To Your SQL" in DBIx::Class::Manual::Cookbook.
220 Note that sqlt_deploy_hook is called by "deployment_statements", which
222 in turn is called before "deploy". Therefore the hook can be used only
223 to manipulate the SQL::Translator::Schema object before it is turned
224 into SQL fed to the database. If you want to execute post-deploy
225 statements which can not be generated by SQL::Translator, the currently
226 suggested method is to overload "deploy" and use dbh_do.
227
229 connect
230 Arguments: @connectinfo
231 Return Value: $new_schema
232 Creates and returns a new Schema object. The connection info set on it
234 is used to create a new instance of the storage backend and set it on
235 the Schema object.
236 See "connect_info" in DBIx::Class::Storage::DBI for DBI-specific syntax
238 on the @connectinfo argument, or DBIx::Class::Storage in general.
239 Note that "connect_info" expects an arrayref of arguments, but
241 "connect" does not. "connect" wraps its arguments in an arrayref before
242 passing them to "connect_info".
243 Overloading
245 "connect" is a convenience method. It is equivalent to calling
247 $schema->clone->connection(@connectinfo). To write your own overloaded
248 version, overload "connection" instead.
249 resultset
251 Arguments: $source_name
252 Return Value: $resultset
253 my $rs = $schema->resultset('DVD');
255 Returns the DBIx::Class::ResultSet object for the registered source
257 name.
258 sources
260 Return Value: @source_names
261 my @source_names = $schema->sources;
263 Lists names of all the sources registered on this Schema object.
265 source
267 Arguments: $source_name
268 Return Value: $result_source
269 my $source = $schema->source('Book');
271 Returns the DBIx::Class::ResultSource object for the registered source
273 name.
274 class
276 Arguments: $source_name
277 Return Value: $classname
278 my $class = $schema->class('CD');
280 Retrieves the Result class name for the given source name.
282 txn_do
284 Arguments: $coderef, @coderef_args?
285 Return Value: The return value of $coderef
286 Executes $coderef with (optional) arguments @coderef_args atomically,
288 returning its result (if any). Equivalent to calling
289 $schema->storage->txn_do. See "txn_do" in DBIx::Class::Storage for
290 more information.
291 This interface is preferred over using the individual methods
293 "txn_begin", "txn_commit", and "txn_rollback" below.
294 WARNING: If you are connected with "AutoCommit => 0" the transaction is
296 considered nested, and you will still need to call "txn_commit" to
297 write your changes when appropriate. You will also want to connect with
298 "auto_savepoint => 1" to get partial rollback to work, if the storage
299 driver for your database supports it.
300 Connecting with "AutoCommit => 1" is recommended.
302 txn_scope_guard
304 Runs "txn_scope_guard" on the schema's storage. See "txn_scope_guard"
305 in DBIx::Class::Storage.
306 txn_begin
308 Begins a transaction (does nothing if AutoCommit is off). Equivalent to
309 calling $schema->storage->txn_begin. See "txn_begin" in
310 DBIx::Class::Storage for more information.
311 txn_commit
313 Commits the current transaction. Equivalent to calling
314 $schema->storage->txn_commit. See "txn_commit" in DBIx::Class::Storage
315 for more information.
316 txn_rollback
318 Rolls back the current transaction. Equivalent to calling
319 $schema->storage->txn_rollback. See "txn_rollback" in
320 DBIx::Class::Storage for more information.
321 storage
323 my $storage = $schema->storage;
324 Returns the DBIx::Class::Storage object for this Schema. Grab this if
326 you want to turn on SQL statement debugging at runtime, or set the
327 quote character. For the default storage, the documentation can be
328 found in DBIx::Class::Storage::DBI.
329 populate
331 Arguments: $source_name, [ \@column_list, \@row_values+ ] | [
332 \%col_data+ ]
333 Return Value: \@result_objects (scalar context) | @result_objects (list
334 context)
335 A convenience shortcut to "populate" in DBIx::Class::ResultSet.
337 Equivalent to:
338 $schema->resultset($source_name)->populate([...]);
340 NOTE
342 The context of this method call has an important effect on what is
343 submitted to storage. In void context data is fed directly to
344 fastpath insertion routines provided by the underlying storage
345 (most often "execute_for_fetch" in DBI), bypassing the new and
346 insert calls on the Result class, including any augmentation of
347 these methods provided by components. For example if you are using
348 something like DBIx::Class::UUIDColumns to create primary keys for
349 you, you will find that your PKs are empty. In this case you will
350 have to explicitly force scalar or list context in order to create
351 those values.
352 connection
354 Arguments: @args
355 Return Value: $new_schema
356 Similar to "connect" except sets the storage object and connection data
358 in-place on the Schema class. You should probably be calling "connect"
359 to get a proper Schema object instead.
360 Overloading
362 Overload "connection" to change the behaviour of "connect".
364 compose_namespace
366 Arguments: $target_namespace, $additional_base_class?
367 Return Value: $new_schema
368 For each DBIx::Class::ResultSource in the schema, this method creates a
370 class in the target namespace (e.g. $target_namespace::CD,
371 $target_namespace::Artist) that inherits from the corresponding classes
372 attached to the current schema.
373 It also attaches a corresponding DBIx::Class::ResultSource object to
375 the new $schema object. If $additional_base_class is given, the new
376 composed classes will inherit from first the corresponding class from
377 the current schema then the base class.
378 For example, for a schema with My::Schema::CD and My::Schema::Artist
380 classes,
381 $schema->compose_namespace('My::DB', 'Base::Class');
383 print join (', ', @My::DB::CD::ISA) . "\n";
384 print join (', ', @My::DB::Artist::ISA) ."\n";
385 will produce the output
387 My::Schema::CD, Base::Class
389 My::Schema::Artist, Base::Class
390 svp_begin
392 Creates a new savepoint (does nothing outside a transaction).
393 Equivalent to calling $schema->storage->svp_begin. See "svp_begin" in
394 DBIx::Class::Storage for more information.
395 svp_release
397 Releases a savepoint (does nothing outside a transaction). Equivalent
398 to calling $schema->storage->svp_release. See "svp_release" in
399 DBIx::Class::Storage for more information.
400 svp_rollback
402 Rollback to a savepoint (does nothing outside a transaction).
403 Equivalent to calling $schema->storage->svp_rollback. See
404 "svp_rollback" in DBIx::Class::Storage for more information.
405 clone
407 Arguments: %attrs?
408 Return Value: $new_schema
409 Clones the schema and its associated result_source objects and returns
411 the copy. The resulting copy will have the same attributes as the
412 source schema, except for those attributes explicitly overridden by the
413 provided %attrs.
414 throw_exception
416 Arguments: $message
417 Throws an exception. Obeys the exemption rules of DBIx::Class::Carp to
419 report errors from outer-user's perspective. See "exception_action" for
420 details on overriding this method's behavior. If "stacktrace" is
421 turned on, "throw_exception"'s default behavior will provide a detailed
422 stack trace.
423 deploy
425 Arguments: \%sqlt_args, $dir
426 Attempts to deploy the schema to the current storage using
428 SQL::Translator.
429 See "METHODS" in SQL::Translator for a list of values for
431 "\%sqlt_args". The most common value for this would be "{
432 add_drop_table => 1 }" to have the SQL produced include a "DROP TABLE"
433 statement for each table created. For quoting purposes supply
434 "quote_identifiers".
435 Additionally, the DBIx::Class parser accepts a "sources" parameter as a
437 hash ref or an array ref, containing a list of source to deploy. If
438 present, then only the sources listed will get deployed. Furthermore,
439 you can use the "add_fk_index" parser parameter to prevent the parser
440 from creating an index for each FK.
441 deployment_statements
443 Arguments: See "deployment_statements" in DBIx::Class::Storage::DBI
444 Return Value: $listofstatements
445 A convenient shortcut to "$self->storage->deployment_statements($self,
447 @args)". Returns the statements used by "deploy" and "deploy" in
448 DBIx::Class::Storage.
449 create_ddl_dir
451 Arguments: See "create_ddl_dir" in DBIx::Class::Storage::DBI
452 A convenient shortcut to "$self->storage->create_ddl_dir($self,
454 @args)".
455 Creates an SQL file based on the Schema, for each of the specified
457 database types, in the given directory.
458 ddl_filename
460 Arguments: $database-type, $version, $directory, $preversion
461 Return Value: $normalised_filename
462 my $filename = $table->ddl_filename($type, $version, $dir, $preversion)
464 This method is called by "create_ddl_dir" to compose a file name out of
466 the supplied directory, database type and version number. The default
467 file name format is: "$dir$schema-$version-$type.sql".
468 You may override this method in your schema if you wish to use a
470 different format.
471 WARNING
473 Prior to DBIx::Class version 0.08100 this method had a different signature:
475 my $filename = $table->ddl_filename($type, $dir, $version, $preversion)
477 In recent versions variables $dir and $version were reversed in order to
479 bring the signature in line with other Schema/Storage methods. If you
480 really need to maintain backward compatibility, you can do the following
481 in any overriding methods:
482 ($dir, $version) = ($version, $dir) if ($DBIx::Class::VERSION < 0.08100);
484 thaw
486 Provided as the recommended way of thawing schema objects. You can call
487 "Storable::thaw" directly if you wish, but the thawed objects will not
488 have a reference to any schema, so are rather useless.
489 freeze
491 This doesn't actually do anything beyond calling nfreeze, it is just
492 provided here for symmetry.
493 dclone
495 Arguments: $object
496 Return Value: dcloned $object
497 Recommended way of dcloning DBIx::Class::Row and DBIx::Class::ResultSet
499 objects so their references to the schema object (which itself is not
500 cloned) are properly maintained.
501 schema_version
503 Returns the current schema class' $VERSION in a normalised way.
504 register_class
506 Arguments: $source_name, $component_class
507 This method is called by "load_namespaces" and "load_classes" to
509 install the found classes into your Schema. You should be using those
510 instead of this one.
511 You will only need this method if you have your Result classes in files
513 which are not named after the packages (or all in the same file). You
514 may also need it to register classes at runtime.
515 Registers a class which isa DBIx::Class::ResultSourceProxy. Equivalent
517 to calling:
518 $schema->register_source($source_name, $component_class->result_source_instance);
520 register_source
522 Arguments: $source_name, $result_source
523 This method is called by "register_class".
525 Registers the DBIx::Class::ResultSource in the schema with the given
527 source name.
528 unregister_source
530 Arguments: $source_name
531 Removes the DBIx::Class::ResultSource from the schema for the given
533 source name.
534 register_extra_source
536 Arguments: $source_name, $result_source
537 As "register_source" but should be used if the result class already has
539 a source and you want to register an extra one.
540 compose_connection (DEPRECATED)
542 Arguments: $target_namespace, @db_info
543 Return Value: $new_schema
544 DEPRECATED. You probably wanted compose_namespace.
546 Actually, you probably just wanted to call connect.
548
550 Check the list of additional DBIC resources.
551
553 This module is free software copyright by the DBIx::Class (DBIC)
554 authors. You can redistribute it and/or modify it under the same terms
555 as the DBIx::Class library.
556perl v5.30.1 2020-01-29 DBIx::Class::Schema(3)