Sympa::DatabaseDriver - Base class of database drivers for
Sympa
package Sympa::DatabaseDriver::FOO;
use base qw(Sympa::DatabaseDriver);
Sympa::DatabaseDriver is the base class of driver classes for
Sympa Database Manager (SDM).
- 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:
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.
- __dbh ( )
- Instance method, protected. Returns native database handle
which _connect() returned. This may be used at inside of each driver
class.
Sympa::Database, Sympa::DatabaseManager.
Sympa Database Manager (SDM) appeared on Sympa 6.2.