internal package Foswiki::DBI::Database

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:

Child packagesChild packages

• Foswiki::DBI::Database::Generic - Connects to a generic database supported by perl's DBI. This class does not have a constructor of its own. See Foswiki::DBI::Database instead.
• Foswiki::DBI::Database::MariaDB - connects to a MariaDB
• Foswiki::DBI::Database::MySQL - connects to a MySQL database
• Foswiki::DBI::Database::PostgreSQL - connects to a PostgreSQL database
• Foswiki::DBI::Database::SQLite - connects to an SQLite database

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 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 "*"
• 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};

  ...
}