view release on metacpan or  search on metacpan

lib/DBIx/DataModel/Doc/Reference.pod  view on Meta::CPAN

will be used later when calling L</sqlize()>, L</prepare()>
and L</execute()>. Admitted parameters are listed under
the L</select()> method.

For most parameters, when C<refine()> is called several times on the
same statement, the latest value takes precedence (like the latest
update in a Perl hash) : this is the case for instance for parameters
C<-columns>, C<-order_by>, etc. However, for the C<-where> parameter,
the statement accumulates all successive conditions, combining them
with an implicit "AND". So for example

   $statement->refine(-where => {col1 => $val1, col2 => {">" => $min}})
             ->refine(-where => {col3 => $val3, col2 => {"<" => $max}});

is equivalent to

   $statement->refine(-where => {col1 => $val1, 
                                 col2 => {">" => $min,
                                          "<" => $max},
                                 col3 => $val3});

Refining a statement can only occur when the statement is still
in status C<NEW> or C<REFINED>; after L</sqlize()> has been called, 
parameters are frozen and no further refinement is allowed.

=head3 sqlize()

  $statement->sqlize(%args);

Generates SQL from all parameters accumulated so far in the statement.
The statement switches from state C<REFINED> to state C<SQLIZED>,
which forbids any further refinement of the statement
(but does not forbid further bindings).

If present, arguments are passed to C<refine()>; so this is just a shortcut
for

  $statement->refine(%args)->sqlize;

=head3 prepare()

  $statement->prepare(%args);

Method C<sqlize> is called automatically if necessary.
Then the SQL is sent to the database, and the statement handle
returned by DBI (C<$sth>)
is stored internally within the statement.
The state switches to C<PREPARED>.

Arguments are optional, and are just a shortcut for

  $statement->sqlize(%args)->prepare;



=head3 execute()

  $statement->execute(@bindings);

Calls the L</bind()> method, calls L<DBI/execute> on the internal C<$sth>, 
and applies the C<-pre_exec> and C<-post_exec> callbacks 
if necessary. The state switches to C<EXECUTED>.

Arguments are optional, and are just a shortcut for

  $statement->bind(@bindings)->execute;

An executed statement can be executed again, possibly with some 
different bindings. When this happens, the internal result set
is reset, and fresh data rows can be retrieved again through 
the L</next> or L</all> methods.


=head3 make_fast()

Builds a reusable hash for data rows. This spares the time for
building a fresh Perl hash for each row; but of course each
new row will overwrite data of the previous row.
See the doc for L</fast_statement> above.


=head3 sql()

  $sql         = $statement->sql;
  (sql, @bind) = $statement->sql;

In scalar context, returns the SQL code for this
statement (or C<undef> if the statement is not
yet C<sqlized>). 

In list context, returns the SQL code followed
by the bind values, suitable for a call to 
L<DBI/execute>.

Obviously, this method is only available after the
statement has been sqlized (through a direct call 
to the L</sqlize> method, or indirect call via
L</prepare>, L</execute> or L</select>).

=head3 headers

  my @headers = $statement->headers;

Implicitly calls L</execute()> if the statement is not already in 
C<EXECUTED> state.
Returns an array of column names as returned from the DBD driver
through C<< $self->sth->{FetchHashKeyName} >>.
See the L<DBI> documentation for details.


=head3 bind()

  $statement->bind(foo => 123, bar => 456);
  $statement->bind({foo => 123, bar => 456}); # equivalent to above

  $statement->bind(0 => 123, 1 => 456);
  $statement->bind([123, 456]);               # equivalent to above

Takes a list of bindings (name-value pairs), and associates them to
L<"named placeholders"|DBIx::DataModel::Doc::Glossary/placeholder>
within the statement. Named placeholders are defined at the