lib/Catalyst/Model/DBIC/Schema.pm

   1 package Catalyst::Model::DBIC::Schema;
   2
   3 use Moose;
   4 use mro 'c3';
   5 extends 'Catalyst::Model';
   6 with 'MooseX::Object::Pluggable';
   7
   8 our $VERSION = '0.24';
   9
  10 use Carp::Clan '^Catalyst::Model::DBIC::Schema';
  11 use Data::Dumper;
  12 use DBIx::Class ();
  13 use Scalar::Util 'reftype';
  14 use MooseX::ClassAttribute;
  15 use Moose::Autobox;
  16
  17 use Catalyst::Model::DBIC::Schema::Types
  18     qw/ConnectInfo SchemaClass CursorClass/;
  19
  20 use MooseX::Types::Moose qw/ArrayRef Str ClassName/;
  21
  22 use namespace::clean -except => 'meta';
  23
  24 =head1 NAME
  25
  26 Catalyst::Model::DBIC::Schema - DBIx::Class::Schema Model Class
  27
  28 =head1 SYNOPSIS
  29
  30 Manual creation of a DBIx::Class::Schema and a Catalyst::Model::DBIC::Schema:
  31
  32 =over
  33
  34 =item 1.
  35
  36 Create the DBIx:Class schema in MyApp/Schema/FilmDB.pm:
  37
  38   package MyApp::Schema::FilmDB;
  39   use base qw/DBIx::Class::Schema/;
  40
  41   __PACKAGE__->load_classes(qw/Actor Role/);
  42
  43 =item 2.
  44
  45 Create some classes for the tables in the database, for example an
  46 Actor in MyApp/Schema/FilmDB/Actor.pm:
  47
  48   package MyApp::Schema::FilmDB::Actor;
  49   use base qw/DBIx::Class/
  50
  51   __PACKAGE__->load_components(qw/Core/);
  52   __PACKAGE__->table('actor');
  53
  54   ...
  55
  56 and a Role in MyApp/Schema/FilmDB/Role.pm:
  57
  58   package MyApp::Schema::FilmDB::Role;
  59   use base qw/DBIx::Class/
  60
  61   __PACKAGE__->load_components(qw/Core/);
  62   __PACKAGE__->table('role');
  63
  64   ...
  65
  66 Notice that the schema is in MyApp::Schema, not in MyApp::Model. This way it's
  67 usable as a standalone module and you can test/run it without Catalyst.
  68
  69 =item 3.
  70
  71 To expose it to Catalyst as a model, you should create a DBIC Model in
  72 MyApp/Model/FilmDB.pm:
  73
  74   package MyApp::Model::FilmDB;
  75   use base qw/Catalyst::Model::DBIC::Schema/;
  76
  77   __PACKAGE__->config(
  78       schema_class => 'MyApp::Schema::FilmDB',
  79       connect_info => {
  80                         dsn => "DBI:...",
  81                         user => "username",
  82                         password => "password",
  83                       }
  84   );
  85
  86 See below for a full list of the possible config parameters.
  87
  88 =back
  89
  90 Now you have a working Model which accesses your separate DBIC Schema. This can
  91 be used/accessed in the normal Catalyst manner, via $c->model():
  92
  93   my $actor = $c->model('FilmDB::Actor')->find(1);
  94
  95 You can also use it to set up DBIC authentication with
  96 Authentication::Store::DBIC in MyApp.pm:
  97
  98   package MyApp;
  99
 100   use Catalyst qw/... Authentication::Store::DBIC/;
 101
 102   ...
 103
 104   __PACKAGE__->config->{authentication}{dbic} = {
 105       user_class      => 'FilmDB::Actor',
 106       user_field      => 'name',
 107       password_field  => 'password'
 108   }
 109
 110 C<< $c->model('Schema::Source') >> returns a L<DBIx::Class::ResultSet> for
 111 the source name parameter passed. To find out more about which methods can
 112 be called on a ResultSet, or how to add your own methods to it, please see
 113 the ResultSet documentation in the L<DBIx::Class> distribution.
 114
 115 Some examples are given below:
 116
 117   # to access schema methods directly:
 118   $c->model('FilmDB')->schema->source(...);
 119
 120   # to access the source object, resultset, and class:
 121   $c->model('FilmDB')->source(...);
 122   $c->model('FilmDB')->resultset(...);
 123   $c->model('FilmDB')->class(...);
 124
 125   # For resultsets, there's an even quicker shortcut:
 126   $c->model('FilmDB::Actor')
 127   # is the same as $c->model('FilmDB')->resultset('Actor')
 128
 129   # To get the composed schema for making new connections:
 130   my $newconn = $c->model('FilmDB')->composed_schema->connect(...);
 131
 132   # Or the same thing via a convenience shortcut:
 133   my $newconn = $c->model('FilmDB')->connect(...);
 134
 135   # or, if your schema works on different storage drivers:
 136   my $newconn = $c->model('FilmDB')->composed_schema->clone();
 137   $newconn->storage_type('::LDAP');
 138   $newconn->connection(...);
 139
 140   # and again, a convenience shortcut
 141   my $newconn = $c->model('FilmDB')->clone();
 142   $newconn->storage_type('::LDAP');
 143   $newconn->connection(...);
 144
 145 =head1 DESCRIPTION
 146
 147 This is a Catalyst Model for L<DBIx::Class::Schema>-based Models.  See
 148 the documentation for L<Catalyst::Helper::Model::DBIC::Schema> for
 149 information on generating these Models via Helper scripts.
 150
 151 When your Catalyst app starts up, a thin Model layer is created as an
 152 interface to your DBIC Schema. It should be clearly noted that the model
 153 object returned by C<< $c->model('FilmDB') >> is NOT itself a DBIC schema or
 154 resultset object, but merely a wrapper proving L<methods|/METHODS> to access
 155 the underlying schema.
 156
 157 In addition to this model class, a shortcut class is generated for each
 158 source in the schema, allowing easy and direct access to a resultset of the
 159 corresponding type. These generated classes are even thinner than the model
 160 class, providing no public methods but simply hooking into Catalyst's
 161 model() accessor via the
 162 L<ACCEPT_CONTEXT|Catalyst::Component/ACCEPT_CONTEXT> mechanism. The complete
 163 contents of each generated class is roughly equivalent to the following:
 164
 165   package MyApp::Model::FilmDB::Actor
 166   sub ACCEPT_CONTEXT {
 167       my ($self, $c) = @_;
 168       $c->model('FilmDB')->resultset('Actor');
 169   }
 170
 171 In short, there are three techniques available for obtaining a DBIC
 172 resultset object:
 173
 174   # the long way
 175   my $rs = $c->model('FilmDB')->schema->resultset('Actor');
 176
 177   # using the shortcut method on the model object
 178   my $rs = $c->model('FilmDB')->resultset('Actor');
 179
 180   # using the generated class directly
 181   my $rs = $c->model('FilmDB::Actor');
 182
 183 In order to add methods to a DBIC resultset, you cannot simply add them to
 184 the source (row, table) definition class; you must define a separate custom
 185 resultset class. See L<DBIx::Class::Manual::Cookbook/"Predefined searches">
 186 for more info.
 187
 188 =head1 CONFIG PARAMETERS
 189
 190 =head2 schema_class
 191
 192 This is the classname of your L<DBIx::Class::Schema> Schema.  It needs
 193 to be findable in C<@INC>, but it does not need to be inside the
 194 C<Catalyst::Model::> namespace.  This parameter is required.
 195
 196 =head2 connect_info
 197
 198 This is an arrayref of connection parameters, which are specific to your
 199 C<storage_type> (see your storage type documentation for more details).
 200 If you only need one parameter (e.g. the DSN), you can just pass a string
 201 instead of an arrayref.
 202
 203 This is not required if C<schema_class> already has connection information
 204 defined inside itself (which isn't highly recommended, but can be done)
 205
 206 For L<DBIx::Class::Storage::DBI>, which is the only supported
 207 C<storage_type> in L<DBIx::Class> at the time of this writing, the
 208 parameters are your dsn, username, password, and connect options hashref.
 209
 210 See L<DBIx::Class::Storage::DBI/connect_info> for a detailed explanation
 211 of the arguments supported.
 212
 213 Examples:
 214
 215   connect_info => {
 216     dsn => 'dbi:Pg:dbname=mypgdb',
 217     user => 'postgres',
 218     password => ''
 219   }
 220
 221   connect_info => {
 222     dsn => 'dbi:SQLite:dbname=foo.db',
 223     on_connect_do => [
 224       'PRAGMA synchronous = OFF',
 225     ]
 226   }
 227
 228   connect_info => {
 229     dsn => 'dbi:Pg:dbname=mypgdb',
 230     user => 'postgres',
 231     password => '',
 232     pg_enable_utf8 => 1,
 233     on_connect_do => [
 234       'some SQL statement',
 235       'another SQL statement',
 236     ],
 237   }
 238
 239 Or using L<Config::General>:
 240
 241     <Model::FilmDB>
 242         schema_class   MyApp::Schema::FilmDB
 243         roles Caching
 244         <connect_info>
 245             dsn   dbi:Pg:dbname=mypgdb
 246             user   postgres
 247             password ''
 248             auto_savepoint 1
 249             on_connect_do   some SQL statement
 250             on_connect_do   another SQL statement
 251         </connect_info>
 252     </Model::FilmDB>
 253
 254 or
 255
 256     <Model::FilmDB>
 257         schema_class   MyApp::Schema::FilmDB
 258         connect_info   dbi:SQLite:dbname=foo.db
 259     </Model::FilmDB>
 260
 261 Or using L<YAML>:
 262
 263   Model::MyDB:
 264       schema_class: MyDB
 265       connect_info:
 266           dsn: dbi:Oracle:mydb
 267           user: mtfnpy
 268           password: mypass
 269           LongReadLen: 1000000
 270           LongTruncOk: 1
 271           on_connect_do: [ "alter session set nls_date_format = 'YYYY-MM-DD HH24:MI:SS'" ]
 272           cursor_class: 'DBIx::Class::Cursor::Cached'
 273
 274 The old arrayref style with hashrefs for L<DBI> then L<DBIx::Class> options is also
 275 supported:
 276
 277   connect_info => [
 278     'dbi:Pg:dbname=mypgdb',
 279     'postgres',
 280     '',
 281     {
 282       pg_enable_utf8 => 1,
 283     },
 284     {
 285       auto_savepoint => 1,
 286       on_connect_do => [
 287         'some SQL statement',
 288         'another SQL statement',
 289       ],
 290     }
 291   ]
 292
 293 =head2 roles
 294
 295 Array of Roles to apply at BUILD time. Roles are relative to the
 296 C<<MyApp::Model::DB::Role::> then C<<Catalyst::Model::DBIC::Schema::Role::>>
 297 namespaces, unless prefixed with C<+> in which case they are taken to be a
 298 fully qualified name. E.g.:
 299
 300     roles Caching
 301     roles +MyApp::DB::Role::Foo
 302
 303 This is done using L<MooseX::Object::Pluggable>.
 304
 305 A new instance is created at application time, so any consumed required
 306 attributes, coercions and modifiers will work.
 307
 308 Roles are applied before setup, schema and connection are set.
 309
 310 C<ref $self> will be an anon class if any roles are applied.
 311
 312 You cannot modify C<new> or C<BUILD>, modify C<setup> instead.
 313
 314 L</ACCEPT_CONTEXT> and L</finalize> can also be modified.
 315
 316 Roles that come with the distribution:
 317
 318 =over 4
 319
 320 =item L<Catalyst::Model::DBIC::Schema::Role::Caching>
 321
 322 =item L<Catalyst::Model::DBIC::Schema::Role::Replicated>
 323
 324 =back
 325
 326 =head2 storage_type
 327
 328 Allows the use of a different C<storage_type> than what is set in your
 329 C<schema_class> (which in turn defaults to C<::DBI> if not set in current
 330 L<DBIx::Class>).  Completely optional, and probably unnecessary for most
 331 people until other storage backends become available for L<DBIx::Class>.
 332
 333 =head1 METHODS
 334
 335 =head2 new
 336
 337 Instantiates the Model based on the above-documented ->config parameters.
 338 The only required parameter is C<schema_class>.  C<connect_info> is
 339 required in the case that C<schema_class> does not already have connection
 340 information defined for it.
 341
 342 =head2 schema
 343
 344 Accessor which returns the connected schema being used by the this model.
 345 There are direct shortcuts on the model class itself for
 346 schema->resultset, schema->source, and schema->class.
 347
 348 =head2 composed_schema
 349
 350 Accessor which returns the composed schema, which has no connection info,
 351 which was used in constructing the C<schema> above.  Useful for creating
 352 new connections based on the same schema/model.  There are direct shortcuts
 353 from the model object for composed_schema->clone and composed_schema->connect
 354
 355 =head2 clone
 356
 357 Shortcut for ->composed_schema->clone
 358
 359 =head2 connect
 360
 361 Shortcut for ->composed_schema->connect
 362
 363 =head2 source
 364
 365 Shortcut for ->schema->source
 366
 367 =head2 class
 368
 369 Shortcut for ->schema->class
 370
 371 =head2 resultset
 372
 373 Shortcut for ->schema->resultset
 374
 375 =head2 storage
 376
 377 Provides an accessor for the connected schema's storage object.
 378 Used often for debugging and controlling transactions.
 379
 380 =cut
 381
 382 class_has 'composed_schema' => (is => 'rw', isa => 'DBIx::Class::Schema');
 383
 384 has 'schema' => (is => 'rw', isa => 'DBIx::Class::Schema');
 385
 386 has 'schema_class' => (
 387     is => 'ro',
 388     isa => SchemaClass,
 389     coerce => 1,
 390     required => 1
 391 );
 392
 393 has 'storage_type' => (is => 'rw', isa => Str);
 394
 395 has 'connect_info' => (is => 'ro', isa => ConnectInfo, coerce => 1);
 396
 397 # ref $self changes to anon after roles are applied, and _original_class_name is
 398 # broken in MX::O::P 0.0009
 399 has '_class_name' => (is => 'ro', isa => ClassName, default => sub {
 400     ref shift
 401 });
 402
 403 has 'model_name' => (is => 'ro', isa => Str, default => sub {
 404     my $self = shift;
 405
 406     my $class = ref $self;
 407     (my $model_name = $class) =~ s/^[\w:]+::(?:Model|M):://;
 408
 409     $model_name
 410 });
 411
 412 has 'roles' => (is => 'ro', isa => ArrayRef|Str);
 413
 414 has '_default_cursor_class' => (
 415     is => 'ro',
 416     isa => CursorClass,
 417     default => 'DBIx::Class::Storage::DBI::Cursor',
 418     coerce => 1
 419 );
 420
 421 sub BUILD {
 422     my $self = shift;
 423     my $class = ref $self;
 424     my $schema_class = $self->schema_class;
 425
 426     if( !$self->connect_info ) {
 427         if($schema_class->storage && $schema_class->storage->connect_info) {
 428             $self->connect_info($schema_class->storage->connect_info);
 429         }
 430         else {
 431             die "Either ->config->{connect_info} must be defined for $class"
 432                   . " or $schema_class must have connect info defined on it."
 433                   . " Here's what we got:\n"
 434                   . Dumper($self);
 435         }
 436     }
 437
 438     if (exists $self->connect_info->{cursor_class}) {
 439         eval { Class::MOP::load_class($self->connect_info->{cursor_class}) }
 440             or croak "invalid connect_info: Cannot load your cursor_class"
 441         . " ".$self->connect_info->{cursor_class}.": $@";
 442     }
 443
 444     $self->_plugin_ns('Role');
 445
 446     $self->load_plugins($self->roles->flatten) if $self->roles;
 447
 448     $self->setup;
 449
 450     $self->composed_schema($schema_class->compose_namespace($class));
 451
 452     $self->schema($self->composed_schema->clone);
 453
 454     $self->schema->storage_type($self->storage_type)
 455         if $self->storage_type;
 456
 457     $self->schema->connection($self->connect_info);
 458
 459     $self->_install_rs_models;
 460
 461     $self->finalize;
 462 }
 463
 464 sub clone { shift->composed_schema->clone(@_); }
 465
 466 sub connect { shift->composed_schema->connect(@_); }
 467
 468 sub storage { shift->schema->storage(@_); }
 469
 470 =head2 setup
 471
 472 Called at C<<BUILD>> time before configuration.
 473
 474 =cut
 475
 476 sub setup { 1 }
 477
 478 =head2 finalize
 479
 480 Called at the end of C<BUILD> after everything has been configured.
 481
 482 =cut
 483
 484 sub finalize { 1 }
 485
 486 =head2 ACCEPT_CONTEXT
 487
 488 Point of extension for doing things at C<<$c->model>> time, returns the model
 489 instance, see L<Catalyst::Manual::Intro> for more information.
 490
 491 =cut
 492
 493 sub ACCEPT_CONTEXT { shift }
 494
 495 sub _install_rs_models {
 496     my $self  = shift;
 497     my $class = $self->_class_name;
 498
 499     no strict 'refs';
 500
 501     my @sources = $self->schema->sources;
 502
 503     die "No sources found (did you forget to define your tables?)"
 504         unless @sources;
 505
 506     foreach my $moniker (@sources) {
 507         my $classname = "${class}::$moniker";
 508         *{"${classname}::ACCEPT_CONTEXT"} = sub {
 509             shift;
 510             shift->model($self->model_name)->resultset($moniker);
 511         }
 512     }
 513 }
 514
 515 sub _reset_cursor_class {
 516     my $self = shift;
 517
 518     if ($self->storage->can('cursor_class')) {
 519         $self->storage->cursor_class($self->_default_cursor_class)
 520             if $self->storage->cursor_class ne $self->_default_cursor_class;
 521     }
 522 }
 523
 524 __PACKAGE__->meta->make_immutable;
 525
 526 =head1 SEE ALSO
 527
 528 General Catalyst Stuff:
 529
 530 L<Catalyst::Manual>, L<Catalyst::Test>, L<Catalyst::Request>,
 531 L<Catalyst::Response>, L<Catalyst::Helper>, L<Catalyst>,
 532
 533 Stuff related to DBIC and this Model style:
 534
 535 L<DBIx::Class>, L<DBIx::Class::Schema>,
 536 L<DBIx::Class::Schema::Loader>, L<Catalyst::Helper::Model::DBIC::Schema>,
 537 L<MooseX::Object::Pluggable>
 538
 539 Roles:
 540
 541 L<Catalyst::Model::DBIC::Schema::Role::Caching>,
 542 L<Catalyst::Model::DBIC::Schema::Role::Replicated>
 543
 544 =head1 AUTHOR
 545
 546 Brandon L Black, C<blblack@gmail.com>
 547
 548 Contributors:
 549
 550 Rafael Kitover, C<<rkitover at cpan.org>>
 551
 552 =head1 COPYRIGHT
 553
 554 This program is free software, you can redistribute it and/or modify it
 555 under the same terms as Perl itself.
 556
 557 =cut
 558
 559 1;