Marcus Ramberg > DBIx-Class-0.05999_04 > DBIx::Class::Schema

Download:
DBIx-Class-0.05999_04.tar.gz

Dependencies

Annotate this POD (2)

CPAN RT

New  15
Open  16
Stalled  12
View/Report Bugs
Source   Latest Release: DBIx-Class-0.08270

NAME ^

DBIx::Class::Schema - composable schemas

SYNOPSIS ^

  package My::Schema;
  use base qw/DBIx::Class::Schema/;
  
  # load My::Schema::Foo, My::Schema::Bar, My::Schema::Baz
  __PACKAGE__->load_classes(qw/Foo Bar Baz/);

  package My::Schema::Foo;
  use base qw/DBIx::Class/;
  __PACKAGE__->load_components(qw/PK::Auto::Pg Core/); # for example
  __PACKAGE__->table('foo');

  # Elsewhere in your code:
  my $schema1 = My::Schema->connect(
    $dsn,
    $user,
    $password,
    $attrs
  );
  
  my $schema2 = My::Schema->connect($coderef_returning_dbh);

  # fetch objects using My::Schema::Foo
  my $resultset = $schema1->resultset('Foo')->search( ... );
  my @objects = $schema2->resultset('Foo')->search( ... );

DESCRIPTION ^

Creates database classes based on a schema. This is the recommended way to use DBIx::Class and allows you to use more than one concurrent connection with your classes.

NB: If you're used to Class::DBI it's worth reading the "SYNOPSIS" carefully as DBIx::Class does things a little differently. Note in particular which module inherits off which.

METHODS ^

register_class

Arguments: <moniker> <component_class>

Registers a class which isa ResultSourceProxy; equivalent to calling

  $schema->register_source($moniker, $component_class->result_source_instance);

register_source

Arguments: <moniker> <result source>

Registers the result source in the schema with the given moniker

class

  my $class = $schema->class('Foo');

Retrieves the result class name for a given result source

source

  my $source = $schema->source('Foo');

Returns the result source object for the registered name

sources

  my @source_monikers = $schema->sources;

Returns the source monikers of all source registrations on this schema

resultset

  my $rs = $schema->resultset('Foo');

Returns the resultset for the registered moniker

load_classes

Arguments: [<classes>, (<class>, <class>), {<namespace> => [<classes>]}]

Uses Module::Find to find all classes under the database class' namespace, or uses the classes you select. Then it loads the component (using use), and registers them (using register_class);

It is possible to comment out classes with a leading '#', but note that perl will think it's a mistake (trying to use a comment in a qw list) so you'll need to add "no warnings 'qw';" before your load_classes call.

compose_connection

Arguments: <target> <@db_info>

This is the most important method in this class. it takes a target namespace, as well as dbh connection info, and creates a DBIx::Class::DB class as well as subclasses for each of your database classes in this namespace, using this connection.

It will also setup a ->class method on the target class, which lets you resolve database classes based on the schema component name, for example

  MyApp::DB->class('Foo') # returns MyApp::DB::Foo, 
                          # which ISA MyApp::Schema::Foo

This is the recommended API for accessing Schema generated classes, and using it might give you instant advantages with future versions of DBIC.

WARNING: Loading components into Schema classes after compose_connection may not cause them to be seen by the classes in your target namespace due to the dispatch table approach used by Class::C3. If you do this you may find you need to call Class::C3->reinitialize() afterwards to get the behaviour you expect.

setup_connection_class

Arguments: <$target> <@info>

Sets up a database connection class to inject between the schema and the subclasses the schema creates.

connection

Arguments: (@args)

Instantiates a new Storage object of type storage_type and passes the arguments to $storage->connect_info. Sets the connection in-place on the schema.

connect

Arguments: (@info)

Conveneience method, equivalent to $schema->clone->connection(@info)

txn_begin

Begins a transaction (does nothing if AutoCommit is off).

txn_commit

Commits the current transaction.

txn_rollback

Rolls back the current transaction.

txn_do

Arguments: <$coderef>, [@coderef_args]

Executes $coderef with (optional) arguments @coderef_args transactionally, returning its result (if any). If an exception is caught, a rollback is issued and the exception is rethrown. If the rollback fails, (i.e. throws an exception) an exception is thrown that includes a "Rollback failed" message.

For example,

  my $foo = $schema->resultset('foo')->find(1);

  my $coderef = sub {
    my ($foo, @bars) = @_;

    # If any one of these fails, the entire transaction fails
    $foo->create_related('bars', {
      col => $_
    }) foreach (@bars);

    return $foo->bars;
  };

  my $rs;
  eval {
    $rs = $schema->txn_do($coderef, $foo, qw/foo bar baz/);
  };

  if ($@) {
    my $error = $@;
    if ($error =~ /Rollback failed/) {
      die "something terrible has happened!";
    } else {
      deal_with_failed_transaction();
      die $error;
    }
  }

Nested transactions work as expected (i.e. only the outermost transaction will issue a txn_commit on the Schema's storage)

clone

Clones the schema and its associated result_source objects and returns the copy.

populate

Arguments: ($moniker, \@data);

Populates the source registered with the given moniker with the supplied data. @data should be a list of listrefs, the first containing column names, the second matching values - i.e.

  $schema->populate('Foo', [
    [ qw/foo_id foo_string/ ],
    [ 1, 'One' ],
    [ 2, 'Two' ],
    ...
  ]);

throw_exception

Defaults to using Carp::Clan to report errors from user perspective.

deploy

Attempts to deploy the schema to the current storage

AUTHORS ^

Matt S. Trout <mst@shadowcatsystems.co.uk>

LICENSE ^

You may distribute this code under the same terms as Perl itself.

syntax highlighting: