DBIx::DataModel::Doc::Internals(3p)

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

DOCUMENTATION CONTEXT
This chapter is part of the "DBIx::DataModel" manual.

•   SYNOPSIS AND DESCRIPTION

•   DESIGN

•   QUICKSTART

•   REFERENCE

•   COOKBOOK

•   INTERNALS

•   GLOSSARY

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.

PRIVATE METHODS

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

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

The optional %args argument can pass additional options to "insert" in SQL::Abstract::More; currently only one option is available : "-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 "$sth->fetch".

"PROTECTED" METHODS

  _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 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 "no_update_columns" and all references to foreign objects should have been removed ( normally the insert method has already done that job). The "_singleInsert" method calls "_rawInsert" for performing the database update, and then makes sure that the object contains its own key, calling DBI's last_insert_id() if necessary, as explained in the insert documentation.

You may redeclare "_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 "_singleInsert" depends on %options :

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

•   if $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

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