view release on metacpan or  search on metacpan

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

=item * B<table_info / column_info> -
Return data in the same key-naming convention as DBI
(C<TABLE_NAME>, C<TABLE_TYPE>, C<COLUMN_NAME>, C<DATA_TYPE>,
C<ORDINAL_POSITION>, C<IS_NULLABLE>, C<COLUMN_DEF>).

=item * B<ping> - Returns 1 when active, 0 after disconnect.

=back

=head2 Not Compatible (differs from or absent in DBI)

=over 4

=item * B<No DBI DSN format> -
DBI uses C<"dbi:Driver:param=val"> DSNs.  DB::Handy uses a plain directory
path or the proprietary C<"base_dir=DIR;database=DB"> mini-DSN.
C<dbi:Handy:...> strings are B<not> recognised.

=item * B<No transaction support> -
DB::Handy B<always operates in AutoCommit mode>; there is no way to
group statements into an atomic transaction.  C<begin_work>, C<commit>,
and C<rollback> are implemented but always return C<undef> and set
C<errstr>.  C<AutoCommit> always returns C<1>.

=item * B<Column order> -
DB::Handy preserves column order for named SELECT lists (including
C<AS> aliases), C<SELECT *> (uses CREATE TABLE order), and
JOIN with C<SELECT *> (table appearance order, each in CREATE order).
Compatible with DBI.

=item * B<RaiseError / PrintError are standalone> -
In DBI, C<RaiseError> and C<PrintError> are handled by the DBI framework
itself.  In DB::Handy they are implemented by the connection-handle code
only and may not fire in every error path that DBI would cover.

=item * B<No type_info / type_info_all> -
DBI provides C<type_info> and C<type_info_all> to query data-type
capabilities.  These methods are not implemented.

=item * B<No statement-level attributes beyond NAME/NUM_OF_FIELDS> -
DBI statement handles expose many attributes (C<TYPE>, C<PRECISION>,
C<SCALE>, C<NULLABLE>, C<CursorName>, etc.).  DB::Handy only supports
C<NAME> and C<NUM_OF_FIELDS>.

=item * B<last_insert_id semantics> -
C<last_insert_id> accepts the same four positional arguments as DBI
(C<$catalog>, C<$schema>, C<$table>, C<$field>) but ignores them.
It returns the row count of the most recent INSERT (always 1 for a
single-row insert).  Compatible with DBI.

=item * B<No BLOB / CLOB types> -
DBI supports large-object binding via special type constants.  DB::Handy
has no BLOB/CLOB storage; VARCHAR is capped at 255 bytes.

=item * B<No database-handle cloning or fork safety> -
DBI provides C<clone> and handles C<fork> safely.  DB::Handy does not
implement C<clone> and makes no special provision for forked processes.

=item * B<No HandleError callback> -
DBI supports the C<HandleError> attribute for custom error callbacks.
DB::Handy does not implement C<HandleError>.

=back

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

A connection handle is returned by C<connect>.  It is an instance of
C<DB::Handy::Connection> and provides a DBI-like interface for executing
SQL and fetching results.

=head2 connect( $dsn, $database [, \%opts] )

  # Positional arguments
  my $dbh = DB::Handy->connect('./data', 'mydb');

  # DSN string
  my $dbh = DB::Handy->connect('base_dir=./data;database=mydb');

  # With options
  my $dbh = DB::Handy->connect('./data', 'mydb', {
      RaiseError => 1,
      PrintError => 0,
  });

Creates and returns a connection handle (C<DB::Handy::Connection>).

The first argument (C<$dsn>) is one of:

=over 4

=item * A plain directory path used as the base storage directory.

=item * A C<dbi:Handy:key=val;...> DSN string (C<dbi:Handy:> prefix
is stripped before parsing).

=item * A bare C<key=val;...> parameter string (no prefix).

=back

Recognised DSN keys: C<base_dir> (alias C<dir>) and C<database>
(alias C<db>).  See L</"dbi:Handy DSN"> in DIFFERENCES FROM DBI for
a full parameter table.

C<$database> is the logical name of the database.  The corresponding
directory (C<$dsn/$database/>) is B<created automatically> if it does
not exist.  To avoid automatic creation, pass C<< AutoUse => 0 >> in the
options hash.

B<Options:>

=over 4

=item C<RaiseError =E<gt> 1>

Die (C<die>) on any error.  Default: 0.  Compatible with DBI.

=item C<PrintError =E<gt> 1>

Warn (C<warn>) on any error.  Default: 0.  Compatible with DBI.