view release on metacpan or  search on metacpan

lib/DB/Handy.pm  view on Meta::CPAN

Return a SQL string literal suitable for direct interpolation into a SQL
statement.  Single-quote the value and double any embedded single-quote
characters.  Return the unquoted string C<NULL> for C<undef>.

B<Note:> Numeric values are also quoted as strings (C<"'42'">), unlike
some DBI drivers that pass integers through unquoted.  Prefer C<?>
placeholders over C<quote> wherever possible.

Compatible with DBI (default C<quote> behaviour).

=head2 last_insert_id()

  $dbh->do("INSERT INTO emp (id,name) VALUES (?,?)", 4, 'Dave');
  my $n = $dbh->last_insert_id;   # 1 (one row was inserted)

Return the row count of the most recent INSERT statement.  This is always
1 on a successful single-row INSERT, or the total count for a bulk
C<INSERT ... SELECT>.

C<last_insert_id> accepts the same four positional arguments as DBI
(C<$catalog, $schema, $table, $field>) but ignores them; only the
connection object is used.  Compatible with DBI.

=head2 disconnect()

  $dbh->disconnect;

Mark the connection as closed.  Subsequent calls to C<do>, C<prepare>,
etc. will fail.  Always returns 1.

In DBI, C<disconnect> may flush uncommitted transactions; DB::Handy has
no transactions, so C<disconnect> is a no-op beyond setting the
disconnected flag.  Compatible with DBI.

=head2 errstr()

  my $msg = $dbh->errstr;

Return the error message from the most recent failed operation on this
handle, or the empty string if there was no error.

Like DBI, DB::Handy resets C<errstr> and C<err> when a statement is
prepared or executed, so a message left over from an earlier failure is
never mistaken for the outcome of a call that has just succeeded.

The package-level variable C<$DB::Handy::errstr> holds the last error
from any handle, analogous to C<$DBI::errstr>.  It is not reset.
Compatible with DBI.

=head2 err()

  my $code = $dbh->err;

Return the error code from the most recent failed operation (always 1 for
any error, 0 for no error).  Reset together with C<errstr>.
Analogous to C<$DBI::err>.
Compatible with DBI.

=head2 ping()

  my $alive = $dbh->ping;

Return true while the handle is usable, false after C<disconnect>.  There
is no server to reach, so this reports the handle's own state.
Compatible with DBI.

=head2 AutoCommit()

  my $ac = $dbh->AutoCommit;   # always 1

Always returns C<1>.  This method, not the C<< $dbh->{AutoCommit} >> hash
key, is the authoritative answer; see L</ATTRIBUTES>.

=head2 begin_work() / commit() / rollback()

  $dbh->begin_work or die $dbh->errstr;

All three always fail: they return C<undef> and set C<errstr> to explain
that DB::Handy has no transactions.  They exist so that ported DBI code
fails visibly instead of appearing to open a transaction.  Connecting with
C<AutoCommit =E<gt> 0> is refused for the same reason.

=head2 table_info()

  my $rows = $dbh->table_info;
  for my $t (@$rows) { print "$t->{TABLE_NAME}\n" }

Return an array reference of hash references, one per table in the current
database.  B<Not compatible with DBI>, in two ways: DBI's C<table_info>
takes four positional arguments (C<$catalog>, C<$schema>, C<$table>,
C<$type>) and returns a statement handle, whereas this method takes no
arguments and returns the rows directly.  The hash keys follow DBI's
naming (C<TABLE_CAT>, C<TABLE_SCHEM>, C<TABLE_NAME>, C<TABLE_TYPE>,
C<REMARKS>).

=head2 column_info( $table )

  my $rows = $dbh->column_info('emp');
  for my $c (@$rows) { print "$c->{COLUMN_NAME} $c->{TYPE_NAME}\n" }

Return an array reference of hash references, one per column of C<$table>,
in declaration order.  B<Not compatible with DBI>: DBI's C<column_info>
takes C<$catalog>, C<$schema>, C<$table>, C<$column> and returns a
statement handle; this method takes B<the table name as its only
argument> and returns the rows directly.  Calling it with DBI's four
arguments passes C<undef> as the table name and returns C<undef>.

The hash keys follow DBI's naming (C<TABLE_CAT>, C<TABLE_SCHEM>,
C<TABLE_NAME>, C<COLUMN_NAME>, C<DATA_TYPE>, C<TYPE_NAME>,
C<COLUMN_SIZE>, C<ORDINAL_POSITION>, C<IS_NULLABLE>, C<COLUMN_DEF>).

=head1 METHODS - Statement handle (DB::Handy::Statement)

A statement handle is created by C<< $dbh->prepare($sql) >>.  It is an
instance of C<DB::Handy::Statement>.

=head2 execute( [@bind_values] )

  $sth->execute;                   # no placeholders
  $sth->execute(42, 'Alice');      # substitute two ? placeholders