Provided by: sympa_6.2.70~dfsg-2_amd64 
NAME
Sympa::DatabaseDriver - Base class of database drivers for Sympa
SYNOPSIS
package Sympa::DatabaseDriver::FOO;
use base qw(Sympa::DatabaseDriver);
DESCRIPTION
Sympa::DatabaseDriver is the base class of driver classes for Sympa Database Manager
(SDM).
Instance methods subclasses should implement
required_modules ( )
Overridable. Returns an arrayref including package name(s) this driver requires. By
default, no packages are required.
required_parameters ( )
Overridable. Returns an arrayref including names of required (not optional)
parameters. By default, returns "['db_name', 'db_user']".
Note: On Sympa prior to 6.2.37b.2, it by default returned "['db_host', 'db_name',
'db_user']".
optional_modules ( )
Overridable. Returns an arrayref including all name(s) of optional packages. By
default, there are no optional packages.
This method was introduced by Sympa 6.2.4.
optional_parameters ( )
Overridable. Returns an arrayref including all names of optional parameters. By
default, returns 'db_passwd', 'db_port', 'db_options' and so on.
build_connect_string ( )
Mandatory for SQL driver. Builds the string to be used by the DBI to connect to the
database.
Parameter:
None.
Returns:
String representing data source name (DSN).
connect ( )
Overridable. Connects to database calling "_connect"() and sets database handle.
Parameter:
None.
Returns:
True value or, if connection failed, false value.
_connect ( )
Overridable. Connects to database and returns native database handle.
The default implementation is for DBI database handle.
get_substring_clause ( { source_field => $source_field, separator => $separator,
substring_length => $substring_length } )
This method was deprecated by Sympa 6.2.4.
get_limit_clause ( )
This method was deprecated.
get_formatted_date ( { mode => $mode, target => $target } )
Deprecated as of Sympa 6.2.25b.3.
Mandatory for SQL driver. Returns a character string corresponding to the expression
to use in a query involving a date.
Parameters:
$mode
authorized values:
'write'
The sub returns the expression to use in 'INSERT' or 'UPDATE' queries.
'read'
The sub returns the expression to use in 'SELECT' queries.
$target
The name of the field or the value to be used in the query.
Returns:
The formatted date or "undef" if the date format mode is unknown.
is_autoinc ( { table => $table, field => $field } )
Required to probe database structure. Checks whether a field is an auto-increment
field or not.
Parameters:
$field
The name of the field to test
$table
The name of the table to add
Returns:
True if the field is an auto-increment field, false otherwise
is_sufficient_field_type ( $required, $actual )
Overridable, only for SQL driver. Checks if database field type is sufficient.
Parameters:
$required
Required field type.
$actual
Actual field type.
Returns:
The true value if actual field type is appropriate AND size is equal to or greater
than required size.
This method was added on Sympa 6.2.67b.1.
set_autoinc ( { table => $table, field => $field } )
Required to update database structure. Defines the field as an auto-increment field.
Parameters:
$field
The name of the field to set.
$table
The name of the table to add.
Returns:
1 if the auto-increment could be set, "undef" otherwise.
get_tables ( )
Required to probe database structure. Returns the list of the tables in the database.
Parameters:
None.
Returns:
A ref to an array containing the list of the table names in the database, "undef" if
something went wrong.
add_table ( { table => $table } )
Required to update database structure. Adds a table to the database.
Parameter:
$table
The name of the table to add
Returns:
A character string report of the operation done or "undef" if something went wrong.
get_fields ( { table => $table } )
Required to probe database structure. Returns a ref to an hash containing the
description of the fields in a table from the database.
Parameters:
$table
The name of the table whose fields are requested.
Returns:
A hash in which the keys are the field names and the values are the field type.
Returns "undef" if something went wrong.
update_field ( { table => $table, field => $field, type => $type, ... } )
Required to update database structure. Changes the type of a field in a table from
the database.
Parameters:
$field
The name of the field to update.
$table
The name of the table whose fields will be updated.
$type
The type of the field to add.
$notnull
Specifies that the field must not be null
Returns:
A character string report of the operation done or "undef" if something went wrong.
add_field ( { table => $table, field => $field, type => $type, ... } )
Required to update database structure. Adds a field in a table from the database.
Parameters:
$field
The name of the field to add.
$table
The name of the table where the field will be added.
$type
The type of the field to add.
$notnull
Specifies that the field must not be null.
$autoinc
Specifies that the field must be auto-incremental.
$primary
Specifies that the field is a key.
Returns:
A character string report of the operation done or "undef" if something went wrong.
delete_field ( { table => $table, field => $field } )
Required to update database structure. Deletes a field from a table in the database.
Parameters:
$field
The name of the field to delete
$table
The name of the table where the field will be deleted.
Returns:
A character string report of the operation done or "undef" if something went wrong.
get_primary_key ( { table => $table } )
Required to probe database structure. Returns the list fields being part of a table's
primary key.
$table
The name of the table for which the primary keys are requested.
Returns:
A ref to a hash in which each key is the name of a primary key or "undef" if something
went wrong.
unset_primary_key ( { table => $table } )
Required to update database structure. Drops the primary key of a table.
Parameter:
$table
The name of the table for which the primary keys must be dropped.
Returns:
A character string report of the operation done or "undef" if something went wrong.
set_primary_key ( { table => $table, fields => $fields } )
Required to update database structure. Sets the primary key of a table.
Parameters:
$table
The name of the table for which the primary keys must be defined.
$fields
A ref to an array containing the names of the fields used in the key.
Returns:
A character string report of the operation done or "undef" if something went wrong.
get_indexes ( { table => $table } )
Required to probe database structure. Returns a ref to a hash in which each key is
the name of an index.
Parameter:
$table
The name of the table for which the indexes are requested.
Returns:
A ref to a hash in which each key is the name of an index. These key point to a
second level hash in which each key is the name of the field indexed. Returns "undef"
if something went wrong.
unset_index ( { table => $table, index => $index } )
Required to update database structure. Drops an index of a table.
Parameters:
$table
The name of the table for which the index must be dropped.
$index
The name of the index to be dropped.
Returns:
A character string report of the operation done or "undef" if something went wrong.
set_index ( { table => $table, index_name => $index_name, fields => $fields } )
Required to update database structure. Sets an index in a table.
Parameters:
$table
The name of the table for which the index must be defined.
$fields
A ref to an array containing the names of the fields used in the index.
$index_name
The name of the index to be defined.
Returns:
A character string report of the operation done or "undef" if something went wrong.
translate_type ( $generic_type )
Required to probe and update database structure. Get native field type corresponds to
generic type. The generic type is based on MySQL: See "full_db_struct" in
Sympa::DatabaseDescription.
Subclasses of Sympa::DatabaseDriver class also can override methods provided by
Sympa::Database class:
do_operation ( $operation, $parameters, ...)
Overridable, only for LDAP driver.
do_query ( $query, $parameters, ... )
Overridable, only for SQL driver.
do_prepared_query ( $query, $parameters, ... )
Overridable, only for SQL driver.
AS_DOUBLE ( $value )
Overridable. Helper functions to return the DOUBLE binding type and value used by
"do_prepared_query"(). Overridden by inherited classes.
Parameter:
$value
Parameter value
Returns:
One of:
• An array "( { sql_type => SQL_type }, value )".
• Single value (i.e. an array with single item), if special treatment won't be
needed.
• Empty array "()" if arguments were not given.
AS_BLOB ( $value )
Overridable. Helper functions to return the BLOB (binary large object) binding type
and value used by "do_prepared_query"(). Overridden by inherited classes.
See "AS_DOUBLE" for more details.
Utility method
__dbh ( )
Instance method, protected. Returns native database handle which _connect() returned.
This may be used at inside of each driver class.
SEE ALSO
Sympa::Database, Sympa::DatabaseManager.
HISTORY
Sympa Database Manager (SDM) appeared on Sympa 6.2.