NAME

Class::PObject::Driver::DBI - Base class for all DBI-related drivers

SYNOPSIS

    package Class::PObject::YourDriver;
    use Class::PObject::Driver::DBI;
    @ISA = ('Class::PObject::Driver::DBI');

    sub save {
        my ($self, $pobject_name, \%properties, \%columns) = @_;
        ...
    }

    sub dbh {
        my ($self, $pobject_name, \%properties) = @_;
        ...
    }

ABSTRACT

    Class::PObject::Driver::DBI is a subclass of Class::PObject::Driver.
    Provides all the necessary base methods/utilities for writing
    DBI-related pobject drivers.

STOP!

If you just want to be able to use Class::PObject this manual is not for you. This is for those willing to write pobject drivers to support other database systems and storage devices.

If you just want to be able to use Class::PObject, you should refer to its manual instead.

DESCRIPTION

Class::PObject::Driver::DBI is a direct subclass of Class::PObject::Driver and overrides the methods provided in Class::PObject::Driver with those more relevant to RDBMS engines.

It uses ANSI-SQL syntax, so most of the base methods should perform as expected for most RDBMS that support ANSI-SQL syntax.

For those that don't, you can override necessary methods from within your driver class. This manual will not discuss the list of base methods, for they all are documented in Class::PObject::Driver. Please refer to the manual for gory details.

REQUIRED METHODS

Once your driver inherits from Class::PObject::Driver::DBI, most of the base methods, such as load(), remove(), remove_all(), count() will already be defined for you, so you may not even have to defined those methods.

The only methods required to be defined are save() and dbh(). For details on save() method, refer to Class::PObject::Driver.

• dbh($self, $pobject_name, \%properties) - will be called by other base methods whenever a database handle is needed. It receives all the standard arguments (see Class::PObject::Driver)

  If your project consists of several pobjects, which is very common, you may want to stash() the created database handle to ensure Class::PObject will be able to re-use the same object over instead of having to establish connection each time. This can get too costly too soon.

OTHER METHODS

The list of all other standard driver methods can be found in Class::PObject::Driver.

Class::PObject::Driver::DBI also provides following private/utility methods that are called by other driver methods to create SQL statements and/or clauses.

You may override these methods to affect the creation of SQL statements for your specific database instead of having to re-define the standard driver methods.

All the methods prefixed with _prepare_ string return an array of two elements. First is the $sql, which holds the relevant ANSI-SQL statement with possible placeholders, and second is \@bind_params, which holds the list of all the values for the place holders in the $sql.

• _prepare_where_clause($self, \%terms) - prepares a WHERE SQL clause. This method is primarily called from within _prepare_select(), _prepare_update(), _prepare_delete() and count() methods.

  Example:

      my ($sql, $bind_params) = $self->_prepare_where_clause({name=>'sherzod', is_admin=>'1'});
  
      # $sql is "WHERE name=?" AND is_admin=>?
      # $bind_params is ['sherzod', 1]

• _prepare_select($self, $table_name, \%terms, \%args, \@cols) - prepares a SELECT SQL statement, given $table_name, \%terms and \%args and \@cols.

  Example:

      my ($sql, $bind_params) = $self->_prepare_select('authors', {is_admin =>1},
                                                                  {limit  => 10,
                                                                   offset => 0,
                                                                   sort   => 'name',
                                                                   direction=>'asc'});

  $sql will hold

      SELECT * FROM authors WHERE is_admin = ?
          ORDER BY name ASC LIMIT 0, 10

  $bind_params will hold [1]

  If your particular database engine requires a slightly different SELECT syntax, you can override this method from within your class.

• _prepare_update($self, $table_name, \%columns, \%terms) is similar to _prepare_select(), but builds an UPDATE SQL statement

• _prepare_insert($self, $table_name, \%columns) builds an INSERT SQL statement

• _prepare_delete($self, $table_name, \%terms) builds a DELETE SQL statement

• _prepare_create_table($self, $object_name, $table_name) builds a CREATE TABLE SQL statement. This can be used from within pobject drivers for creating a table if it's detected to be missing.

  Unlike other _prepare_* methods, this method returns only one value on success, $sql, which is a string containing SQL statement.

• _tablename($self, $pobject_name, $props, $dbh) returns a name of the table this particular object should belong to. If pobject declarations's datasource attribute already defined Table name, this will be returned. Otherwise it will recover the table name from the $pobject_name.

  Usually _tablename() doesn't need to be overridden, because by default it does the right thing. You can override it, for example, if you want all of your tables to have a specific prefix regardless of the $pobject_name or even $datasource->{Table}.

  Most of the base methods call _tablename() to get the name of the table to include it into SQL statements.

SEE ALSO

Class::PObject::Driver

COPYRIGHT AND LICENSE

For author and copyright information refer to Class::PObject's online manual.