API:EPrints/Database

EPrints 3 Reference: Directory Structure - Metadata Fields - Repository Configuration - XML Config Files - XML Export Format - EPrints data structure - Core API - Data Objects

---

API: Core API

Latest Source Code (3.4, 3.3) | Revision Log | Before editing this page please read Pod2Wiki

NAME

EPrints::Database - a connection to the SQL database for an eprints session.

User Comments

DESCRIPTION

EPrints Database Access Module

Provides access to the backend database. All database access done via this module, in the hope that the backend can be replaced as easily as possible.

In most use-cases it should not be necessary to use the database module directly. Instead you should use EPrints::DataSet or EPrints::MetaField accessor methods to access objects and field values respectively.

User Comments

Cross-database Support

Any use of SQL statements must use quote_identifier to quote database tables and columns and quote_value to quote values. The only exception to this are the EPrints::Database::* modules which provide database-driver specific extensions.

User Comments

Quoting SQL Values

By convention variables that contain already quoted values are prefixed with Q_ so they can be easily recognised when used in string interpolation:

my $Q_value = $db->quote_value( "Hello, World!" );
$db->do("SELECT $Q_value");
 

Where possible you should avoid quoting values yourself, instead use a method that accepts unquoted values which will (safely) do the work for you.

User Comments

CONSTANTS

All the SQL_ column types defined by Perl module DBI and the following:

User Comments

SQL_NULL

A column value is undefined.

User Comments

SQL_NOT_NULL

A column value is defined.

User Comments

INSTANCE VARIABLES

User Comments

$self->{session}

The EPrints::Session which is associated with this database connection.

User Comments

$self->{debug}

If true then SQL is logged.

User Comments

$self->{dbh}

The handle on the actual database connection.

User Comments

METHODS

User Comments

Database

User Comments

new

$db = EPrints::Database->new( $repo, [ %opts ] )

Create a connection to the database.

Options:

 db_connect - Boolean. Also connect to the database (default: true).

User Comments

create

$db = $db->create( $username, $password )

Create and connect to a new database using user account $username and $password.

User Comments

build_connection_string

$dbstr = EPrints::Database::build_connection_string( %params )

Build the string to use to connect to the database via DBI.

Parameters:

dbname - Database name (REQUIRED).
dbdriver - Database driver (e.g. mysql, Oracle, pgsql, default: mysql).
dbhost - Database host.  Assumes localhost if unset.
dbport - Port to connect to database host.  Assumes default for driver if unset.
dbsock - Socket file to connect to database through.

User Comments

connect

$db->connect()

Connects to the database.

User Comments

disconnect

$db->disconnect()

Disconnects from the EPrints database. Should always be done before any script exits.

User Comments

set_debug

$db->set_debug( $boolean )

Set the SQL debug mode to true or false.

User Comments

set_version

$db->set_version( $versionid );

Set the version id table in the SQL database to the given versionid (used by the upgrade script).

User Comments

get_version

$version = $db->get_version

Returns the current database schema version.

User Comments

is_latest_version

$boolean = $db->is_latest_version

Return true if the SQL tables are in the correct configuration for this edition of eprints. Otherwise, false.

User Comments

get_server_version

$version = $db->get_server_version

Return the database server version.

User Comments

get_default_charset

$charset = $db->get_default_charset

Return the character set to use.

Returns undef if character sets are unsupported.

User Comments

get_default_collation

$collation = $db->get_default_collation( $lang )

Return the collation to use for language $lang.

Returns undef if collation is unsupported.

User Comments

get_driver_name

$driver = $db->get_driver_name

Return the database driver name.

User Comments

error

$errstr = $db->error()

Return a string describing the last SQL error.

User Comments

retry_error

$boolean = $db->retry_error()

Returns a boolean for whether the database error is a retry error.

User Comments

duplicate_error

$boolean = $db->duplicate_error()

Returns a boolean for whether the database error is a duplicate error.

User Comments

begin

$db->begin()

Begin a transaction.

User Comments

commit

$db->commit()

Commit the previously begun transaction.

User Comments

rollback

$db->rollback()

Rollback the partially completed transaction.

User Comments

type_info

$type_info = $db->type_info( $data_type )

See DBI/type_info.

User Comments

get_column_type

$real_type = $db->get_column_type( $name, $data_type, $not_null, [ $length, $scale, %opts ] )

Returns a SQL column definition for $name of type $type, usually something like:

 $name $type($length,$scale) [ NOT NULL ]
 

If $not_null is true column will be set to NOT NULL.

$length and $scale control the maximum lengths of character or decimal types (see below).

Other options available to refine the column definition:

 langid - character set/collation to use
 sorted - whether this column will be used to order by
 

langid is mapped to real database values by the "dblanguages" configuration option. The database may not be able to order the request column type in which case, if sorted is true, the database may use a substitute column type.

$data_type is the SQL type. The types are constants defined by this module, to import them use:

 use EPrints::Database qw( :sql_types );
 

Supported types (n = requires $length argument):

Character data: SQL_VARCHAR(n), SQL_LONGVARCHAR, SQL_CLOB.

Binary data: SQL_VARBINARY(n), SQL_LONGVARBINARY.

Integer data: SQL_TINYINT, SQL_SMALLINT, SQL_INTEGER, SQL_BIGINT.

Floating-point data: SQL_REAL, SQL_DOUBLE.

Time data: SQL_DATE, SQL_TIME.

The actual column types used will be database-specific.

User Comments

Basic SQL Operations

User Comments

do

$success = $db->do( $sql )

Execute the given $sql.

User Comments

prepare

$sth = $db->prepare( $sql )

Prepare the given $sql and return a handle on it.

Use the execute method on the returned DBI handle to execute the SQL:

 my $sth = $db->prepare_select( "SELECT 'Hello, World'" );
 $sth->execute;
 

User Comments

prepare_select

$sth = $db->prepare_select( $sql, [ %options ] )

Prepare a SELECT statement $sql and return a handle to it. After preparing a statement use execute() to execute it.

Returns a DBI statement handle.

The LIMIT SQL keyword is not universally supported, to specify this use the limit option.

Options:

 limit - limit the number of rows returned
 offset - return limit number of rows after offset
 

User Comments

execute

$success = $db->execute( $sth, $sql )

Execute the SQL prepared earlier in the $sth. $sql is only required for debugging purposes.

User Comments

update

$success = $db->update( $dataset, $data, $changed )

Updates a EPrints::DataObj from $dataset with the given $data. The primary key field (e.g. eprintid) value must be included.

Updates the ordervalues if the $dataset is ordered.

User Comments

_update

$rows = $db->_update( $tablename, $keycols, $keyvals, $columns, @values )

Updates $columns in $tablename with @values where $keycols equals $keyvals and returns the number of rows affected.

N.B. If no rows are affected, the result is still true, see DBI's execute() method.

This is an internal method.

User Comments

insert

$success = $db->insert( $table, $columns, @values )

Inserts @values into the table $table. If $columns is defined it will be used as a list of columns to insert into. @values is a list of arrays containing values to insert. These will be quoted before insertion.

User Comments

insert_quoted

$success = $db->insert_quoted( $table, $columns, @qvalues )

Inserts values into the table $table. If $columns is defined it will be used as a list of columns to insert into. @qvalues is a list of arrays containing values to insert. These will NOT be quoted before insertion - care must be exercised!

User Comments

delete_from

$success = $db->delete_from( $table, $columns, @values )

Perform a SQL DELETE FROM $table using $columns to build a where clause. @values is a list of array references of values in the same order as $columns.

If you want to clear a table completely use clear_table().

User Comments

count_table

$n = $db->count_table( $tablename )

Return the number of rows in the specified SQL table with $tablename.

User Comments

clear_table

$db->clear_table( $tablename )

Clears all records from the given table with $tablename. Use with caution!

User Comments

Quoting

User Comments

prep_int

$mungedvalue = EPrints::Database::prep_int( $value )

Escape numerical $value for an SQL statement. undef becomes NULL. Anything else becomes a number (zero if needed).

User Comments

prep_value

$mungedvalue = EPrints::Database::prep_value( $value )

Escape $value for an SQL statement. Modify value such that " becomes \" and \ becomes \\ and ' becomes \'.

User Comments

prep_like_value

$mungedvalue = EPrints::Database::prep_like_value( $value )

Escape $value for an SQL LIKE clause. In addition to ' " and \ also escapes % and _.

User Comments

quote_value

$str = $db->quote_value( $value )

Return a quoted version of $value. To quote a LIKE value you should use:

$db->quote_value( EPrints::Database::prep_like_value( $foo ) . '%' );
 

User Comments

quote_int

$str = $db->quote_int( $value )

Return a quoted integer for $value.

User Comments

quote_binary

$str = $db->quote_binary( $bytes )

Some databases (Oracle/PostgreSQL) require transforms of binary data to work correctly.

This method should be called on data $bytes containing null bytes or back-slashes before being passed on quote_value.

User Comments

quote_ordervalue

$str = $db->quote_ordervalue( $field, $value )

Some databases (Oracle) can't order by CLOBs so need special treatment when creating the ordervalues tables. This method allows any fixing-up required for string data $value for $field before it's inserted.

User Comments

quote_identifier

$str = $db->quote_identifier( @parts )

Quote a database identifier (e.g. table names). Multiple @parts will be joined by dots (.).

User Comments

prepare_regexp

$sql = $db->prepare_regexp( $col, $value )

The syntax used for regular expressions varies across databases. This method takes two quoted string and returns a SQL expression that will apply the quoted regexp $value to the quoted column $col.

User Comments

sql_as

$sql = $db->sql_AS()

Returns the syntactic glue to use when aliasing. SQL 92 databases will happily use AS but some databases (Oracle) will not accept it.

User Comments

sql_like

$sql = $db->sql_LIKE()

Returns the syntactic glue to use when making a case-insensitive LIKE. PostgreSQL requires ILIKE while everything else uses LIKE and the column collation.

User Comments

Counters

User Comments

counter_current

$n = $db->counter_current( $counter )

Return the value of the previous counter_next on $counter.

User Comments

counter_next

$n = $db->counter_next( $counter )

Return the next unused value for the named $counter. Returns undef if the $counter doesn't exist.

User Comments

counter_minimum

$db->counter_minimum( $counter, $value )

Ensure that the $counter is set no lower than $value. This is used when importing eprints which may not be in scrict sequence.

User Comments

counter_reset

$db->counter_reset( $counter )

Reset the $counter. Use with caution.

User Comments

next_doc_pos

$n = $db->next_doc_pos( $eprintid )

Return the next unused document position for the given $eprintid.

User Comments

Dataset Data

User Comments

exists

$boolean = $db->exists( $dataset, $id )

Return true if there exists an EPrints::DataObj from the $dataset with its primary key set to $id. Otherwise, return false.

User Comments

add_record

$success = $db->add_record( $dataset, $data )

Add the given $data as a new record in the given $dataset. $data is a reference to a hash containing values structured for a record in the that $dataset.

User Comments

remove

$success = $db->remove( $dataset, $id )

Attempts to remove the EPrints::DataObj with the primary key $id from the specified $dataset.

User Comments

Searching, caching and object retrieval

User Comments

cache_exp

$searchexp = $db->cache_exp( $cacheid )

Return the serialised search of a the cached search with $cacheid. Return undef if the $cacheid is invalid or expired.

User Comments

cache

$cacheid = $db->cache( $searchexp, $dataset, $srctable, [$order], [$list] )

Create a cache of the specified search expression from the SQL table $srctable.

If $order is set then the cache is ordered by the specified fields. For example -year/title orders by year (descending). Records with the same year are ordered by title.

If $srctable is set to LIST then order is ignored and the list of IDs is taken from the array reference $list.

If $srctable is set to ALL every matching record from $dataset is added to the cache, optionally ordered by $order.

User Comments

cache_table

$tablename = $db->cache_table( $id )

Return the name of the SQL table used to store the cache with $id.

User Comments

cache_userid

$userid = $db->cache_userid( $id )

Returns the userid associated with the cache with $id if that cache exists.

User Comments

get_cachemap

$cachemap = $db->get_cachemap( $id )

Return the cachemap with $<id>.

User Comments

search

$ids = $db->search( $keyfield, $tables, $conditions, [ $main_table_alias ] )

Return a reference to an array of $keyfield IDs - the results of the search specified by $conditions across the tables specified in the $tables hash where keys are tables aliases and values are table names.

If no $main_table_alias is specified then M is assumed.

User Comments

drop_cache

$db->drop_cache( $id )

Remove the cached search with the given $id.

User Comments

from_cache

$items = $db->from_cache( $dataset, $cacheid, [ $offset, $count, $justids ] )

Return a reference to an array containing all the items from the given $dataset that have IDs in the cache specified by $cacheid. The cache may be specified either by ID or serialised search expression.

$offset is an offset from the start of the cache and $count is the number of records to return.

If $justids is true then it returns just a reference to an array of the record IDs and not the objects themselves.

User Comments

drop_orphan_cache_tables

$c = $db->drop_orphan_cache_tables

Drop tables called cacheXXX where XXX is an integer. Returns the number of cache tables dropped.

User Comments

get_single

$obj = $db->get_single( $dataset, $id )

Return a single <EPrints::DataObj> from the given $dataset with primary key set to $id.

User Comments

get_all

$items = $db->get_all( $dataset )

Returns a reference to an array with all the <EPrints::DataObj>s from the given $dataset.

User Comments

get_cache_ids

@ids = $db->get_cache_ids( $dataset, $cachemap, $offset, $count )

Returns a list of $count IDs from $cache_id starting at $offset and in the order in the $cachemap.

User Comments

get_dataobjs

@dataobjs = $db->get_dataobjs( $dataset, [ $id, $id, ... ] )

Retrieves the records in $dataset with the given $id(s). If an $id doesn't exist in the database it will be ignored.

User Comments

get_values

$values = $db->get_values( $field, $dataset )

Return a reference to an array of all the distinct values of the EPrints::MetaField $field for the $dataset specified.

User Comments

sort_values

$values = $db->sort_values( $field, $values, [ $langid ] )

Sorts and returns the list of $values using the database.

$field is used to get the order value for each value. $langid (or $session->get_langid if unset) is used to determine the database collation to use when sorting the resulting order values.

User Comments

get_ids_by_field_values

$ids = $db->get_ids_by_field_values( $field, $dataset, [ %opts ] )

Return a reference to a hash table where the keys are specified $datasets's $field value IDs and the values are references to arrays of IDs.

User Comments

dequeue_events

@events = $db->dequeue_events( $n )

Attempt to dequeue upto $n events. May return between 0 and $n events depending on parallel processes and how many events are remaining in the queue.

User Comments

ci_lookup

$value = $db->ci_lookup( $field, $value )

This is a hacky method to support case-insensitive lookup for usernames, emails, etc. It returns the actual case-sensitive version of $value if there is a case-insensitive match for the $field.

User Comments

Password Validation and Secret Fields

User Comments

valid_login

$db->valid_login( $username, $password )

Returns whether the clear-text $password matches the stored crypted password for the $username.

User Comments

secret_matches

$db->secret_matches( $dataobj, $fieldname, $token [, $callback ] )

Returns whether the clear-text $token matches the stored crypted field with $fieldname for the $dataobj according to the $callback function.

If not set, $callback defaults to EPrints::Utils#crypt_equals.

User Comments

is_secret_set

$boolean = $db->is_secret_set( $dataobj, $fieldname )

Returns a boolean for whether the secret $fieldname for $dataobj has a value set.

User Comments

Database Schema Manipulation

User Comments

has_sequence

$boolean = $db->has_sequence( $name )

Returns true if a sequence of the given $name exists in the database. Otherwise, returns false.

User Comments

create_sequence

$success = $db->create_sequence( $name )

Creates a new sequence object with $name and initialises to zero.

User Comments

drop_sequence

$success = $db->drop_sequence( $name )

Deletes a sequence object with $name.

User Comments

has_column

$boolean = $db->has_column( $table, $column )

Return true if the named $table has the named $column in the database.

User Comments

drop_column

$success = $db->drop_column( $table, $column )

Drops the named $column from the named $table.

User Comments

get_primary_key

@columns = $db->get_primary_key( $tablename )

Returns a list of column names that comprise the primary key for the $tablename.

Returns an empty list if no primary key exists.

User Comments

index_name

$name = $db->index_name( $table, @cols )

Returns the name of the first index that starts with named columns @cols in the named $table.

Returns undef if no index exists.

User Comments

get_index_ids

$ids = $db->get_index_ids( $table, $condition )

Return a reference to an array of the distinct primary keys from the named SQL $table which match the specified $condition.

User Comments

create_index

$success = $db->create_index( $table, @columns )

Creates an index over @columns for named $table. Returns true on success, false otherwise.

User Comments

create_unique_index

$success = $db->create_unique_index( $tablename, @columns )

Creates a unique index over @columns for named $table. Returns true on success, false otherwise.

User Comments

create_foreign_key

$ok = $db->create_foreign_key( $main_table, $table, $key_field )

Create a foreign key relationship between named $main_table and named $table using $key_field.

This will cause records in $table to be deleted if the equivalent record is deleted from $main_table.

User Comments

get_tables

@tables = $db->get_tables( [ $dbname ] )

Returns a list of all the tables in the database.

$dbname specifies a particular database name of current connection has access to more than one database.

User Comments

has_table

$boolean = $db->has_table( $tablename )

Returns boolean dependent on whether a table of the $tablename exists in the database.

User Comments

create_table

$success = $db->create_table( $tablename, $setkey, @fields );

Creates a new table with $tablename based on @fields.

The first $setkey number of fields are used for its primary key.

User Comments

drop_table

$db->drop_table( @tables )

Delete the named @tables. Use with caution!

User Comments

rename_table

$db->rename_table( $table_from, $table_to )

Renames the table named $table_from to $table_to.

User Comments

swap_table

$db->swap_table( $table_a, $table_b )

Renames table named $table_a to $table_b and vice-versa.

User Comments

EPrints Schema Manipulation

User Comments

create_archive_tables

$success = $db->create_archive_tables()

Create all the SQL tables for all datasets.

User Comments

drop_archive_tables

$db->drop_archive_tables()

Destroy all tables used by EPrints in the database.

User Comments

create_version_table

$db->create_version_table

Make the version table (and set the only value to be the current version of EPrints).

User Comments

drop_version_table

$db->drop_version_table

Drop the version table.

User Comments

has_dataset

$db->has_dataset( $dataset )

Returns true if $dataset exists in the database and has all expected tables including ordervalues and index tables.

This does not check that all fields are configured - see </has_field>.

User Comments

has_dataset_index_tables

$db->has_dataset_index_tables( $dataset )

Returns true if index tables for $dataset exists of if this is not indexable.

User Comments

create_dataset_tables

$success = $db->create_dataset_tables( $dataset )

Creates all the SQL tables for the specified $dataset.

User Comments

drop_dataset_tables

$db->drop_dataset_tables( $dataset )

Drops all the SQL tables for the specified $dataset.

User Comments

create_dataset_index_tables

$success = $db->create_dataset_index_tables( $dataset )

Creates all the index tables for the specified $dataset.

User Comments

create_dataset_ordervalues_tables

$success = $db->create_dataset_ordervalues_tables( $dataset )

Creates all the ordervalues tables for the specified $dataset.

User Comments

has_field

$db->has_field( $dataset, $field )

Returns true if $field is in the database for $dataset.

User Comments

add_field

$db->add_field( $dataset, $field, [ $force ] )

Add $field to $dataset's tables.

If $force is true modify/replace an existing column. Use with care!

User Comments

remove_field

$db->remove_field( $dataset, $field )

Remove $field from $dataset's tables.

User Comments

rename_field

$ok = $db->rename_field( $dataset, $field, $old_name )

Rename the $field in the $dataset from its $old_name.

Returns true if the $field is successfully renamed.

User Comments

create_counters

$success = $db->create_counters

Create the counters used to store the highest current ID of eprints, users, etc.

User Comments

has_counter

$success = $db->has_counter( $counter )

Returns true if $counter exists.

User Comments

create_counter

$success = $db->create_counter( $name )

Create and initialise to zero a new counter with $name.

User Comments

remove_counters

$success = $db->remove_counters

Destroy all counters.

User Comments

drop_counter

$success = $db->drop_counter( $name )

Destroy the counter named $name.

User Comments

User Messages

User Comments

save_user_message

$message = $db->save_user_message( $userid, $m_type, $dom_m_data )

Save user message provided in XML DOM object $dom_m_data as a sanitized string in a EPrints::DataObj::Message using $m_type to define the message type and $userid for the ID of the user whose message it is.

User Comments

get_user_messages

@messages = $db->get_user_messages( $userid, %opts )

Get the messages for a user with ID $userid and clear messages if $opt{clear} is set.

User Comments

clear_user_messages

$db->clear_user_messages( $userid )

Clear all messages for user with ID $userid.

User Comments

SEE ALSO

To access database-stored objects use the methods provided by the following modules: EPrints::Repository, EPrints::DataSet.

User Comments

COPYRIGHT

© Copyright 2000-2024 University of Southampton.

EPrints 3.4 is supplied by EPrints Services.

http://www.eprints.org/eprints-3.4/

LICENSE

This file is part of EPrints 3.4 http://www.eprints.org/.

EPrints 3.4 and this file are released under the terms of the GNU Lesser General Public License version 3 as published by the Free Software Foundation unless otherwise stated.

EPrints 3.4 is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with EPrints 3.4. If not, see http://www.gnu.org/licenses/.

User Comments