PerlDoc

See PublishedAPI for packages intended to be used by Plugin and Contrib authors, or browse all packages.
See also Developing plugins, Developer's Bible, Technical Overview

Perl Module:

---

Parent package: Foswiki::DBI
Child packages:

More ...Less ...

internal package Foswiki::DBI::Database

abstract class for any type of database connecting to foswiki

ClassMethod new()

Constructs a Foswiki::DBI::Database object. This class is mostly subclassed by the acutal database implementation being configured, such as Foswiki::DBI::Database::MariaDB. Subclasses need to specify the actual DBD driver to connect to the database.

ObjectMethod getClassName() → $string

Returns the base name of this database representing the current implementation, such as MariaDB

ObjectMethod applySchema($schema)

Applies the Schema to the connected database. this is called only once when the database is connected. note that the schema must test for existing tables and indexes on its own.

ObjectMethod schemaVersion($type, $version) → $version

getter/setter for the schema version meta data

ObjectMethod replace($table, $primaryKey, $params) → $res

performs an "REPLACE INTO ..." statement. This may be implemented differently in different databases. E.g. MySQL/MariaDB and PostgreSQL do this differently.

$params is a hash of the form:

{
  colname1 => $val1,
  colname2 => $val2,
...
  colnameN => $valN,
}

Describing the columns to be replaced

The $primaryKey parameter specifies the column name that will constraint the insert operation. This is required for PostgreSQL, but not for other database engines.

ObjectMethod handler() → $dbh

Returns the DBD handler that this class is delegating all work to

ObjectMethod connect()

Connects to the database if not already done so and returns a DBI::db handler. this method is called automatically when the db handler is established

ObjectMethod finish()

Called solely by Foswikik::DBI::finish() to finalize the database connection and close any open sockets.

ObjectMethod eachRow($tableName, %params) → $iterator

Returns an object of class Foswiki::Iterator::DBIterator for the given parameters. This is a convenience wrapper for

my $it = Foswiki::Iterator::DBIterator->new($dbh, $stm);

The statement handler is created based on the parameters provided. The %params parameter is a hash with the following values:

• columns: list of columns to return, defaults to "*"
• min: column to compute the minimum for
• max: column to compute the maximum for
• avg: column to compute an average for
• sum: column to compute the sum for
• having: "HAVING" clause SQL statement
• groupBy: groupBy "GROUP BY" clause
• sort, orderBy: "SORT" clause
• filter: "WHERE" clause
• groupConcat: "GROUP_CONCAT(DISTINCT ...)" clause
• count: if defined adds a "COUNT(*) clause, if count is prefixed with "unique" will add a "COUNT(DISTINCT ...)"
• <colName>: <colVal> ... will add a "colName1='colVal1'" to the "WHERE" clause

Note that all parameters except $tableName are optional.

Example:

my $it = Foswiki::DBI::getDB->eachRow("SomeTable", 
  count => "*"
  firstName => "Michael"
);

while ($it->hasNext) {
  my $row = $it->next();

  my $firstName = $row->{firstName};
  my $middleName = $row->{middleName};
  my $lastName = $row->{lastName};
  my $count = $row->{count};

  ...
}