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