1 package DBIx::Class::Schema;
6 use base 'DBIx::Class';
10 use Scalar::Util qw( weaken blessed refaddr );
11 use DBIx::Class::_Util qw(
12 false emit_loud_diag refdesc
13 refcount quote_sub scope_guard
14 is_exception dbic_internal_try
15 fail_on_internal_call emit_loud_diag
17 use Devel::GlobalDestruction;
20 __PACKAGE__->mk_group_accessors( inherited => qw( storage exception_action ) );
21 __PACKAGE__->mk_classaccessor('storage_type' => '::DBI');
22 __PACKAGE__->mk_classaccessor('stacktrace' => $ENV{DBIC_TRACE} || 0);
23 __PACKAGE__->mk_classaccessor('default_resultset_attributes' => {});
25 # These two should have been private from the start but too late now
26 # Undocumented on purpose, hopefully it won't ever be necessary to
28 __PACKAGE__->mk_classaccessor('class_mappings' => {});
29 __PACKAGE__->mk_classaccessor('source_registrations' => {});
31 __PACKAGE__->mk_group_accessors( component_class => 'schema_sanity_checker' );
32 __PACKAGE__->schema_sanity_checker(
33 DBIx::Class::_ENV_::OLD_MRO ? false :
34 'DBIx::Class::Schema::SanityChecker'
39 DBIx::Class::Schema - composable schemas
43 package Library::Schema;
44 use base qw/DBIx::Class::Schema/;
46 # load all Result classes in Library/Schema/Result/
47 __PACKAGE__->load_namespaces();
49 package Library::Schema::Result::CD;
50 use base qw/DBIx::Class::Core/;
52 __PACKAGE__->load_components(qw/InflateColumn::DateTime/); # for example
53 __PACKAGE__->table('cd');
55 # Elsewhere in your code:
56 my $schema1 = Library::Schema->connect(
63 my $schema2 = Library::Schema->connect($coderef_returning_dbh);
65 # fetch objects using Library::Schema::Result::DVD
66 my $resultset = $schema1->resultset('DVD')->search( ... );
67 my @dvd_objects = $schema2->resultset('DVD')->search( ... );
71 Creates database classes based on a schema. This is the recommended way to
72 use L<DBIx::Class> and allows you to use more than one concurrent connection
75 NB: If you're used to L<Class::DBI> it's worth reading the L</SYNOPSIS>
76 carefully, as DBIx::Class does things a little differently. Note in
77 particular which module inherits off which.
81 =head2 load_namespaces
85 =item Arguments: %options?
89 package MyApp::Schema;
90 __PACKAGE__->load_namespaces();
92 __PACKAGE__->load_namespaces(
93 result_namespace => 'Res',
94 resultset_namespace => 'RSet',
95 default_resultset_class => '+MyApp::Othernamespace::RSet',
98 With no arguments, this method uses L<Module::Find> to load all of the
99 Result and ResultSet classes under the namespace of the schema from
100 which it is called. For example, C<My::Schema> will by default find
101 and load Result classes named C<My::Schema::Result::*> and ResultSet
102 classes named C<My::Schema::ResultSet::*>.
104 ResultSet classes are associated with Result class of the same name.
105 For example, C<My::Schema::Result::CD> will get the ResultSet class
106 C<My::Schema::ResultSet::CD> if it is present.
108 Both Result and ResultSet namespaces are configurable via the
109 C<result_namespace> and C<resultset_namespace> options.
111 Another option, C<default_resultset_class> specifies a custom default
112 ResultSet class for Result classes with no corresponding ResultSet.
114 All of the namespace and classname options are by default relative to
115 the schema classname. To specify a fully-qualified name, prefix it
116 with a literal C<+>. For example, C<+Other::NameSpace::Result>.
120 You will be warned if ResultSet classes are discovered for which there
121 are no matching Result classes like this:
123 load_namespaces found ResultSet class $classname with no corresponding Result class
125 If a ResultSource instance is found to already have a ResultSet class set
126 using L<resultset_class|DBIx::Class::ResultSource/resultset_class> to some
127 other class, you will be warned like this:
129 We found ResultSet class '$rs_class' for '$result_class', but it seems
130 that you had already set '$result_class' to use '$rs_set' instead
134 # load My::Schema::Result::CD, My::Schema::Result::Artist,
135 # My::Schema::ResultSet::CD, etc...
136 My::Schema->load_namespaces;
138 # Override everything to use ugly names.
139 # In this example, if there is a My::Schema::Res::Foo, but no matching
140 # My::Schema::RSets::Foo, then Foo will have its
141 # resultset_class set to My::Schema::RSetBase
142 My::Schema->load_namespaces(
143 result_namespace => 'Res',
144 resultset_namespace => 'RSets',
145 default_resultset_class => 'RSetBase',
148 # Put things in other namespaces
149 My::Schema->load_namespaces(
150 result_namespace => '+Some::Place::Results',
151 resultset_namespace => '+Another::Place::RSets',
154 To search multiple namespaces for either Result or ResultSet classes,
155 use an arrayref of namespaces for that option. In the case that the
156 same result (or resultset) class exists in multiple namespaces, later
157 entries in the list of namespaces will override earlier ones.
159 My::Schema->load_namespaces(
160 # My::Schema::Results_C::Foo takes precedence over My::Schema::Results_B::Foo :
161 result_namespace => [ 'Results_A', 'Results_B', 'Results_C' ],
162 resultset_namespace => [ '+Some::Place::RSets', 'RSets' ],
167 # Pre-pends our classname to the given relative classname or
168 # class namespace, unless there is a '+' prefix, which will
170 sub _expand_relative_name {
171 my ($class, $name) = @_;
172 $name =~ s/^\+// or $name = "${class}::${name}";
176 # Finds all modules in the supplied namespace, or if omitted in the
177 # namespace of $class. Untaints all findings as they can be assumed
180 require Module::Find;
182 { $_ =~ /(.+)/ } # untaint result
183 Module::Find::findallmod( $_[1] || ref $_[0] || $_[0] )
187 # returns a hash of $shortname => $fullname for every package
188 # found in the given namespaces ($shortname is with the $fullname's
189 # namespace stripped off)
190 sub _map_namespaces {
191 my ($me, $namespaces) = @_;
194 for my $ns (@$namespaces) {
195 $res{ substr($_, length "${ns}::") } = $_
196 for $me->_findallmod($ns);
202 # returns the result_source_instance for the passed class/object,
203 # or dies with an informative message (used by load_namespaces)
204 sub _ns_get_rsrc_instance {
206 my $rs_class = ref ($_[0]) || $_[0];
208 return dbic_internal_try {
209 $rs_class->result_source
211 $me->throw_exception (
212 "Attempt to load_namespaces() class $rs_class failed - are you sure this is a real Result Class?: $_"
217 sub load_namespaces {
218 my ($class, %args) = @_;
220 my $result_namespace = delete $args{result_namespace} || 'Result';
221 my $resultset_namespace = delete $args{resultset_namespace} || 'ResultSet';
223 my $default_resultset_class = delete $args{default_resultset_class};
225 $default_resultset_class = $class->_expand_relative_name($default_resultset_class)
226 if $default_resultset_class;
228 $class->throw_exception('load_namespaces: unknown option(s): '
229 . join(q{,}, map { qq{'$_'} } keys %args))
230 if scalar keys %args;
232 for my $arg ($result_namespace, $resultset_namespace) {
233 $arg = [ $arg ] if ( $arg and ! ref $arg );
235 $class->throw_exception('load_namespaces: namespace arguments must be '
236 . 'a simple string or an arrayref')
237 if ref($arg) ne 'ARRAY';
239 $_ = $class->_expand_relative_name($_) for (@$arg);
242 my $results_by_source_name = $class->_map_namespaces($result_namespace);
243 my $resultsets_by_source_name = $class->_map_namespaces($resultset_namespace);
247 no warnings qw/redefine/;
248 local *Class::C3::reinitialize = sub { } if DBIx::Class::_ENV_::OLD_MRO;
249 use warnings qw/redefine/;
251 # ensure classes are loaded and attached in inheritance order
252 for my $result_class (values %$results_by_source_name) {
253 $class->ensure_class_loaded($result_class);
256 my @source_names_by_subclass_last = sort {
259 scalar @{mro::get_linear_isa( $results_by_source_name->{$a} )}
265 scalar @{mro::get_linear_isa( $results_by_source_name->{$b} )}
268 } keys(%$results_by_source_name);
270 foreach my $source_name (@source_names_by_subclass_last) {
271 my $result_class = $results_by_source_name->{$source_name};
273 my $preset_resultset_class = $class->_ns_get_rsrc_instance ($result_class)->resultset_class;
274 my $found_resultset_class = delete $resultsets_by_source_name->{$source_name};
276 if($preset_resultset_class && $preset_resultset_class ne 'DBIx::Class::ResultSet') {
277 if($found_resultset_class && $found_resultset_class ne $preset_resultset_class) {
278 carp "We found ResultSet class '$found_resultset_class' matching '$results_by_source_name->{$source_name}', but it seems "
279 . "that you had already set the '$results_by_source_name->{$source_name}' resultet to '$preset_resultset_class' instead";
282 # elsif - there may be *no* default_resultset_class, in which case we fallback to
283 # DBIx::Class::Resultset and there is nothing to check
284 elsif($found_resultset_class ||= $default_resultset_class) {
285 $class->ensure_class_loaded($found_resultset_class);
286 if(!$found_resultset_class->isa("DBIx::Class::ResultSet")) {
287 carp "load_namespaces found ResultSet class '$found_resultset_class' that does not subclass DBIx::Class::ResultSet";
290 $class->_ns_get_rsrc_instance ($result_class)->resultset_class($found_resultset_class);
293 my $source_name = $class->_ns_get_rsrc_instance ($result_class)->source_name || $source_name;
295 push(@to_register, [ $source_name, $result_class ]);
299 foreach (sort keys %$resultsets_by_source_name) {
300 carp "load_namespaces found ResultSet class '$resultsets_by_source_name->{$_}' "
301 .'with no corresponding Result class';
304 Class::C3->reinitialize if DBIx::Class::_ENV_::OLD_MRO;
306 $class->register_class(@$_) for (@to_register);
315 =item Arguments: @classes?, { $namespace => [ @classes ] }+
319 L</load_classes> is an alternative method to L</load_namespaces>, both of
320 which serve similar purposes, each with different advantages and disadvantages.
321 In the general case you should use L</load_namespaces>, unless you need to
322 be able to specify that only specific classes are loaded at runtime.
324 With no arguments, this method uses L<Module::Find> to find all classes under
325 the schema's namespace. Otherwise, this method loads the classes you specify
326 (using L<use>), and registers them (using L</"register_class">).
328 It is possible to comment out classes with a leading C<#>, but note that perl
329 will think it's a mistake (trying to use a comment in a qw list), so you'll
330 need to add C<no warnings 'qw';> before your load_classes call.
332 If any classes found do not appear to be Result class files, you will
333 get the following warning:
335 Failed to load $comp_class. Can't find source_name method. Is
336 $comp_class really a full DBIC result class? Fix it, move it elsewhere,
337 or make your load_classes call more specific.
341 My::Schema->load_classes(); # loads My::Schema::CD, My::Schema::Artist,
342 # etc. (anything under the My::Schema namespace)
344 # loads My::Schema::CD, My::Schema::Artist, Other::Namespace::Producer but
345 # not Other::Namespace::LinerNotes nor My::Schema::Track
346 My::Schema->load_classes(qw/ CD Artist #Track /, {
347 Other::Namespace => [qw/ Producer #LinerNotes /],
353 my ($class, @params) = @_;
358 foreach my $param (@params) {
359 if (ref $param eq 'ARRAY') {
360 # filter out commented entries
361 my @modules = grep { $_ !~ /^#/ } @$param;
363 push (@{$comps_for{$class}}, @modules);
365 elsif (ref $param eq 'HASH') {
366 # more than one namespace possible
367 for my $comp ( keys %$param ) {
368 # filter out commented entries
369 my @modules = grep { $_ !~ /^#/ } @{$param->{$comp}};
371 push (@{$comps_for{$comp}}, @modules);
375 # filter out commented entries
376 push (@{$comps_for{$class}}, $param) if $param !~ /^#/;
380 my @comp = map { substr $_, length "${class}::" }
381 $class->_findallmod($class);
382 $comps_for{$class} = \@comp;
387 no warnings qw/redefine/;
388 local *Class::C3::reinitialize = sub { } if DBIx::Class::_ENV_::OLD_MRO;
389 use warnings qw/redefine/;
391 foreach my $prefix (keys %comps_for) {
392 foreach my $comp (@{$comps_for{$prefix}||[]}) {
393 my $comp_class = "${prefix}::${comp}";
394 $class->ensure_class_loaded($comp_class);
396 my $snsub = $comp_class->can('source_name');
398 carp "Failed to load $comp_class. Can't find source_name method. Is $comp_class really a full DBIC result class? Fix it, move it elsewhere, or make your load_classes call more specific.";
401 $comp = $snsub->($comp_class) || $comp;
403 push(@to_register, [ $comp, $comp_class ]);
407 Class::C3->reinitialize if DBIx::Class::_ENV_::OLD_MRO;
409 foreach my $to (@to_register) {
410 $class->register_class(@$to);
418 =item Arguments: $storage_type|{$storage_type, \%args}
420 =item Return Value: $storage_type|{$storage_type, \%args}
422 =item Default value: DBIx::Class::Storage::DBI
426 Set the storage class that will be instantiated when L</connect> is called.
427 If the classname starts with C<::>, the prefix C<DBIx::Class::Storage> is
428 assumed by L</connect>.
430 You want to use this to set subclasses of L<DBIx::Class::Storage::DBI>
431 in cases where the appropriate subclass is not autodetected.
433 If your storage type requires instantiation arguments, those are
434 defined as a second argument in the form of a hashref and the entire
435 value needs to be wrapped into an arrayref or a hashref. We support
436 both types of refs here in order to play nice with your
437 Config::[class] or your choice. See
438 L<DBIx::Class::Storage::DBI::Replicated> for an example of this.
440 =head2 default_resultset_attributes
444 =item Arguments: L<\%attrs|DBIx::Class::ResultSet/ATTRIBUTES>
446 =item Return Value: L<\%attrs|DBIx::Class::ResultSet/ATTRIBUTES>
448 =item Default value: None
452 Like L<DBIx::Class::ResultSource/resultset_attributes> stores a collection
453 of resultset attributes, to be used as defaults for B<every> ResultSet
454 instance schema-wide. The same list of CAVEATS and WARNINGS applies, with
455 the extra downside of these defaults being practically inescapable: you will
456 B<not> be able to derive a ResultSet instance with these attributes unset.
461 use base qw/DBIx::Class::Schema/;
462 __PACKAGE__->default_resultset_attributes( { software_limit => 1 } );
464 =head2 schema_sanity_checker
468 =item Arguments: L<perform_schema_sanity_checks()|DBIx::Class::Schema::SanityChecker/perform_schema_sanity_checks> provider
470 =item Return Value: L<perform_schema_sanity_checks()|DBIx::Class::Schema::SanityChecker/perform_schema_sanity_checks> provider
472 =item Default value: L<DBIx::Class::Schema::SanityChecker>
476 On every call to L</connection> if the value of this attribute evaluates to
477 true, DBIC will invoke
478 C<< L<$schema_sanity_checker|/schema_sanity_checker>->L<perform_schema_sanity_checks|DBIx::Class::Schema::SanityChecker/perform_schema_sanity_checks>($schema) >>
479 before returning. The return value of this invocation is ignored.
481 B<YOU ARE STRONGLY URGED> to
482 L<learn more about the reason|DBIx::Class::Schema::SanityChecker/WHY> this
483 feature was introduced. Blindly disabling the checker on existing projects
484 B<may result in data corruption> after upgrade to C<< DBIC >= v0.082900 >>.
489 use base qw/DBIx::Class::Schema/;
490 __PACKAGE__->schema_sanity_checker('My::Schema::SanityChecker');
492 # or to disable all checks:
493 __PACKAGE__->schema_sanity_checker('');
495 Note: setting the value to C<undef> B<will not> have the desired effect,
496 due to an implementation detail of L<Class::Accessor::Grouped> inherited
497 accessors. In order to disable any and all checks you must set this
498 attribute to an empty string as shown in the second example above.
500 =head2 exception_action
504 =item Arguments: $code_reference
506 =item Return Value: $code_reference
508 =item Default value: None
512 When L</throw_exception> is invoked and L</exception_action> is set to a code
513 reference, this reference will be called instead of
514 L<DBIx::Class::Exception/throw>, with the exception message passed as the only
517 Your custom throw code B<must> rethrow the exception, as L</throw_exception> is
518 an integral part of DBIC's internal execution control flow.
523 use base qw/DBIx::Class::Schema/;
524 use My::ExceptionClass;
525 __PACKAGE__->exception_action(sub { My::ExceptionClass->throw(@_) });
526 __PACKAGE__->load_classes;
529 my $schema_obj = My::Schema->connect( .... );
530 $schema_obj->exception_action(sub { My::ExceptionClass->throw(@_) });
536 =item Arguments: boolean
540 Whether L</throw_exception> should include stack trace information.
541 Defaults to false normally, but defaults to true if C<$ENV{DBIC_TRACE}>
544 =head2 sqlt_deploy_hook
548 =item Arguments: $sqlt_schema
552 An optional sub which you can declare in your own Schema class that will get
553 passed the L<SQL::Translator::Schema> object when you deploy the schema via
554 L</create_ddl_dir> or L</deploy>.
556 For an example of what you can do with this, see
557 L<DBIx::Class::Manual::Cookbook/Adding Indexes And Functions To Your SQL>.
559 Note that sqlt_deploy_hook is called by L</deployment_statements>, which in turn
560 is called before L</deploy>. Therefore the hook can be used only to manipulate
561 the L<SQL::Translator::Schema> object before it is turned into SQL fed to the
562 database. If you want to execute post-deploy statements which can not be generated
563 by L<SQL::Translator>, the currently suggested method is to overload L</deploy>
564 and use L<dbh_do|DBIx::Class::Storage::DBI/dbh_do>.
572 =item Arguments: @connectinfo
574 =item Return Value: $new_schema
578 Creates and returns a new Schema object. The connection info set on it
579 is used to create a new instance of the storage backend and set it on
582 See L<DBIx::Class::Storage::DBI/"connect_info"> for DBI-specific
583 syntax on the C<@connectinfo> argument, or L<DBIx::Class::Storage> in
586 Note that C<connect_info> expects an arrayref of arguments, but
587 C<connect> does not. C<connect> wraps its arguments in an arrayref
588 before passing them to C<connect_info>.
592 C<connect> is a convenience method. It is equivalent to calling
593 $schema->clone->connection(@connectinfo). To write your own overloaded
594 version, overload L</connection> instead.
598 sub connect :DBIC_method_is_indirect_sugar {
599 DBIx::Class::_ENV_::ASSERT_NO_INTERNAL_INDIRECT_CALLS and fail_on_internal_call;
600 shift->clone->connection(@_);
607 =item Arguments: L<$source_name|DBIx::Class::ResultSource/source_name>
609 =item Return Value: L<$resultset|DBIx::Class::ResultSet>
613 my $rs = $schema->resultset('DVD');
615 Returns the L<DBIx::Class::ResultSet> object for the registered source
621 my ($self, $source_name) = @_;
622 $self->throw_exception('resultset() expects a source name')
623 unless defined $source_name;
624 return $self->source($source_name)->resultset;
631 =item Return Value: L<@source_names|DBIx::Class::ResultSource/source_name>
635 my @source_names = $schema->sources;
637 Lists names of all the sources registered on this Schema object.
641 sub sources { keys %{shift->source_registrations} }
647 =item Arguments: L<$source_name|DBIx::Class::ResultSource/source_name>
649 =item Return Value: L<$result_source|DBIx::Class::ResultSource>
653 my $source = $schema->source('Book');
655 Returns the L<DBIx::Class::ResultSource> object for the registered
661 my ($self, $source_name) = @_;
663 $self->throw_exception("source() expects a source name")
666 my $source_registrations;
669 ( $source_registrations = $self->source_registrations )->{$source_name}
671 # if we got here, they probably passed a full class name
672 $source_registrations->{ $self->class_mappings->{$source_name} || '' }
674 $self->throw_exception( "Can't find source for ${source_name}" )
678 # We need to prevent alterations of pre-existing $@ due to where this call
679 # sits in the overall stack ( *unless* of course there is an actual error
680 # to report ). set_mro does alter $@ (and yes - it *can* throw an exception)
681 # We do not use local because set_mro *can* throw an actual exception
682 # We do not use a try/catch either, as on one hand it would slow things
683 # down for no reason (we would always rethrow), but also because adding *any*
684 # try/catch block below will segfault various threading tests on older perls
685 # ( which in itself is a FIXME but ENOTIMETODIG )
686 my $old_dollarat = $@;
689 mro::set_mro($_, 'c3') for
692 # some pseudo-sources do not have a result/resultset yet
697 ${"${_}::__INITIAL_MRO_UPON_DBIC_LOAD__"}
705 { length ref $_ ? ref $_ : $_ }
706 ( $rsrc, $rsrc->result_class, $rsrc->resultset_class )
709 # DO NOT REMOVE - see comment above
719 =item Arguments: L<$source_name|DBIx::Class::ResultSource/source_name>
721 =item Return Value: $classname
725 my $class = $schema->class('CD');
727 Retrieves the Result class name for the given source name.
732 return shift->source(shift)->result_class;
739 =item Arguments: C<$coderef>, @coderef_args?
741 =item Return Value: The return value of $coderef
745 Executes C<$coderef> with (optional) arguments C<@coderef_args> atomically,
746 returning its result (if any). Equivalent to calling $schema->storage->txn_do.
747 See L<DBIx::Class::Storage/"txn_do"> for more information.
749 This interface is preferred over using the individual methods L</txn_begin>,
750 L</txn_commit>, and L</txn_rollback> below.
752 WARNING: If you are connected with C<< AutoCommit => 0 >> the transaction is
753 considered nested, and you will still need to call L</txn_commit> to write your
754 changes when appropriate. You will also want to connect with C<< auto_savepoint =>
755 1 >> to get partial rollback to work, if the storage driver for your database
758 Connecting with C<< AutoCommit => 1 >> is recommended.
765 $self->storage or $self->throw_exception
766 ('txn_do called on $schema without storage');
768 $self->storage->txn_do(@_);
771 =head2 txn_scope_guard
773 Runs C<txn_scope_guard> on the schema's storage. See
774 L<DBIx::Class::Storage/txn_scope_guard>.
778 sub txn_scope_guard {
781 $self->storage or $self->throw_exception
782 ('txn_scope_guard called on $schema without storage');
784 $self->storage->txn_scope_guard(@_);
789 Begins a transaction (does nothing if AutoCommit is off). Equivalent to
790 calling $schema->storage->txn_begin. See
791 L<DBIx::Class::Storage/"txn_begin"> for more information.
798 $self->storage or $self->throw_exception
799 ('txn_begin called on $schema without storage');
801 $self->storage->txn_begin;
806 Commits the current transaction. Equivalent to calling
807 $schema->storage->txn_commit. See L<DBIx::Class::Storage/"txn_commit">
808 for more information.
815 $self->storage or $self->throw_exception
816 ('txn_commit called on $schema without storage');
818 $self->storage->txn_commit;
823 Rolls back the current transaction. Equivalent to calling
824 $schema->storage->txn_rollback. See
825 L<DBIx::Class::Storage/"txn_rollback"> for more information.
832 $self->storage or $self->throw_exception
833 ('txn_rollback called on $schema without storage');
835 $self->storage->txn_rollback;
840 my $storage = $schema->storage;
842 Returns the L<DBIx::Class::Storage> object for this Schema. Grab this
843 if you want to turn on SQL statement debugging at runtime, or set the
844 quote character. For the default storage, the documentation can be
845 found in L<DBIx::Class::Storage::DBI>.
851 =item Arguments: L<$source_name|DBIx::Class::ResultSource/source_name>, [ \@column_list, \@row_values+ ] | [ \%col_data+ ]
853 =item Return Value: L<\@result_objects|DBIx::Class::Manual::ResultClass> (scalar context) | L<@result_objects|DBIx::Class::Manual::ResultClass> (list context)
857 A convenience shortcut to L<DBIx::Class::ResultSet/populate>. Equivalent to:
859 $schema->resultset($source_name)->populate([...]);
865 The context of this method call has an important effect on what is
866 submitted to storage. In void context data is fed directly to fastpath
867 insertion routines provided by the underlying storage (most often
868 L<DBI/execute_for_fetch>), bypassing the L<new|DBIx::Class::Row/new> and
869 L<insert|DBIx::Class::Row/insert> calls on the
870 L<Result|DBIx::Class::Manual::ResultClass> class, including any
871 augmentation of these methods provided by components. For example if you
872 are using something like L<DBIx::Class::UUIDColumns> to create primary
873 keys for you, you will find that your PKs are empty. In this case you
874 will have to explicitly force scalar or list context in order to create
881 sub populate :DBIC_method_is_indirect_sugar {
882 DBIx::Class::_ENV_::ASSERT_NO_INTERNAL_INDIRECT_CALLS and fail_on_internal_call;
884 my ($self, $name, $data) = @_;
885 my $rs = $self->resultset($name)
886 or $self->throw_exception("'$name' is not a resultset");
888 return $rs->populate($data);
895 =item Arguments: @args
897 =item Return Value: $self
901 Similar to L</connect> except sets the storage object and connection
902 data B<in-place> on C<$self>. You should probably be calling
903 L</connect> to get a properly L<cloned|/clone> Schema object instead.
905 If the accessor L</schema_sanity_checker> returns a true value C<$checker>,
906 the following call will take place before return:
907 C<< L<$checker|/schema_sanity_checker>->L<perform_schema_sanity_checks(C<$self>)|DBIx::Class::Schema::SanityChecker/perform_schema_sanity_checks> >>
911 Overload C<connection> to change the behaviour of C<connect>.
915 my $default_off_stderr_blurb_emitted;
917 my ($self, @info) = @_;
918 return $self if !@info && $self->storage;
920 my ($storage_class, $args) = ref $self->storage_type
921 ? $self->_normalize_storage_type($self->storage_type)
922 : $self->storage_type
925 $storage_class =~ s/^::/DBIx::Class::Storage::/;
928 $self->ensure_class_loaded ($storage_class);
931 $self->throw_exception(
932 "Unable to load storage class ${storage_class}: $_"
936 my $storage = $storage_class->new( $self => $args||{} );
937 $storage->connect_info(\@info);
938 $self->storage($storage);
942 ### Begin 5.8 "you have not selected a checker" warning
944 # We can not blanket-enable this on 5.8 - it is just too expensive for
945 # day to day execution. We also can't just go silent - there are genuine
946 # regressions ( due to core changes) for which this is the only line of
947 # defense. So instead we whine on STDERR that folks need to do something
949 # Beyond suboptimal, but given the constraints the best we can do :(
951 # This should stay around for at least 3~4 years
953 DBIx::Class::_ENV_::OLD_MRO
955 ! $default_off_stderr_blurb_emitted
957 length ref $self->schema_sanity_checker
959 length ref __PACKAGE__->schema_sanity_checker
962 refaddr( $self->schema_sanity_checker )
964 refaddr( __PACKAGE__->schema_sanity_checker )
969 "Sanity checks for schema %s are disabled on this perl $]: "
970 . '*THIS IS POTENTIALLY VERY DANGEROUS*. You are strongly urged to '
971 . "read http://is.gd/dbic_sancheck_5_008 before proceeding\n",
972 ( defined( blessed $self ) ? refdesc $self : "'$self'" )
975 $default_off_stderr_blurb_emitted = 1;
977 ### End 5.8 "you have not selected a checker" warning
981 if( my $checker = $self->schema_sanity_checker ) {
982 $checker->perform_schema_sanity_checks($self);
988 sub _normalize_storage_type {
989 my ($self, $storage_type) = @_;
990 if(ref $storage_type eq 'ARRAY') {
991 return @$storage_type;
992 } elsif(ref $storage_type eq 'HASH') {
993 return %$storage_type;
995 $self->throw_exception('Unsupported REFTYPE given: '. ref $storage_type);
999 =head2 compose_namespace
1003 =item Arguments: $target_namespace, $additional_base_class?
1005 =item Return Value: $new_schema
1009 For each L<DBIx::Class::ResultSource> in the schema, this method creates a
1010 class in the target namespace (e.g. $target_namespace::CD,
1011 $target_namespace::Artist) that inherits from the corresponding classes
1012 attached to the current schema.
1014 It also attaches a corresponding L<DBIx::Class::ResultSource> object to the
1015 new $schema object. If C<$additional_base_class> is given, the new composed
1016 classes will inherit from first the corresponding class from the current
1017 schema then the base class.
1019 For example, for a schema with My::Schema::CD and My::Schema::Artist classes,
1021 $schema->compose_namespace('My::DB', 'Base::Class');
1022 print join (', ', @My::DB::CD::ISA) . "\n";
1023 print join (', ', @My::DB::Artist::ISA) ."\n";
1025 will produce the output
1027 My::Schema::CD, Base::Class
1028 My::Schema::Artist, Base::Class
1032 sub compose_namespace {
1033 my ($self, $target, $base) = @_;
1035 my $schema = $self->clone;
1037 $schema->source_registrations({});
1039 # the original class-mappings must remain - otherwise
1040 # reverse_relationship_info will not work
1041 #$schema->class_mappings({});
1044 no warnings qw/redefine/;
1045 local *Class::C3::reinitialize = sub { } if DBIx::Class::_ENV_::OLD_MRO;
1046 use warnings qw/redefine/;
1048 foreach my $source_name ($self->sources) {
1049 my $orig_source = $self->source($source_name);
1051 my $target_class = "${target}::${source_name}";
1052 $self->inject_base($target_class, $orig_source->result_class, ($base || ()) );
1054 $schema->register_source(
1056 $orig_source->clone(
1057 result_class => $target_class
1062 # Legacy stuff, not inserting INDIRECT assertions
1063 quote_sub "${target}::${_}" => "shift->schema->$_(\@_)"
1064 for qw(class source resultset);
1067 Class::C3->reinitialize() if DBIx::Class::_ENV_::OLD_MRO;
1069 # Give each composed class yet another *schema-less* source copy
1070 # this is used for the freeze/thaw cycle
1072 # This is not covered by any tests directly, but is indirectly exercised
1073 # in t/cdbi/sweet/08pager by re-setting the schema on an existing object
1074 # FIXME - there is likely a much cheaper way to take care of this
1075 for my $source_name ($self->sources) {
1077 my $target_class = "${target}::${source_name}";
1079 $target_class->result_source_instance(
1080 $self->source($source_name)->clone(
1081 result_class => $target_class,
1082 schema => ( ref $schema || $schema ),
1090 # LEGACY: The intra-call to this was removed in 66d9ef6b and then
1091 # the sub was de-documented way later in 249963d4. No way to be sure
1092 # nothing on darkpan is calling it directly, so keeping as-is
1093 sub setup_connection_class {
1094 my ($class, $target, @info) = @_;
1095 $class->inject_base($target => 'DBIx::Class::DB');
1096 #$target->load_components('DB');
1097 $target->connection(@info);
1102 Creates a new savepoint (does nothing outside a transaction).
1103 Equivalent to calling $schema->storage->svp_begin. See
1104 L<DBIx::Class::Storage/"svp_begin"> for more information.
1109 my ($self, $name) = @_;
1111 $self->storage or $self->throw_exception
1112 ('svp_begin called on $schema without storage');
1114 $self->storage->svp_begin($name);
1119 Releases a savepoint (does nothing outside a transaction).
1120 Equivalent to calling $schema->storage->svp_release. See
1121 L<DBIx::Class::Storage/"svp_release"> for more information.
1126 my ($self, $name) = @_;
1128 $self->storage or $self->throw_exception
1129 ('svp_release called on $schema without storage');
1131 $self->storage->svp_release($name);
1136 Rollback to a savepoint (does nothing outside a transaction).
1137 Equivalent to calling $schema->storage->svp_rollback. See
1138 L<DBIx::Class::Storage/"svp_rollback"> for more information.
1143 my ($self, $name) = @_;
1145 $self->storage or $self->throw_exception
1146 ('svp_rollback called on $schema without storage');
1148 $self->storage->svp_rollback($name);
1155 =item Arguments: %attrs?
1157 =item Return Value: $new_schema
1161 Clones the schema and its associated result_source objects and returns the
1162 copy. The resulting copy will have the same attributes as the source schema,
1163 except for those attributes explicitly overridden by the provided C<%attrs>.
1171 (ref $self ? %$self : ()),
1172 (@_ == 1 && ref $_[0] eq 'HASH' ? %{ $_[0] } : @_),
1174 bless $clone, (ref $self || $self);
1176 $clone->$_(undef) for qw/class_mappings source_registrations storage/;
1178 $clone->_copy_state_from($self);
1183 # Needed in Schema::Loader - if you refactor, please make a compatibility shim
1185 sub _copy_state_from {
1186 my ($self, $from) = @_;
1188 $self->class_mappings({ %{$from->class_mappings} });
1189 $self->source_registrations({ %{$from->source_registrations} });
1191 # we use extra here as we want to leave the class_mappings as they are
1192 # but overwrite the source_registrations entry with the new source
1193 $self->register_extra_source( $_ => $from->source($_) )
1196 if ($from->storage) {
1197 $self->storage($from->storage);
1198 $self->storage->set_schema($self);
1202 =head2 throw_exception
1206 =item Arguments: $message
1210 Throws an exception. Obeys the exemption rules of L<DBIx::Class::Carp> to report
1211 errors from outer-user's perspective. See L</exception_action> for details on overriding
1212 this method's behavior. If L</stacktrace> is turned on, C<throw_exception>'s
1213 default behavior will provide a detailed stack trace.
1217 sub throw_exception {
1218 my ($self, @args) = @_;
1221 ! DBIx::Class::_Util::in_internal_try()
1223 my $act = $self->exception_action
1228 my $guard = scope_guard {
1229 return if $guard_disarmed;
1230 emit_loud_diag( emit_dups => 1, msg => "
1232 !!! DBIx::Class INTERNAL PANIC !!!
1234 The exception_action() handler installed on '$self'
1235 aborted the stacktrace below via a longjmp (either via Return::Multilevel or
1236 plain goto, or Scope::Upper or something equally nefarious). There currently
1237 is nothing safe DBIx::Class can do, aside from displaying this error. A future
1238 version ( 0.082900, when available ) will reduce the cases in which the
1239 handler is invoked, but this is neither a complete solution, nor can it do
1240 anything for other software that might be affected by a similar problem.
1242 !!! FIX YOUR ERROR HANDLING !!!
1244 This guard was activated starting",
1249 # if it throws - good, we'll assign to @args in the end
1250 # if it doesn't - do different things depending on RV truthiness
1251 if( $act->(@args) ) {
1253 "Invocation of the exception_action handler installed on $self did *not*"
1254 .' result in an exception. DBIx::Class is unable to function without a reliable'
1255 .' exception mechanism, ensure your exception_action does not hide exceptions'
1256 ." (original error: $args[0])"
1261 "The exception_action handler installed on $self returned false instead"
1262 .' of throwing an exception. This behavior has been deprecated, adjust your'
1263 .' handler to always rethrow the supplied error'
1270 # We call this to get the necessary warnings emitted and disregard the RV
1271 # as it's definitely an exception if we got as far as this catch{} block
1277 # Done guarding against https://github.com/PerlDancer/Dancer2/issues/1125
1278 $guard_disarmed = 1;
1281 DBIx::Class::Exception->throw( $args[0], $self->stacktrace );
1288 =item Arguments: \%sqlt_args, $dir
1292 Attempts to deploy the schema to the current storage using L<SQL::Translator>.
1294 See L<SQL::Translator/METHODS> for a list of values for C<\%sqlt_args>.
1295 The most common value for this would be C<< { add_drop_table => 1 } >>
1296 to have the SQL produced include a C<DROP TABLE> statement for each table
1297 created. For quoting purposes supply C<quote_identifiers>.
1299 Additionally, the DBIx::Class parser accepts a C<sources> parameter as a hash
1300 ref or an array ref, containing a list of source to deploy. If present, then
1301 only the sources listed will get deployed. Furthermore, you can use the
1302 C<add_fk_index> parser parameter to prevent the parser from creating an index for each
1308 my ($self, $sqltargs, $dir) = @_;
1309 $self->throw_exception("Can't deploy without storage") unless $self->storage;
1310 $self->storage->deploy($self, undef, $sqltargs, $dir);
1313 =head2 deployment_statements
1317 =item Arguments: See L<DBIx::Class::Storage::DBI/deployment_statements>
1319 =item Return Value: $listofstatements
1323 A convenient shortcut to
1324 C<< $self->storage->deployment_statements($self, @args) >>.
1325 Returns the statements used by L</deploy> and
1326 L<DBIx::Class::Storage/deploy>.
1330 sub deployment_statements {
1333 $self->throw_exception("Can't generate deployment statements without a storage")
1334 if not $self->storage;
1336 $self->storage->deployment_statements($self, @_);
1339 =head2 create_ddl_dir
1343 =item Arguments: See L<DBIx::Class::Storage::DBI/create_ddl_dir>
1347 A convenient shortcut to
1348 C<< $self->storage->create_ddl_dir($self, @args) >>.
1350 Creates an SQL file based on the Schema, for each of the specified
1351 database types, in the given directory.
1355 sub create_ddl_dir {
1358 $self->throw_exception("Can't create_ddl_dir without storage") unless $self->storage;
1359 $self->storage->create_ddl_dir($self, @_);
1366 =item Arguments: $database-type, $version, $directory, $preversion
1368 =item Return Value: $normalised_filename
1372 my $filename = $table->ddl_filename($type, $version, $dir, $preversion)
1374 This method is called by C<create_ddl_dir> to compose a file name out of
1375 the supplied directory, database type and version number. The default file
1376 name format is: C<$dir$schema-$version-$type.sql>.
1378 You may override this method in your schema if you wish to use a different
1383 Prior to DBIx::Class version 0.08100 this method had a different signature:
1385 my $filename = $table->ddl_filename($type, $dir, $version, $preversion)
1387 In recent versions variables $dir and $version were reversed in order to
1388 bring the signature in line with other Schema/Storage methods. If you
1389 really need to maintain backward compatibility, you can do the following
1390 in any overriding methods:
1392 ($dir, $version) = ($version, $dir) if ($DBIx::Class::VERSION < 0.08100);
1397 my ($self, $type, $version, $dir, $preversion) = @_;
1399 $version = "$preversion-$version" if $preversion;
1401 my $class = blessed($self) || $self;
1404 return "$dir/$class-$version-$type.sql";
1409 Provided as the recommended way of thawing schema objects. You can call
1410 C<Storable::thaw> directly if you wish, but the thawed objects will not have a
1411 reference to any schema, so are rather useless.
1416 my ($self, $obj) = @_;
1417 local $DBIx::Class::ResultSourceHandle::thaw_schema = $self;
1418 return Storable::thaw($obj);
1423 This doesn't actually do anything beyond calling L<nfreeze|Storable/SYNOPSIS>,
1424 it is just provided here for symmetry.
1429 return Storable::nfreeze($_[1]);
1436 =item Arguments: $object
1438 =item Return Value: dcloned $object
1442 Recommended way of dcloning L<DBIx::Class::Row> and L<DBIx::Class::ResultSet>
1443 objects so their references to the schema object
1444 (which itself is B<not> cloned) are properly maintained.
1449 my ($self, $obj) = @_;
1450 local $DBIx::Class::ResultSourceHandle::thaw_schema = $self;
1451 return Storable::dclone($obj);
1454 =head2 schema_version
1456 Returns the current schema class' $VERSION in a normalised way.
1460 sub schema_version {
1462 my $class = ref($self)||$self;
1464 # does -not- use $schema->VERSION
1465 # since that varies in results depending on if version.pm is installed, and if
1466 # so the perl or XS versions. If you want this to change, bug the version.pm
1467 # author to make vpp and vxs behave the same.
1472 $version = ${"${class}::VERSION"};
1478 =head2 register_class
1482 =item Arguments: $source_name, $component_class
1486 This method is called by L</load_namespaces> and L</load_classes> to install the found classes into your Schema. You should be using those instead of this one.
1488 You will only need this method if you have your Result classes in
1489 files which are not named after the packages (or all in the same
1490 file). You may also need it to register classes at runtime.
1492 Registers a class which isa DBIx::Class::ResultSourceProxy. Equivalent to
1495 $schema->register_source($source_name, $component_class->result_source);
1499 sub register_class {
1500 my ($self, $source_name, $to_register) = @_;
1501 $self->register_source($source_name => $to_register->result_source);
1504 =head2 register_source
1508 =item Arguments: $source_name, L<$result_source|DBIx::Class::ResultSource>
1512 This method is called by L</register_class>.
1514 Registers the L<DBIx::Class::ResultSource> in the schema with the given
1519 sub register_source { shift->_register_source(@_) }
1521 =head2 unregister_source
1525 =item Arguments: $source_name
1529 Removes the L<DBIx::Class::ResultSource> from the schema for the given source name.
1533 sub unregister_source { shift->_unregister_source(@_) }
1535 =head2 register_extra_source
1539 =item Arguments: $source_name, L<$result_source|DBIx::Class::ResultSource>
1543 As L</register_source> but should be used if the result class already
1544 has a source and you want to register an extra one.
1548 sub register_extra_source { shift->_register_source(@_, { extra => 1 }) }
1550 sub _register_source {
1551 my ($self, $source_name, $supplied_rsrc, $params) = @_;
1553 my $derived_rsrc = $supplied_rsrc->clone({
1554 source_name => $source_name,
1557 # Do not move into the clone-hashref above: there are things
1558 # on CPAN that do hook 'sub schema' </facepalm>
1559 # https://metacpan.org/source/LSAUNDERS/DBIx-Class-Preview-1.000003/lib/DBIx/Class/ResultSource/Table/Previewed.pm#L9-38
1560 $derived_rsrc->schema($self);
1562 weaken $derived_rsrc->{schema}
1563 if length( my $schema_class = ref($self) );
1565 my %reg = %{$self->source_registrations};
1566 $reg{$source_name} = $derived_rsrc;
1567 $self->source_registrations(\%reg);
1569 return $derived_rsrc if $params->{extra};
1571 my( $result_class, $result_class_level_rsrc );
1573 $result_class = $derived_rsrc->result_class
1575 # There are known cases where $rs_class is *ONLY* an inflator, without
1576 # any hint of a rsrc (e.g. DBIx::Class::KiokuDB::EntryProxy)
1577 $result_class_level_rsrc = dbic_internal_try { $result_class->result_source_instance }
1579 my %map = %{$self->class_mappings};
1582 "$result_class already had a registered source which was replaced by "
1583 . 'this call. Perhaps you wanted register_extra_source(), though it is '
1584 . 'more likely you did something wrong.'
1586 exists $map{$result_class}
1588 $map{$result_class} ne $source_name
1590 $result_class_level_rsrc != $supplied_rsrc
1593 $map{$result_class} = $source_name;
1594 $self->class_mappings(\%map);
1597 my $schema_class_level_rsrc;
1599 # we are called on a schema instance, not on the class
1600 length $schema_class
1604 # the schema class also has a registration with the same name
1605 $schema_class_level_rsrc = dbic_internal_try { $schema_class->source($source_name) }
1609 # what we are registering on the schema instance *IS* derived
1610 # from the class-level (top) rsrc...
1611 ( grep { $_ == $derived_rsrc } $result_class_level_rsrc->__derived_instances )
1615 # ... while the schema-class-level has stale-markers
1616 keys %{ $schema_class_level_rsrc->{__metadata_divergencies} || {} }
1619 "The ResultSource instance you just registered on '$self' as "
1620 . "'$source_name' seems to have no relation to $schema_class->"
1621 . "source('$source_name') which in turn is marked stale (likely due "
1622 . "to recent $result_class->... direct class calls). This is almost "
1623 . "always a mistake: perhaps you forgot a cycle of "
1624 . "$schema_class->unregister_source( '$source_name' ) / "
1625 . "$schema_class->register_class( '$source_name' => '$result_class' )"
1628 DBIx::Class::_ENV_::ASSERT_NO_ERRONEOUS_METAINSTANCE_USE
1629 ? emit_loud_diag( msg => $msg, confess => 1 )
1638 my $global_phase_destroy;
1640 ### NO detected_reinvoked_destructor check
1641 ### This code very much relies on being called multuple times
1643 return if $global_phase_destroy ||= in_global_destruction;
1646 my $srcs = $self->source_registrations;
1648 for my $source_name (keys %$srcs) {
1649 # find first source that is not about to be GCed (someone other than $self
1650 # holds a reference to it) and reattach to it, weakening our own link
1652 # during global destruction (if we have not yet bailed out) this should throw
1653 # which will serve as a signal to not try doing anything else
1654 # however beware - on older perls the exception seems randomly untrappable
1655 # due to some weird race condition during thread joining :(((
1656 if (length ref $srcs->{$source_name} and refcount($srcs->{$source_name}) > 1) {
1657 local $SIG{__DIE__} if $SIG{__DIE__};
1658 local $@ if DBIx::Class::_ENV_::UNSTABLE_DOLLARAT;
1660 $srcs->{$source_name}->schema($self);
1661 weaken $srcs->{$source_name};
1664 $global_phase_destroy = 1;
1671 # Dummy NEXTSTATE ensuring the all temporaries on the stack are garbage
1672 # collected before leaving this scope. Depending on the code above, this
1673 # may very well be just a preventive measure guarding future modifications
1677 sub _unregister_source {
1678 my ($self, $source_name) = @_;
1679 my %reg = %{$self->source_registrations};
1681 my $source = delete $reg{$source_name};
1682 $self->source_registrations(\%reg);
1683 if ($source->result_class) {
1684 my %map = %{$self->class_mappings};
1685 delete $map{$source->result_class};
1686 $self->class_mappings(\%map);
1691 =head2 compose_connection (DEPRECATED)
1695 =item Arguments: $target_namespace, @db_info
1697 =item Return Value: $new_schema
1701 DEPRECATED. You probably wanted compose_namespace.
1703 Actually, you probably just wanted to call connect.
1707 (hidden due to deprecation)
1709 Calls L<DBIx::Class::Schema/"compose_namespace"> to the target namespace,
1710 calls L<DBIx::Class::Schema/connection> with @db_info on the new schema,
1711 then injects the L<DBix::Class::ResultSetProxy> component and a
1712 resultset_instance classdata entry on all the new classes, in order to support
1713 $target_namespaces::$class->search(...) method calls.
1715 This is primarily useful when you have a specific need for class method access
1716 to a connection. In normal usage it is preferred to call
1717 L<DBIx::Class::Schema/connect> and use the resulting schema object to operate
1718 on L<DBIx::Class::ResultSet> objects with L<DBIx::Class::Schema/resultset> for
1725 sub compose_connection {
1726 my ($self, $target, @info) = @_;
1728 carp_once "compose_connection deprecated as of 0.08000"
1729 unless $INC{"DBIx/Class/CDBICompat.pm"};
1732 require DBIx::Class::ResultSetProxy;
1735 $self->throw_exception
1736 ("No arguments to load_classes and couldn't load DBIx::Class::ResultSetProxy ($_)")
1739 if ($self eq $target) {
1740 # Pathological case, largely caused by the docs on early C::M::DBIC::Plain
1741 foreach my $source_name ($self->sources) {
1742 my $source = $self->source($source_name);
1743 my $class = $source->result_class;
1744 $self->inject_base($class, 'DBIx::Class::ResultSetProxy');
1745 $class->mk_classaccessor(resultset_instance => $source->resultset);
1746 $class->mk_classaccessor(class_resolver => $self);
1748 $self->connection(@info);
1752 my $schema = $self->compose_namespace($target, 'DBIx::Class::ResultSetProxy');
1753 quote_sub "${target}::schema", '$s', { '$s' => \$schema };
1755 $schema->connection(@info);
1756 foreach my $source_name ($schema->sources) {
1757 my $source = $schema->source($source_name);
1758 my $class = $source->result_class;
1759 #warn "$source_name $class $source ".$source->storage;
1761 $class->mk_group_accessors( inherited => [ result_source_instance => '_result_source' ] );
1762 # explicit set-call, avoid mro update lag
1763 $class->set_inherited( result_source_instance => $source );
1765 $class->mk_classaccessor(resultset_instance => $source->resultset);
1766 $class->mk_classaccessor(class_resolver => $schema);
1771 =head1 FURTHER QUESTIONS?
1773 Check the list of L<additional DBIC resources|DBIx::Class/GETTING HELP/SUPPORT>.
1775 =head1 COPYRIGHT AND LICENSE
1777 This module is free software L<copyright|DBIx::Class/COPYRIGHT AND LICENSE>
1778 by the L<DBIx::Class (DBIC) authors|DBIx::Class/AUTHORS>. You can
1779 redistribute it and/or modify it under the same terms as the
1780 L<DBIx::Class library|DBIx::Class/COPYRIGHT AND LICENSE>.