1 package DBIx::Class::Schema;
6 use DBIx::Class::Exception;
7 use Carp::Clan qw/^DBIx::Class|^Try::Tiny/;
9 use Scalar::Util 'weaken';
11 use Sub::Name 'subname';
16 use base qw/DBIx::Class/;
18 __PACKAGE__->mk_classdata('class_mappings' => {});
19 __PACKAGE__->mk_classdata('source_registrations' => {});
20 __PACKAGE__->mk_classdata('storage_type' => '::DBI');
21 __PACKAGE__->mk_classdata('storage');
22 __PACKAGE__->mk_classdata('exception_action');
23 __PACKAGE__->mk_classdata('stacktrace' => $ENV{DBIC_TRACE} || 0);
24 __PACKAGE__->mk_classdata('default_resultset_attributes' => {});
28 DBIx::Class::Schema - composable schemas
32 package Library::Schema;
33 use base qw/DBIx::Class::Schema/;
35 # load all Result classes in Library/Schema/Result/
36 __PACKAGE__->load_namespaces();
38 package Library::Schema::Result::CD;
39 use base qw/DBIx::Class::Core/;
41 __PACKAGE__->load_components(qw/InflateColumn::DateTime/); # for example
42 __PACKAGE__->table('cd');
44 # Elsewhere in your code:
45 my $schema1 = Library::Schema->connect(
52 my $schema2 = Library::Schema->connect($coderef_returning_dbh);
54 # fetch objects using Library::Schema::Result::DVD
55 my $resultset = $schema1->resultset('DVD')->search( ... );
56 my @dvd_objects = $schema2->resultset('DVD')->search( ... );
60 Creates database classes based on a schema. This is the recommended way to
61 use L<DBIx::Class> and allows you to use more than one concurrent connection
64 NB: If you're used to L<Class::DBI> it's worth reading the L</SYNOPSIS>
65 carefully, as DBIx::Class does things a little differently. Note in
66 particular which module inherits off which.
70 =head2 load_namespaces
74 =item Arguments: %options?
78 __PACKAGE__->load_namespaces();
80 __PACKAGE__->load_namespaces(
81 result_namespace => 'Res',
82 resultset_namespace => 'RSet',
83 default_resultset_class => '+MyDB::Othernamespace::RSet',
86 With no arguments, this method uses L<Module::Find> to load all your
87 Result classes from a sub-namespace F<Result> under your Schema class'
88 namespace, i.e. with a Schema of I<MyDB::Schema> all files in
89 I<MyDB::Schema::Result> are assumed to be Result classes.
91 It also finds all ResultSet classes in the namespace F<ResultSet> and
92 loads them into the appropriate Result classes using for you. The
93 matching is done by assuming the package name of the ResultSet class
94 is the same as that of the Result class.
96 You will be warned if ResultSet classes are discovered for which there
97 are no matching Result classes like this:
99 load_namespaces found ResultSet class $classname with no corresponding Result class
101 If a Result class is found to already have a ResultSet class set using
102 L</resultset_class> to some other class, you will be warned like this:
104 We found ResultSet class '$rs_class' for '$result', but it seems
105 that you had already set '$result' to use '$rs_set' instead
107 Both of the sub-namespaces are configurable if you don't like the defaults,
108 via the options C<result_namespace> and C<resultset_namespace>.
110 If (and only if) you specify the option C<default_resultset_class>, any found
111 Result classes for which we do not find a corresponding
112 ResultSet class will have their C<resultset_class> set to
113 C<default_resultset_class>.
115 All of the namespace and classname options to this method are relative to
116 the schema classname by default. To specify a fully-qualified name, prefix
117 it with a literal C<+>.
121 # load My::Schema::Result::CD, My::Schema::Result::Artist,
122 # My::Schema::ResultSet::CD, etc...
123 My::Schema->load_namespaces;
125 # Override everything to use ugly names.
126 # In this example, if there is a My::Schema::Res::Foo, but no matching
127 # My::Schema::RSets::Foo, then Foo will have its
128 # resultset_class set to My::Schema::RSetBase
129 My::Schema->load_namespaces(
130 result_namespace => 'Res',
131 resultset_namespace => 'RSets',
132 default_resultset_class => 'RSetBase',
135 # Put things in other namespaces
136 My::Schema->load_namespaces(
137 result_namespace => '+Some::Place::Results',
138 resultset_namespace => '+Another::Place::RSets',
141 If you'd like to use multiple namespaces of each type, simply use an arrayref
142 of namespaces for that option. In the case that the same result
143 (or resultset) class exists in multiple namespaces, the latter entries in
144 your list of namespaces will override earlier ones.
146 My::Schema->load_namespaces(
147 # My::Schema::Results_C::Foo takes precedence over My::Schema::Results_B::Foo :
148 result_namespace => [ 'Results_A', 'Results_B', 'Results_C' ],
149 resultset_namespace => [ '+Some::Place::RSets', 'RSets' ],
154 # Pre-pends our classname to the given relative classname or
155 # class namespace, unless there is a '+' prefix, which will
157 sub _expand_relative_name {
158 my ($class, $name) = @_;
160 $name = $class . '::' . $name if ! ($name =~ s/^\+//);
164 # Finds all modules in the supplied namespace, or if omitted in the
165 # namespace of $class. Untaints all findings as they can be assumed
169 my $ns = shift || ref $proto || $proto;
171 my @mods = Module::Find::findallmod($ns);
173 # try to untaint module names. mods where this fails
174 # are left alone so we don't have to change the old behavior
175 no locale; # localized \w doesn't untaint expression
176 return map { $_ =~ m/^( (?:\w+::)* \w+ )$/x ? $1 : $_ } @mods;
179 # returns a hash of $shortname => $fullname for every package
180 # found in the given namespaces ($shortname is with the $fullname's
181 # namespace stripped off)
182 sub _map_namespaces {
183 my ($class, @namespaces) = @_;
186 foreach my $namespace (@namespaces) {
189 map { (substr($_, length "${namespace}::"), $_) }
190 $class->_findallmod($namespace)
197 # returns the result_source_instance for the passed class/object,
198 # or dies with an informative message (used by load_namespaces)
199 sub _ns_get_rsrc_instance {
201 my $rs = ref ($_[0]) || $_[0];
203 if ($rs->can ('result_source_instance') ) {
204 return $rs->result_source_instance;
207 $class->throw_exception (
208 "Attempt to load_namespaces() class $rs failed - are you sure this is a real Result Class?"
213 sub load_namespaces {
214 my ($class, %args) = @_;
216 my $result_namespace = delete $args{result_namespace} || 'Result';
217 my $resultset_namespace = delete $args{resultset_namespace} || 'ResultSet';
218 my $default_resultset_class = delete $args{default_resultset_class};
220 $class->throw_exception('load_namespaces: unknown option(s): '
221 . join(q{,}, map { qq{'$_'} } keys %args))
222 if scalar keys %args;
224 $default_resultset_class
225 = $class->_expand_relative_name($default_resultset_class);
227 for my $arg ($result_namespace, $resultset_namespace) {
228 $arg = [ $arg ] if !ref($arg) && $arg;
230 $class->throw_exception('load_namespaces: namespace arguments must be '
231 . 'a simple string or an arrayref')
232 if ref($arg) ne 'ARRAY';
234 $_ = $class->_expand_relative_name($_) for (@$arg);
237 my %results = $class->_map_namespaces(@$result_namespace);
238 my %resultsets = $class->_map_namespaces(@$resultset_namespace);
242 no warnings 'redefine';
243 local *Class::C3::reinitialize = sub { };
244 use warnings 'redefine';
246 # ensure classes are loaded and attached in inheritance order
247 $class->ensure_class_loaded($_) foreach(values %results);
249 my @subclass_last = sort {
252 scalar @{mro::get_linear_isa( $results{$a} )}
258 scalar @{mro::get_linear_isa( $results{$b} )}
263 foreach my $result (@subclass_last) {
264 my $result_class = $results{$result};
266 my $rs_class = delete $resultsets{$result};
267 my $rs_set = $class->_ns_get_rsrc_instance ($result_class)->resultset_class;
269 if($rs_set && $rs_set ne 'DBIx::Class::ResultSet') {
270 if($rs_class && $rs_class ne $rs_set) {
271 carp "We found ResultSet class '$rs_class' for '$result', but it seems "
272 . "that you had already set '$result' to use '$rs_set' instead";
275 elsif($rs_class ||= $default_resultset_class) {
276 $class->ensure_class_loaded($rs_class);
277 if(!$rs_class->isa("DBIx::Class::ResultSet")) {
278 carp "load_namespaces found ResultSet class $rs_class that does not subclass DBIx::Class::ResultSet";
281 $class->_ns_get_rsrc_instance ($result_class)->resultset_class($rs_class);
284 my $source_name = $class->_ns_get_rsrc_instance ($result_class)->source_name || $result;
286 push(@to_register, [ $source_name, $result_class ]);
290 foreach (sort keys %resultsets) {
291 carp "load_namespaces found ResultSet class $_ with no "
292 . 'corresponding Result class';
295 Class::C3->reinitialize;
296 $class->register_class(@$_) for (@to_register);
305 =item Arguments: @classes?, { $namespace => [ @classes ] }+
309 L</load_classes> is an alternative method to L</load_namespaces>, both of
310 which serve similar purposes, each with different advantages and disadvantages.
311 In the general case you should use L</load_namespaces>, unless you need to
312 be able to specify that only specific classes are loaded at runtime.
314 With no arguments, this method uses L<Module::Find> to find all classes under
315 the schema's namespace. Otherwise, this method loads the classes you specify
316 (using L<use>), and registers them (using L</"register_class">).
318 It is possible to comment out classes with a leading C<#>, but note that perl
319 will think it's a mistake (trying to use a comment in a qw list), so you'll
320 need to add C<no warnings 'qw';> before your load_classes call.
322 If any classes found do not appear to be Result class files, you will
323 get the following warning:
325 Failed to load $comp_class. Can't find source_name method. Is
326 $comp_class really a full DBIC result class? Fix it, move it elsewhere,
327 or make your load_classes call more specific.
331 My::Schema->load_classes(); # loads My::Schema::CD, My::Schema::Artist,
332 # etc. (anything under the My::Schema namespace)
334 # loads My::Schema::CD, My::Schema::Artist, Other::Namespace::Producer but
335 # not Other::Namespace::LinerNotes nor My::Schema::Track
336 My::Schema->load_classes(qw/ CD Artist #Track /, {
337 Other::Namespace => [qw/ Producer #LinerNotes /],
343 my ($class, @params) = @_;
348 foreach my $param (@params) {
349 if (ref $param eq 'ARRAY') {
350 # filter out commented entries
351 my @modules = grep { $_ !~ /^#/ } @$param;
353 push (@{$comps_for{$class}}, @modules);
355 elsif (ref $param eq 'HASH') {
356 # more than one namespace possible
357 for my $comp ( keys %$param ) {
358 # filter out commented entries
359 my @modules = grep { $_ !~ /^#/ } @{$param->{$comp}};
361 push (@{$comps_for{$comp}}, @modules);
365 # filter out commented entries
366 push (@{$comps_for{$class}}, $param) if $param !~ /^#/;
370 my @comp = map { substr $_, length "${class}::" }
372 $comps_for{$class} = \@comp;
377 no warnings qw/redefine/;
378 local *Class::C3::reinitialize = sub { };
379 foreach my $prefix (keys %comps_for) {
380 foreach my $comp (@{$comps_for{$prefix}||[]}) {
381 my $comp_class = "${prefix}::${comp}";
382 $class->ensure_class_loaded($comp_class);
384 my $snsub = $comp_class->can('source_name');
386 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.";
389 $comp = $snsub->($comp_class) || $comp;
391 push(@to_register, [ $comp, $comp_class ]);
395 Class::C3->reinitialize;
397 foreach my $to (@to_register) {
398 $class->register_class(@$to);
399 # if $class->can('result_source_instance');
407 =item Arguments: $storage_type|{$storage_type, \%args}
409 =item Return value: $storage_type|{$storage_type, \%args}
411 =item Default value: DBIx::Class::Storage::DBI
415 Set the storage class that will be instantiated when L</connect> is called.
416 If the classname starts with C<::>, the prefix C<DBIx::Class::Storage> is
417 assumed by L</connect>.
419 You want to use this to set subclasses of L<DBIx::Class::Storage::DBI>
420 in cases where the appropriate subclass is not autodetected.
422 If your storage type requires instantiation arguments, those are
423 defined as a second argument in the form of a hashref and the entire
424 value needs to be wrapped into an arrayref or a hashref. We support
425 both types of refs here in order to play nice with your
426 Config::[class] or your choice. See
427 L<DBIx::Class::Storage::DBI::Replicated> for an example of this.
429 =head2 exception_action
433 =item Arguments: $code_reference
435 =item Return value: $code_reference
437 =item Default value: None
441 When L</throw_exception> is invoked and L</exception_action> is set to a code
442 reference, this reference will be called instead of
443 L<DBIx::Class::Exception/throw>, with the exception message passed as the only
446 Your custom throw code B<must> rethrow the exception, as L</throw_exception> is
447 an integral part of DBIC's internal execution control flow.
452 use base qw/DBIx::Class::Schema/;
453 use My::ExceptionClass;
454 __PACKAGE__->exception_action(sub { My::ExceptionClass->throw(@_) });
455 __PACKAGE__->load_classes;
458 my $schema_obj = My::Schema->connect( .... );
459 $schema_obj->exception_action(sub { My::ExceptionClass->throw(@_) });
465 =item Arguments: boolean
469 Whether L</throw_exception> should include stack trace information.
470 Defaults to false normally, but defaults to true if C<$ENV{DBIC_TRACE}>
473 =head2 sqlt_deploy_hook
477 =item Arguments: $sqlt_schema
481 An optional sub which you can declare in your own Schema class that will get
482 passed the L<SQL::Translator::Schema> object when you deploy the schema via
483 L</create_ddl_dir> or L</deploy>.
485 For an example of what you can do with this, see
486 L<DBIx::Class::Manual::Cookbook/Adding Indexes And Functions To Your SQL>.
488 Note that sqlt_deploy_hook is called by L</deployment_statements>, which in turn
489 is called before L</deploy>. Therefore the hook can be used only to manipulate
490 the L<SQL::Translator::Schema> object before it is turned into SQL fed to the
491 database. If you want to execute post-deploy statements which can not be generated
492 by L<SQL::Translator>, the currently suggested method is to overload L</deploy>
493 and use L<dbh_do|DBIx::Class::Storage::DBI/dbh_do>.
501 =item Arguments: @connectinfo
503 =item Return Value: $new_schema
507 Creates and returns a new Schema object. The connection info set on it
508 is used to create a new instance of the storage backend and set it on
511 See L<DBIx::Class::Storage::DBI/"connect_info"> for DBI-specific
512 syntax on the C<@connectinfo> argument, or L<DBIx::Class::Storage> in
515 Note that C<connect_info> expects an arrayref of arguments, but
516 C<connect> does not. C<connect> wraps its arguments in an arrayref
517 before passing them to C<connect_info>.
521 C<connect> is a convenience method. It is equivalent to calling
522 $schema->clone->connection(@connectinfo). To write your own overloaded
523 version, overload L</connection> instead.
527 sub connect { shift->clone->connection(@_) }
533 =item Arguments: $source_name
535 =item Return Value: $resultset
539 my $rs = $schema->resultset('DVD');
541 Returns the L<DBIx::Class::ResultSet> object for the registered source
547 my ($self, $moniker) = @_;
548 $self->throw_exception('resultset() expects a source name')
549 unless defined $moniker;
550 return $self->source($moniker)->resultset;
557 =item Return Value: @source_names
561 my @source_names = $schema->sources;
563 Lists names of all the sources registered on this Schema object.
567 sub sources { return keys %{shift->source_registrations}; }
573 =item Arguments: $source_name
575 =item Return Value: $result_source
579 my $source = $schema->source('Book');
581 Returns the L<DBIx::Class::ResultSource> object for the registered
587 my ($self, $moniker) = @_;
588 my $sreg = $self->source_registrations;
589 return $sreg->{$moniker} if exists $sreg->{$moniker};
591 # if we got here, they probably passed a full class name
592 my $mapped = $self->class_mappings->{$moniker};
593 $self->throw_exception("Can't find source for ${moniker}")
594 unless $mapped && exists $sreg->{$mapped};
595 return $sreg->{$mapped};
602 =item Arguments: $source_name
604 =item Return Value: $classname
608 my $class = $schema->class('CD');
610 Retrieves the Result class name for the given source name.
615 my ($self, $moniker) = @_;
616 return $self->source($moniker)->result_class;
623 =item Arguments: C<$coderef>, @coderef_args?
625 =item Return Value: The return value of $coderef
629 Executes C<$coderef> with (optional) arguments C<@coderef_args> atomically,
630 returning its result (if any). Equivalent to calling $schema->storage->txn_do.
631 See L<DBIx::Class::Storage/"txn_do"> for more information.
633 This interface is preferred over using the individual methods L</txn_begin>,
634 L</txn_commit>, and L</txn_rollback> below.
636 WARNING: If you are connected with C<< AutoCommit => 0 >> the transaction is
637 considered nested, and you will still need to call L</txn_commit> to write your
638 changes when appropriate. You will also want to connect with C<< auto_savepoint =>
639 1 >> to get partial rollback to work, if the storage driver for your database
642 Connecting with C<< AutoCommit => 1 >> is recommended.
649 $self->storage or $self->throw_exception
650 ('txn_do called on $schema without storage');
652 $self->storage->txn_do(@_);
655 =head2 txn_scope_guard
657 Runs C<txn_scope_guard> on the schema's storage. See
658 L<DBIx::Class::Storage/txn_scope_guard>.
662 sub txn_scope_guard {
665 $self->storage or $self->throw_exception
666 ('txn_scope_guard called on $schema without storage');
668 $self->storage->txn_scope_guard(@_);
673 Begins a transaction (does nothing if AutoCommit is off). Equivalent to
674 calling $schema->storage->txn_begin. See
675 L<DBIx::Class::Storage/"txn_begin"> for more information.
682 $self->storage or $self->throw_exception
683 ('txn_begin called on $schema without storage');
685 $self->storage->txn_begin;
690 Commits the current transaction. Equivalent to calling
691 $schema->storage->txn_commit. See L<DBIx::Class::Storage/"txn_commit">
692 for more information.
699 $self->storage or $self->throw_exception
700 ('txn_commit called on $schema without storage');
702 $self->storage->txn_commit;
707 Rolls back the current transaction. Equivalent to calling
708 $schema->storage->txn_rollback. See
709 L<DBIx::Class::Storage/"txn_rollback"> for more information.
716 $self->storage or $self->throw_exception
717 ('txn_rollback called on $schema without storage');
719 $self->storage->txn_rollback;
724 my $storage = $schema->storage;
726 Returns the L<DBIx::Class::Storage> object for this Schema. Grab this
727 if you want to turn on SQL statement debugging at runtime, or set the
728 quote character. For the default storage, the documentation can be
729 found in L<DBIx::Class::Storage::DBI>.
735 =item Arguments: $source_name, \@data;
737 =item Return value: \@$objects | nothing
741 Pass this method a resultsource name, and an arrayref of
742 arrayrefs. The arrayrefs should contain a list of column names,
743 followed by one or many sets of matching data for the given columns.
745 In void context, C<insert_bulk> in L<DBIx::Class::Storage::DBI> is used
746 to insert the data, as this is a fast method. However, insert_bulk currently
747 assumes that your datasets all contain the same type of values, using scalar
748 references in a column in one row, and not in another will probably not work.
750 Otherwise, each set of data is inserted into the database using
751 L<DBIx::Class::ResultSet/create>, and a arrayref of the resulting row
756 $schema->populate('Artist', [
757 [ qw/artistid name/ ],
758 [ 1, 'Popular Band' ],
763 Since wantarray context is basically the same as looping over $rs->create(...)
764 you won't see any performance benefits and in this case the method is more for
765 convenience. Void context sends the column information directly to storage
766 using <DBI>s bulk insert method. So the performance will be much better for
767 storages that support this method.
769 Because of this difference in the way void context inserts rows into your
770 database you need to note how this will effect any loaded components that
771 override or augment insert. For example if you are using a component such
772 as L<DBIx::Class::UUIDColumns> to populate your primary keys you MUST use
773 wantarray context if you want the PKs automatically created.
778 my ($self, $name, $data) = @_;
779 if(my $rs = $self->resultset($name)) {
780 if(defined wantarray) {
781 return $rs->populate($data);
783 $rs->populate($data);
786 $self->throw_exception("$name is not a resultset");
794 =item Arguments: @args
796 =item Return Value: $new_schema
800 Similar to L</connect> except sets the storage object and connection
801 data in-place on the Schema class. You should probably be calling
802 L</connect> to get a proper Schema object instead.
806 Overload C<connection> to change the behaviour of C<connect>.
811 my ($self, @info) = @_;
812 return $self if !@info && $self->storage;
814 my ($storage_class, $args) = ref $self->storage_type ?
815 ($self->_normalize_storage_type($self->storage_type),{}) : ($self->storage_type, {});
817 $storage_class = 'DBIx::Class::Storage'.$storage_class
818 if $storage_class =~ m/^::/;
820 $self->ensure_class_loaded ($storage_class);
823 $self->throw_exception(
824 "No arguments to load_classes and couldn't load ${storage_class} ($_)"
827 my $storage = $storage_class->new($self=>$args);
828 $storage->connect_info(\@info);
829 $self->storage($storage);
833 sub _normalize_storage_type {
834 my ($self, $storage_type) = @_;
835 if(ref $storage_type eq 'ARRAY') {
836 return @$storage_type;
837 } elsif(ref $storage_type eq 'HASH') {
838 return %$storage_type;
840 $self->throw_exception('Unsupported REFTYPE given: '. ref $storage_type);
844 =head2 compose_namespace
848 =item Arguments: $target_namespace, $additional_base_class?
850 =item Retur Value: $new_schema
854 For each L<DBIx::Class::ResultSource> in the schema, this method creates a
855 class in the target namespace (e.g. $target_namespace::CD,
856 $target_namespace::Artist) that inherits from the corresponding classes
857 attached to the current schema.
859 It also attaches a corresponding L<DBIx::Class::ResultSource> object to the
860 new $schema object. If C<$additional_base_class> is given, the new composed
861 classes will inherit from first the corresponding class from the current
862 schema then the base class.
864 For example, for a schema with My::Schema::CD and My::Schema::Artist classes,
866 $schema->compose_namespace('My::DB', 'Base::Class');
867 print join (', ', @My::DB::CD::ISA) . "\n";
868 print join (', ', @My::DB::Artist::ISA) ."\n";
870 will produce the output
872 My::Schema::CD, Base::Class
873 My::Schema::Artist, Base::Class
877 # this might be oversimplified
878 # sub compose_namespace {
879 # my ($self, $target, $base) = @_;
881 # my $schema = $self->clone;
882 # foreach my $moniker ($schema->sources) {
883 # my $source = $schema->source($moniker);
884 # my $target_class = "${target}::${moniker}";
885 # $self->inject_base(
886 # $target_class => $source->result_class, ($base ? $base : ())
888 # $source->result_class($target_class);
889 # $target_class->result_source_instance($source)
890 # if $target_class->can('result_source_instance');
891 # $schema->register_source($moniker, $source);
896 sub compose_namespace {
897 my ($self, $target, $base) = @_;
898 my $schema = $self->clone;
900 no warnings qw/redefine/;
901 # local *Class::C3::reinitialize = sub { };
902 foreach my $moniker ($schema->sources) {
903 my $source = $schema->source($moniker);
904 my $target_class = "${target}::${moniker}";
906 $target_class => $source->result_class, ($base ? $base : ())
908 $source->result_class($target_class);
909 $target_class->result_source_instance($source)
910 if $target_class->can('result_source_instance');
911 $schema->register_source($moniker, $source);
914 # Class::C3->reinitialize();
917 no warnings 'redefine';
918 foreach my $meth (qw/class source resultset/) {
919 *{"${target}::${meth}"} = subname "${target}::${meth}" =>
920 sub { shift->schema->$meth(@_) };
926 sub setup_connection_class {
927 my ($class, $target, @info) = @_;
928 $class->inject_base($target => 'DBIx::Class::DB');
929 #$target->load_components('DB');
930 $target->connection(@info);
935 Creates a new savepoint (does nothing outside a transaction).
936 Equivalent to calling $schema->storage->svp_begin. See
937 L<DBIx::Class::Storage/"svp_begin"> for more information.
942 my ($self, $name) = @_;
944 $self->storage or $self->throw_exception
945 ('svp_begin called on $schema without storage');
947 $self->storage->svp_begin($name);
952 Releases a savepoint (does nothing outside a transaction).
953 Equivalent to calling $schema->storage->svp_release. See
954 L<DBIx::Class::Storage/"svp_release"> for more information.
959 my ($self, $name) = @_;
961 $self->storage or $self->throw_exception
962 ('svp_release called on $schema without storage');
964 $self->storage->svp_release($name);
969 Rollback to a savepoint (does nothing outside a transaction).
970 Equivalent to calling $schema->storage->svp_rollback. See
971 L<DBIx::Class::Storage/"svp_rollback"> for more information.
976 my ($self, $name) = @_;
978 $self->storage or $self->throw_exception
979 ('svp_rollback called on $schema without storage');
981 $self->storage->svp_rollback($name);
988 =item Return Value: $new_schema
992 Clones the schema and its associated result_source objects and returns the
999 my $clone = { (ref $self ? %$self : ()) };
1000 bless $clone, (ref $self || $self);
1002 $clone->class_mappings({ %{$clone->class_mappings} });
1003 $clone->source_registrations({ %{$clone->source_registrations} });
1004 foreach my $moniker ($self->sources) {
1005 my $source = $self->source($moniker);
1006 my $new = $source->new($source);
1007 # we use extra here as we want to leave the class_mappings as they are
1008 # but overwrite the source_registrations entry with the new source
1009 $clone->register_extra_source($moniker => $new);
1011 $clone->storage->set_schema($clone) if $clone->storage;
1015 =head2 throw_exception
1019 =item Arguments: $message
1023 Throws an exception. Defaults to using L<Carp::Clan> to report errors from
1024 user's perspective. See L</exception_action> for details on overriding
1025 this method's behavior. If L</stacktrace> is turned on, C<throw_exception>'s
1026 default behavior will provide a detailed stack trace.
1030 my $false_exception_action_warned;
1031 sub throw_exception {
1034 if (my $act = $self->exception_action) {
1036 DBIx::Class::Exception->throw(
1037 "Invocation of the exception_action handler installed on $self did *not*"
1038 .' result in an exception. DBIx::Class is unable to function without a reliable'
1039 .' exception mechanism, ensure that exception_action does not hide exceptions'
1040 ." (original error: $_[0])"
1043 elsif(! $false_exception_action_warned++) {
1045 "The exception_action handler installed on $self returned false instead"
1046 .' of throwing an exception. This behavior has been deprecated, adjust your'
1047 .' handler to always rethrow the supplied error.'
1052 DBIx::Class::Exception->throw($_[0], $self->stacktrace);
1059 =item Arguments: \%sqlt_args, $dir
1063 Attempts to deploy the schema to the current storage using L<SQL::Translator>.
1065 See L<SQL::Translator/METHODS> for a list of values for C<\%sqlt_args>.
1066 The most common value for this would be C<< { add_drop_table => 1 } >>
1067 to have the SQL produced include a C<DROP TABLE> statement for each table
1068 created. For quoting purposes supply C<quote_table_names> and
1069 C<quote_field_names>.
1071 Additionally, the DBIx::Class parser accepts a C<sources> parameter as a hash
1072 ref or an array ref, containing a list of source to deploy. If present, then
1073 only the sources listed will get deployed. Furthermore, you can use the
1074 C<add_fk_index> parser parameter to prevent the parser from creating an index for each
1080 my ($self, $sqltargs, $dir) = @_;
1081 $self->throw_exception("Can't deploy without storage") unless $self->storage;
1082 $self->storage->deploy($self, undef, $sqltargs, $dir);
1085 =head2 deployment_statements
1089 =item Arguments: See L<DBIx::Class::Storage::DBI/deployment_statements>
1091 =item Return value: $listofstatements
1095 A convenient shortcut to
1096 C<< $self->storage->deployment_statements($self, @args) >>.
1097 Returns the SQL statements used by L</deploy> and
1098 L<DBIx::Class::Schema::Storage/deploy>.
1102 sub deployment_statements {
1105 $self->throw_exception("Can't generate deployment statements without a storage")
1106 if not $self->storage;
1108 $self->storage->deployment_statements($self, @_);
1111 =head2 create_ddl_dir
1115 =item Arguments: See L<DBIx::Class::Storage::DBI/create_ddl_dir>
1119 A convenient shortcut to
1120 C<< $self->storage->create_ddl_dir($self, @args) >>.
1122 Creates an SQL file based on the Schema, for each of the specified
1123 database types, in the given directory.
1127 sub create_ddl_dir {
1130 $self->throw_exception("Can't create_ddl_dir without storage") unless $self->storage;
1131 $self->storage->create_ddl_dir($self, @_);
1138 =item Arguments: $database-type, $version, $directory, $preversion
1140 =item Return value: $normalised_filename
1144 my $filename = $table->ddl_filename($type, $version, $dir, $preversion)
1146 This method is called by C<create_ddl_dir> to compose a file name out of
1147 the supplied directory, database type and version number. The default file
1148 name format is: C<$dir$schema-$version-$type.sql>.
1150 You may override this method in your schema if you wish to use a different
1155 Prior to DBIx::Class version 0.08100 this method had a different signature:
1157 my $filename = $table->ddl_filename($type, $dir, $version, $preversion)
1159 In recent versions variables $dir and $version were reversed in order to
1160 bring the signature in line with other Schema/Storage methods. If you
1161 really need to maintain backward compatibility, you can do the following
1162 in any overriding methods:
1164 ($dir, $version) = ($version, $dir) if ($DBIx::Class::VERSION < 0.08100);
1169 my ($self, $type, $version, $dir, $preversion) = @_;
1171 my $filename = ref($self);
1172 $filename =~ s/::/-/g;
1173 $filename = File::Spec->catfile($dir, "$filename-$version-$type.sql");
1174 $filename =~ s/$version/$preversion-$version/ if($preversion);
1181 Provided as the recommended way of thawing schema objects. You can call
1182 C<Storable::thaw> directly if you wish, but the thawed objects will not have a
1183 reference to any schema, so are rather useless.
1188 my ($self, $obj) = @_;
1189 local $DBIx::Class::ResultSourceHandle::thaw_schema = $self;
1190 return Storable::thaw($obj);
1195 This doesn't actually do anything more than call L<Storable/freeze>, it is just
1196 provided here for symmetry.
1201 return Storable::freeze($_[1]);
1208 =item Arguments: $object
1210 =item Return Value: dcloned $object
1214 Recommended way of dcloning L<DBIx::Class::Row> and L<DBIx::Class::ResultSet>
1215 objects so their references to the schema object
1216 (which itself is B<not> cloned) are properly maintained.
1221 my ($self, $obj) = @_;
1222 local $DBIx::Class::ResultSourceHandle::thaw_schema = $self;
1223 return Storable::dclone($obj);
1226 =head2 schema_version
1228 Returns the current schema class' $VERSION in a normalised way.
1232 sub schema_version {
1234 my $class = ref($self)||$self;
1236 # does -not- use $schema->VERSION
1237 # since that varies in results depending on if version.pm is installed, and if
1238 # so the perl or XS versions. If you want this to change, bug the version.pm
1239 # author to make vpp and vxs behave the same.
1244 $version = ${"${class}::VERSION"};
1250 =head2 register_class
1254 =item Arguments: $moniker, $component_class
1258 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.
1260 You will only need this method if you have your Result classes in
1261 files which are not named after the packages (or all in the same
1262 file). You may also need it to register classes at runtime.
1264 Registers a class which isa DBIx::Class::ResultSourceProxy. Equivalent to
1267 $schema->register_source($moniker, $component_class->result_source_instance);
1271 sub register_class {
1272 my ($self, $moniker, $to_register) = @_;
1273 $self->register_source($moniker => $to_register->result_source_instance);
1276 =head2 register_source
1280 =item Arguments: $moniker, $result_source
1284 This method is called by L</register_class>.
1286 Registers the L<DBIx::Class::ResultSource> in the schema with the given
1291 sub register_source {
1294 $self->_register_source(@_);
1297 =head2 unregister_source
1301 =item Arguments: $moniker
1305 Removes the L<DBIx::Class::ResultSource> from the schema for the given moniker.
1309 sub unregister_source {
1312 $self->_unregister_source(@_);
1315 =head2 register_extra_source
1319 =item Arguments: $moniker, $result_source
1323 As L</register_source> but should be used if the result class already
1324 has a source and you want to register an extra one.
1328 sub register_extra_source {
1331 $self->_register_source(@_, { extra => 1 });
1334 sub _register_source {
1335 my ($self, $moniker, $source, $params) = @_;
1337 my $orig_source = $source;
1339 $source = $source->new({ %$source, source_name => $moniker });
1340 $source->schema($self);
1341 weaken $source->{schema} if ref($self);
1343 my $rs_class = $source->result_class;
1345 my %reg = %{$self->source_registrations};
1346 $reg{$moniker} = $source;
1347 $self->source_registrations(\%reg);
1349 return if ($params->{extra});
1350 return unless defined($rs_class) && $rs_class->can('result_source_instance');
1352 my %map = %{$self->class_mappings};
1354 exists $map{$rs_class}
1356 $map{$rs_class} ne $moniker
1358 $rs_class->result_source_instance ne $orig_source
1360 carp "$rs_class already has a source, use register_extra_source for additional sources";
1362 $map{$rs_class} = $moniker;
1363 $self->class_mappings(\%map);
1366 sub _unregister_source {
1367 my ($self, $moniker) = @_;
1368 my %reg = %{$self->source_registrations};
1370 my $source = delete $reg{$moniker};
1371 $self->source_registrations(\%reg);
1372 if ($source->result_class) {
1373 my %map = %{$self->class_mappings};
1374 delete $map{$source->result_class};
1375 $self->class_mappings(\%map);
1380 =head2 compose_connection (DEPRECATED)
1384 =item Arguments: $target_namespace, @db_info
1386 =item Return Value: $new_schema
1390 DEPRECATED. You probably wanted compose_namespace.
1392 Actually, you probably just wanted to call connect.
1396 (hidden due to deprecation)
1398 Calls L<DBIx::Class::Schema/"compose_namespace"> to the target namespace,
1399 calls L<DBIx::Class::Schema/connection> with @db_info on the new schema,
1400 then injects the L<DBix::Class::ResultSetProxy> component and a
1401 resultset_instance classdata entry on all the new classes, in order to support
1402 $target_namespaces::$class->search(...) method calls.
1404 This is primarily useful when you have a specific need for class method access
1405 to a connection. In normal usage it is preferred to call
1406 L<DBIx::Class::Schema/connect> and use the resulting schema object to operate
1407 on L<DBIx::Class::ResultSet> objects with L<DBIx::Class::Schema/resultset> for
1417 sub compose_connection {
1418 my ($self, $target, @info) = @_;
1420 carp "compose_connection deprecated as of 0.08000"
1421 unless ($INC{"DBIx/Class/CDBICompat.pm"} || $warn++);
1423 my $base = 'DBIx::Class::ResultSetProxy';
1425 eval "require ${base};"
1428 $self->throw_exception
1429 ("No arguments to load_classes and couldn't load ${base} ($_)")
1432 if ($self eq $target) {
1433 # Pathological case, largely caused by the docs on early C::M::DBIC::Plain
1434 foreach my $moniker ($self->sources) {
1435 my $source = $self->source($moniker);
1436 my $class = $source->result_class;
1437 $self->inject_base($class, $base);
1438 $class->mk_classdata(resultset_instance => $source->resultset);
1439 $class->mk_classdata(class_resolver => $self);
1441 $self->connection(@info);
1445 my $schema = $self->compose_namespace($target, $base);
1448 my $name = join '::', $target, 'schema';
1449 *$name = subname $name, sub { $schema };
1452 $schema->connection(@info);
1453 foreach my $moniker ($schema->sources) {
1454 my $source = $schema->source($moniker);
1455 my $class = $source->result_class;
1456 #warn "$moniker $class $source ".$source->storage;
1457 $class->mk_classdata(result_source_instance => $source);
1458 $class->mk_classdata(resultset_instance => $source->resultset);
1459 $class->mk_classdata(class_resolver => $schema);
1469 Matt S. Trout <mst@shadowcatsystems.co.uk>
1473 You may distribute this code under the same terms as Perl itself.