/ 
SeeAlso-Server-0.71
River stage one • 2 direct dependents • 2 total dependents
/ SeeAlso::DBI

NAME

SeeAlso::DBI - Store SeeAlso::Response objects in database.

VERSION

version 0.71

SYNOPSIS

# use database as SeeAlso::Source

my $dbh = DBI->connect( ... );
my $dbi = SeeAlso::DBI->new( dbh => $dbh );

print SeeAlso::Server->new->query( $dbi );

DESCRIPTION

A SeeAlso::DBI object manages a store of SeeAlso::Response objects that are stored in a database. By default that database must contain a table named seealso with rows named key, label, database, and uri. A query for identifier $id of type SeeAlso::Identifier will result in an SQL query such as

SELECT label, description, uri FROM seealso WHERE key=?

With the hashed identifier ($id<gthash>) used as key parameter. By default a database table accessed with this class stores the four values key, label, description, and uri in each row - but you can also use other schemas.

METHODS

new ( %parameters )

Create a new database store. You must specify either a database handle in form or a DBI object with parameter dbh parameter, or a dbi parameter that is passed to DBI->connect, or a config parameter to read setting from the DBI section of a configuration hash reference.

my $dbh = DBI->new( "dbi:mysql:database=$d;host=$host", $user, $password );
my $db = SeeAlso::DBI->new( dbh => $dbh );

my $db = SeeAlso::DBI->new( 
    dbi => "dbi:mysql:database=$database;host=$host", 
    user => $user, passwort => $password
);

use YAML::Any qw(LoadFile);
my $config = LoadFile("dbiconnect.yml");
my $db = SeeAlso::DBI->new( config => $config );
my $db = SeeAlso::DBI->new( $%{$config->{DBI}} ); # same

The configuration hash can be stored in a configuration file (INI, YAML, etc.) and must contains a section named DBI. All values specified in this section are added to the constructor's parameter list. A configuration file could look like this (replace uppercase values with real values):

DBI:
  dbi : mysql:database=DBNAME;host=HOST
  user : USER
  password : PWD

The following parameters are recognized:

dbh

Database Handle of type DBI.

dbh_ro

Database Handle of type DBI that will be used for all read access. Usefull for master-slave database settings.

dbi

Source parameter to create a DBI object. "dbi:" is prepended if the parameter does not start with this prefix.

user

Username if parameter dbi is given.

password

Password if parameter dbi is given.

table

SQL table name for default SQL statements (default: seealso).

select

SQL statement to select rows.

delete

SQL statement to delete rows.

insert

SQL statement to insert rows.

clear

SQL statement to clear the database table.

build

Newly create the SQL table with the create statement.

label

Do not store the label in the database but use this value instead.

description

Do not store the description in the database but use this value instead.

uri

Do not store the uri in the database but use this value instead.

key

One of 'hash' (default), 'value', 'canonical' or a code that the identifier is passed to before beeing used as key. Only useful when used together with parameter idtype.

idtype

Subclass of SeeAlso::Identifier to be use when creating an identifier.

config

Configuration settings as hash reference or as configuration file that will be read into a hash reference. Afterwarrds the The DBI section of the configuration is added to the other parameters (existing parameters are not overridden).

query_callback ( $identifier )

Fetch from DB, uses the key value ($identifier->hash by default).

key ( $identifier )

Get a key value for a given SeeAlso::Identifier.

create

Create the database table.

clear

Delete all content in the database. Be sure not to call this by accident!

drop

Delete the whole database table. Be sure not to call this by accident!

delete ( $identifier )

Removes all rows associated with a given identifier.

update ( $response )

Replace all rows associated with the the identifier of a given response with the new response.

insert ( $response )

Add a SeeAlso::Response to the database (unless the response is empty). Returns the number of affected rows or -1 if the database driver cannot determine this number.

bulk_insert ( $fetch_quadruple_sub )

Add a set of quadrupels to the database. The subroutine $fetch_quadruple_sub is called unless without any parameters, until it returns a false value. It is expected to return a reference to an array with four values (key, label, description, uri) which will be added to the database. Returns the number of affected rows or -1 if the database driver cannot determine this number.

enriched_row

bulk_import ( [ file => $file ... ] )

TODO: remove enrichment!

SEE ALSO

This package was partly inspired by on CHI::Driver::DBI by Justin DeVuyst and Perrin Harkins.

AUTHOR

Jakob Voss

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Jakob Voss.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.