
=head1 NAME

SQL::DB::Schema - Table and column definitions for SQL::DB

=head1 VERSION

0.971.0. Development release.

=head1 SYNOPSIS

    use SQL::DB::Schema;

    my $schema = SQL::DB::Schema->new( name => 'myschema' );

    $schema->define(@table_1_definition);
    $schema->define(@table_2_definition);
    $schema->define(@table_3_definition);
    # ...
    $schema->define(@table_N_definition);
    
    my ($itable_1, $itable_3) = $schema->irows(qw/table_1, table_3/)
    my ($utable_1, $utable_3) = $schema->urows(qw/table_1, table_3/)
    my ($stable_1, $stable_2) = $schema->srows(qw/table_1, table_2/)


=head1 DESCRIPTION

B<SQL::DB::Schema> objects hold the table and column definitions used
by L<SQL::DB> for creating SQL queries.

The SYNOPSIS and this documentation show how this module is used but
you should never write such code by hand.  Schema information is either
automatically retrieved by L<SQL::DB> at run-time or pre-generated
using C<deployed_table_info()> from L<SQL::DBx::Deploy>.

=head1 CONSTRUCTOR

=over 4

=item new( name => $name ) -> SQL::DB::Schema

Create a new schema object with the following parameters:

=over

=item name

The name of the schema. The name is required and should be unique.

=back

=back

=head1 ATTRIBUTES

=over 4

=item name

The name of the schema as given to the constructor.

=item package_root

The name prefix for internally generated classes.

=back

=head1 METHODS

=over 4

=item define( \@column_info )

Add table/column information to the schema. The \@column_info
array-reference must be the same as the structure returned from a
L<DBI> "column_info()" call. This method will confess if duplicate
column information is given.

=item not_known(@tables) -> @not_known

Returns the @tables which are not known in the schema.

=item irows( $table, [ $table2 ] ) -> @CODErefs

Returns coderefs representing $table(s). Each coderef called with
column names returns a string suitable for an INSERT operation.  These
coderefs can be used in L<SQL::DB>'s "do()" method (for INSERT
queries). Raises an exception if a non-existing table is requested.

=item urows( $table, [ $table2 ] ) -> @SQL::DB::Expr

Returns objects representing abstract rows from $table(s). Each object
has a method for each column in the table. These urow objects can be
used in L<SQL::DB>'s "do()" method (UPDATE or DELETE queries). Raises
an exception if a non-existing table is requested.

=item srows( $table, [ $table2 ] ) -> @SQL::DB::Expr

Returns objects representing abstract rows from $table(s). Each object
has a method for each column in the table. These srow objects can be
used in L<SQL::DB> "fetch()" and "fetch1()" methods (for SELECT
queries). Raises an exception if a non-existing table is requested.

=back

=head1 SEE ALSO

L<SQL::DBx::Deploy>

=head1 AUTHOR

Mark Lawrence E<lt>nomad@null.netE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright 2007-2011 Mark Lawrence <nomad@null.net>

This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 3 of the License, or (at your
option) any later version.

