view release on metacpan or  search on metacpan

lib/DBI/DBD/SqlEngine/Developers.pod  view on Meta::CPAN

This method usually requires extending in a derived implementation.
See L<DBD::CSV> or L<DBD::DBM> for some example.

=item STORE

Allows storing of statement private attributes. No special handling is
currently implemented here.

=item rows

Returns the number of rows affected by the last execute. This method might
return C<undef>.

=back

=head2 DBI::DBD::SqlEngine::TableSource

Provides data sources and table information on database driver and database
handle level.

  package DBI::DBD::SqlEngine::TableSource;

  sub data_sources ($;$)
  {
    my ( $class, $drh, $attrs ) = @_;
    ...
  }

  sub avail_tables
  {
    my ( $class, $drh ) = @_;
    ...
  }

The C<data_sources> method is called when the user invokes any of the
following:

  @ary = DBI->data_sources($driver);
  @ary = DBI->data_sources($driver, \%attr);
  
  @ary = $dbh->data_sources();
  @ary = $dbh->data_sources(\%attr);

The C<avail_tables> method is called when the user invokes any of the
following:

  @names = $dbh->tables( $catalog, $schema, $table, $type );
  
  $sth = $dbh->table_info( $catalog, $schema, $table, $type );
  $sth = $dbh->table_info( $catalog, $schema, $table, $type, \%attr );

  $dbh->func( "list_tables" );

Every time where an C<\%attr> argument can be specified, this C<\%attr>
object's C<sql_table_source> attribute is preferred over the C<$dbh>
attribute or the driver default.

=head2 DBI::DBD::SqlEngine::DataSource

Provides base functionality for dealing with tables. It is primarily
designed for allowing transparent access to files on disk or already
opened (file-)streams (e.g. for DBD::CSV).

Derived classes shall be restricted to similar functionality, too (e.g.
opening streams from an archive, transparently compress/uncompress
log files before parsing them, 

  package DBI::DBD::SqlEngine::DataSource;

  sub complete_table_name ($$;$)
  {
    my ( $self, $meta, $table, $respect_case ) = @_;
    ...
  }

The method C<complete_table_name> is called when first setting up the
I<meta information> for a table:

  "SELECT user.id, user.name, user.shell FROM user WHERE ..."

results in opening the table C<user>. First step of the table open
process is completing the name. Let's imagine you're having a L<DBD::CSV>
handle with following settings:

  $dbh->{sql_identifier_case} = SQL_IC_LOWER;
  $dbh->{f_ext} = '.lst';
  $dbh->{f_dir} = '/data/web/adrmgr';

Those settings will result in looking for files matching
C<[Uu][Ss][Ee][Rr](\.lst)?$> in C</data/web/adrmgr/>. The scanning of the
directory C</data/web/adrmgr/> and the pattern match check will be done
in C<DBD::File::DataSource::File> by the C<complete_table_name> method.

If you intend to provide other sources of data streams than files, in
addition to provide an appropriate C<complete_table_name> method, a method
to open the resource is required:

  package DBI::DBD::SqlEngine::DataSource;

  sub open_data ($)
  {
    my ( $self, $meta, $attrs, $flags ) = @_;
    ...
  }

After the method C<open_data> has been run successfully, the table's meta
information are in a state which allows the table's data accessor methods
will be able to fetch/store row information. Implementation details heavily
depends on the table implementation, whereby the most famous is surely
L<DBD::File::Table|DBD::File/DBD::File::Table>.

=head2 DBI::DBD::SqlEngine::Statement

Derives from DBI::SQL::Nano::Statement for unified naming when deriving
new drivers. No additional feature is provided from here.

=head2 DBI::DBD::SqlEngine::Table

Derives from DBI::SQL::Nano::Table for unified naming when deriving
new drivers.

You should consult the documentation of C<< SQL::Eval::Table >> (see
L<SQL::Eval>) to get more information about the abstract methods of the
table's base class you have to override and a description of the table
meta information expected by the SQL engines.