=encoding ISO8859-1

=head1 NAME

DBIx::DataModel::Doc::Internals - Description of the internal structure


=head1 DOCUMENTATION CONTEXT

This chapter is part of the C<DBIx::DataModel> manual.


=over

=item * 

L<SYNOPSIS AND DESCRIPTION|DBIx::DataModel>

=item * 

L<DESIGN|DBIx::DataModel::Doc::Design>

=item * 

L<QUICKSTART|DBIx::DataModel::Doc::Quickstart>

=item *

L<REFERENCE|DBIx::DataModel::Doc::Reference>

=item *

L<MISC|DBIx::DataModel::Doc::Misc>

=item *

INTERNALS

=item *

L<GLOSSARY|DBIx::DataModel::Doc::Glossary>

=back


This chapter documents some details that normally should not be
relevant to clients; you only want to read about them if you
intend to extend the framework.



=head1 PRIVATE METHODS


=head2 _rawInsert

  my $sth = $obj->_rawInsert(%args);

Internal implementation for insertions into the database :
takes keys and values within C<%$obj>, generates SQL for 
insertion of those values into C<< $obj->db_from() >>,
and executes it. Never called directly, but used by the protected method
L</"_singleInsert">.

The optional C<%args> argument can pass additional options
to L<SQL::Abstract::More/insert>; currently only one option is 
available : C<-returning>.

The method returns the statement handle just created, in case the caller
would need to retrieve some values after the insert : for example when
using a RETURNING clause in PostgreSQL, the values can be obtained through
a subsequent call to C<< $sth->fetch >>.


=head1 "PROTECTED" METHODS

=head2 _singleInsert

  $obj->_singleInsert(%options);

Implementation for inserting a record into the
database; should never be called directly, but is used as 
a backend by the 
L<insert|DBIx::DataModel::Doc::Reference/"insert()">
method. 

This method receives an object blessed into some table class; the
object hash should only contain keys and values to be directly
inserted into the database, i.e. the C<no_update_columns> and all
references to foreign objects should have been removed (
normally the
L<insert|DBIx::DataModel::Doc::Reference/"insert">
method has already done that job).  
The C<_singleInsert> method calls L</"_rawInsert">
for performing the database update, and then makes
sure that the object contains its own key, calling
DBI's L<last_insert_id()|DBI/last_insert_id> if necessary,
as explained in the L<insert|DBIx::DataModel::Doc::Reference/"insert()">
documentation.

You may redeclare C<_singleInsert> in your own table classes,
for example if you need to compute a key by other means, like
constructing it from other fields, or generating it from
a random number. 

The return value from C<_singleInsert> depends on C<%options> :

=over

=item *

if C<< $options{-returning} >> is a scalar or arrayref,
that option is passed to C<_rowInsert>,  then 
to L<SQL::Abstract/insert> and finally to the SQL level 
(INSERT ... RETURNING ...);  whatever is returned from the 
database gets transmitted back to the caller.

=item *

if C<< $options{-returning} >> is a hashref, the 
return value is also a hashref, containing the column
name(s) and value(s) of the primary key for that record

=item *

if C<< $options{-returning} >> is absent, the
return value is the list of values of the primary key
for that record.

=back