Added commands and API sketch

[dbsrgits/dbic-future.git] / lib / DBIx / Class / Manual / Specification.pm

=head1 NAME

DBIx::Class::Manual::Specification

=head1 SYNOPSIS

This discusses the specification for DBIx::Class v0.09. Along with discussing
new features, it will also include proper specification for features that exist
in the DBIx::Class 0.08 versions that will be supported in DBIx::Class 0.09.
Where appropriate, it will also discuss specifications for Data::Query and any
other modules/distributions.

=head1 MOTIVATIONS

DBIx::Class has become one of, if not the, premier ORMs in the Perl community.
However, its featureset has grown organically. As such, some features that were
considered a good idea at one time proved to be implemented in such a way that
prevented proper implementation of other features down the road. Examples
include prefetching and searching.

This document means to provide a solid foundation for future development so as
to prevent painting the distribution into a corner for features that have not
been conceived of at this time.

=head1 GOALS

This specification will be driven by the following design goals.

=head2 Database-agnostic usage

One of the biggest selling points of an ORM is that a programmer should be able
to change the relational database used to back a given application without
having to change anything but configuration. And, to a point, this works
relatively well. Until it doesn't. DBIx::Class 0.09 will change that.

=head2 Database-specific optimization

As it turns out, the drive to be database-agnostic, makes it very hard to
optimize for a given specific database's strengths. In order to support as many
databases, the SQL generated generally ends up being at the lowest common
denominator. This gives ORMs a bad name where performance is concerned. But, it
doesn't have to be that way and DBIx::Class 0.09 will demonstrate how.

=head2 Datastore-agnostic usage

Data doesn't just live in relational databases anymore. There are many reasons,
for this, the primary one being that the relational model doesn't necessarily
reflect the structure of certain data models. But, there are many times when
relational calculus represents the proper way of manipulating that data. Or,
more commonly, a given relational query needs to merge data from relational and
non-relational sources. DBIx::Class, along with Data::Query, will provide a
single API for manipulating data in a relational fashion, regardless of whether
that manipulation is in a datastore, within Perl, or both.

=head2 Intuitive API

Every API has unavoidable gribbly bits. This falls out of the fact that the
problemspace a given API solves can never be fully mapped to it (an extension
of Godel's Incompleteness Theorem). However, like Perl itself, the API should be
organized and optimized so that the user only needs to know a minimum of the
API's functionality in order to accomplish the most common tasks. Furthermore,
that minimum should be easily discoverable in simple synopses and examples.

=head2 Extensible API and backend

Without breaking or, in as many cases as possible I<knowing>, existing backend
implementation details, the functionality of DBIx::Class should be extensible.
Both the API (new contact points) and backend (new datastores, etc) should be
extended knowing a simple API for doing so. This implies that as many pieces as
possible of the backend functionality should be overridable separate from every
other piece.

=head1 RESTRICTIONS

Fill this part in.

=head1 RELATIONAL THEORY

(B<Author's note:> To understand the fundamental underpinnings of DBIx::Class
0.09's choice of features, it is necessary to have a common understanding of
relational theory. I recommend that everyone at least read this section once in
order to be familiar with the terms I use throughout this document.)

Relational theory (calculus or algebra - the difference is esoteric) is, at its
roots, all about set theory and set manipulations. Each row in a table (or
tuple) is an element of a set. The various clause (or operations) in a SQL
statement can be viewed as set manipulators that take one or more sets of tuples
as input and provide a set of tuples as output.

A SQL statement has many clauses and they are evaluated in a very specific order
that is different from the order they are presented. (As mutations share all of
their clauses with queries and evaluate in the same order, only queries will be
discussed here.) The order of evaluation for a SELECT statement is:

=over 4

=item * FROM (with JOINs evaluated in left-to-right order)

=item * WHERE (with AND/OR evaluated in left-to-right order within each
parenthetical block)

=item * GROUP BY

=item * SELECT

=item * HAVING

=item * ORDER BY

=back

(Expand here.)

=head1 FEATURES

=head2 Basic Features

An ORM must provide some very basic features. They are, in essence, the ability
to:

=over 4

=item * Retrieve data from a relational database (a.k.a., select)

=item * Insert, update, and delete in that relational database (a.k.a., mutate)

=back

These functions are generally achieved by providing some API to the SELECT
statement that returns a collection of objects. These objects then allow for
updating and deleting. The same API that allows for SELECT also, generally, will
allow for creation and, possibly, deletion. Most ORMs do this modelling by
mapping a class to a table and an instance of that class to a given row in that
table. 

DBIx::Class takes a different approach entirely. Instead of treating the row as
the atomic unit, DBIx::Class 09 will treat the column as the atomic unit. This
opens up several possibilities:

=over 4

=item * The definition of a table fall out naturally as a collection of columns

=item * Defining custom searches is a matter of creating a collection of columns on the fly.

=item * Validating values is easily handled regardless of where the column is used.

=item * Enumeration tables can be hidden behind a column definition, allowing optimization to ENUM as appropriate.

=back

=head3 Sources

A source, at its simplest, is the representation of a single table in a
relational database. For example, the table `artists`. But, a source can be
much more than that. Within a relational database, "`artists JOIN cds`" forms a
source containing the columns of both `artists` and `cds`. Taken to the logical
extreme, the FROM clause of a query forms a single source. A subquery can also
be viewed as a source. (In fact, any table or join can be viewed as the subquery
"(SELECT * FROM table) AS table".)

Under the hood, a source acts as a collection of column definitions. When a
source feeds into 

=head3 Resultsets (RENAME ME)

The resultset is arguably the single most important breakthrough in DBIx::Class.
It allows for the gradual building of a SQL statement and reuse of that building
for more than just SELECT statements. In addition to being able to separate
responsibilites by letting different pieces of an application (such as security)
decorate the resultset appropriately, a resultset can also be reused for various
needs. The same resultset can be used for a query, a mass update, a mass delete,
or anything else.

Under the hood, a resultset has a representation for each SQL clause. Each usage
of the resultset will take the clauses that make sense for that usage and leave
the others.

(Expand here, detailing each usage of a resultset and the clauses that each
uses.)

=head3 Objects (aka, Rows)

Traditionally, there is row object is acts as a hashref representing a row in a
table. This representation is simple to implement, meets the 80/20 case, and is
completely wrong. It fails when dealing with GROUP BY clauses, custom queries,
and is generally inflexible.

DBIx::Class 09 chooses instead to model a row as an object that is a collection
of columns that contain values. This means that the object is defined by the
resultset that generates the stream the object comes from. In the standard case,
the resultset's store is a single table and all columns are selected, acting the
same way as a DBIx::Class 08 row object would.

=head2 Queries as streams

A grouping of data can be viewed as either a collection or a stream. The main
difference is that a collection is eager and a stream is lazy. For large
datasets, collections can be very expensive in terms of memory and time (filling
that memory). Streams, on the other hand, defer loading anything into memory
until the last possible moment, but are easily convertible into a collection as
needed. (q.v. Higher Order Perl for more information.)

=head1 EXAMPLES

  subtype Year as Num where { $_ > 0 && $_ <= 9999 };

  table Artist {
      column artist_id => ( isa => 'Num', auto_increment => 1, primary_key => 1 );
      column name => ( isa => 'String', max_length => 50, nullable => 0 );
      column rank => ( isa => 'Num', default => 13 );

      has_many 'CD';

      table 'artists';
  }

  table CD {
      column cdid => ( isa => 'Num', auto_increment => 1, primary_key => 1 );
      column artist => ( isa => 'Num' );
      column title => ( isa => 'String', max_length => 100 );
      column year => ( isa => 'Year' );

      belongs_to 'Artist';

      table 'cds';
  }

  # The following four searches are equivalent:
  my @artists = $schema->table('Artist')->search({
      name => 'Bon Jovi',
  })->all;

  my @artists = $schema->search({
      name => 'Bon Jovi',
  }, {
      from => 'Artist',
  });

  # If a class and table name would conflict and they don't refer to the same
  # thing, a compile-time error is thrown.
  my @artists = $schema->search({
      'Artist.name' => 'Bon Jovi',
  });

  my @artists = $schema->search({
      'artists.name' => 'Bon Jovi',
  });

  # The following searches are equivalent. Results will contain objects that
  # respond to artist_name(), cd_name(), and year() and nothing else.
  my @results = $schema->search({
      'Artist.name' => [ 'Bon Jovi', 'Metallica' ],
      'CD.year'     => [ '2004', '2006' ],
  }, {
      select => [
          [ 'Artist.name' => 'artist_name' ],
          [ 'CD.name' => 'cd_name' ],
          'CD.year',
      ],
  });

  # Artist is the default table here.
  my @results = $schema->table('Artist')->search({
      'name'    => [ 'Bon Jovi', 'Metallica' ],
      'CD.year' => [ '2004', '2006' ],
  }, {
      select => [
          [ 'name' => 'artist_name' ],
          [ 'CD.name' => 'cd_name' ],
          'CD.year',
      ],
  });

  # CD is the default table here.
  my @results = $schema->table('CD')->search({
      'Artist.name'    => [ 'Bon Jovi', 'Metallica' ],
      'year' => [ '2004', '2006' ],
  }, {
      select => [
          [ 'Artist.name' => 'artist_name' ],
          [ 'name' => 'cd_name' ],
          'year',
      ],
  });

  # Note that joins are intuited through the existence of the relationships.

=head1 TODO

=over 4

=item * L</RESTRICTIONS> section needs to be filled in.

=back

=head1 AUTHOR(S)

robkinyon: Rob Kinyon C<< <rkinyon@cpan.org> >>

=head1 LICENSE

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

=cut