=head1 NAME

DBIx::DataModel::Doc::Delta_v2 - Differences introduced in version 2.0

=head1 DESCRIPTION

The architecture and Application Programming Interface (API)
of C<DBIx::DataModel> were deeply
refactored in version 2.0. This document enumerates the main 
differences introduced in that version.
For older changes, see also L<DBIx::DataModel::Doc::Delta_v1>.

=head1 NEW META LAYER

All information about the schema is stored within meta-objects;
such objects can be queried for retrieving 
the list of tables, the list of associations, etc.

=head1 SCHEMA MODES

The C<$dbh> database connection, and various parameters about
SQL generation, are no longer stored within the Schema B<class>; 
instead, they are stored in B<instances> of
L<DBIx::DataModel::Schema>. By default, there is only one such instance,
and the class has a C<singleton()> method for reaching it : this is called
I<single-schema mode>, which is compatible with previous versions
of C<DBIx::DataModel>, and is also the most economical way to work with the 
database. 

Even in single-schema mode, it is possible to switch between several 
C<$dbh>, through methods L<DBIx::DataModel::Schema/localize_state> 
and L<DBIx::DataModel::Schema/do_transaction>. However, 
there is of course only one connected C<$dbh> at any point in time.

If the application needs to communicate with several C<$dbh> at the same
time, then it is necessary to enter I<multi-schema> mode,
simply by explicitly calling the L<DBIx::DataModel::Schema/new> method
on the schema subclass :

  my $schema1 = My::DB->new(dbh => $dbh1);
  my $schema2 = My::DB->new(dbh => $dbh2);

As soon as the C<new()> method is called, the system knows that 
it should work in multi-schema mode, and the C<singleton()> method
becomes prohibited. As a consequence, calls to C<fetch()> or C<select()>
can no longer be invoked on a class name: the schema needs to be specified 

  # this does NOT work in multi-schema mode
  my $rows = My::DB::SomeTable->select(...)
  
  # but this does work
  my $rows = $schema1->table('SomeTable')->select(...)

Another consequence of multi-schema mode is that every data row
will contain a reference to its schema, under name C<__schema>.
This is necessary if we want to be able to follow paths from that row :

  my $other_row = $row->some_associated_table();

Therefore there is a small penalty for multi-schema mode, because
the C<__schema> in every row needs some memory and some bookkeeping.

=head1 API CHANGES

=head2 Deprecation of camelCase methods

All methods and parameters previously written in "camelCase" notation
(à la Java, i.e "someMethodNameWithManyWords") are now
written with underscores (à la Perl, i.e. "some_method_name_with_many_words").

=head2 SQL::Abstract::More

Code that used to be with C<DBIx_:DataModel>, for extending 
the L<SQL::Abstract> API, and tuning SQL generation, is now 
moved to a separate distribution called L<SQL::Abstract::More>.

=head2 Introduction of Params::Validate

Arguments to methods are now systematically checked
through L<Params::Validate>.
This is in accordance with the principle of "defensive programming", 
and helps to discover errors sooner.

=head2 Extended usage for C<update()> and C<delete()>

It is now possible to perform bulk updates or deletes, just like in 
straigt SQL :

  My::DB::SomeTable->update(-set   => {foo => 123}
                            -where => {bar => {"<" => 456}});

  My::DB::SomeTable->delete(-where => {col => {-like => "foobar%"});


=head2 Table inheritance

If your database supports table inheritance (like for example PostgreSQL),
you might define a corresponding inheritance structure
between the Perl table classes.

=head2 Reorganization of data sources

The former class C<DBIx::DataModel::View> is deprecated; it is now
treated exactly like a C<Table>.

A new L<DBIx::DataModel::Source::Join> class has been introduced 
(together with its meta L<DBIx::DataModel::Meta::Source::Join>) :
this gives a cleaner structure for the specific needs of database joins.

=head1 DEPRECATED FEATURES

=head2 Autoload

Autoload is deprecated. Reading or setting a column value
is done through the usual Perl operations for working with
hashrefs.