Provided by: sympa_6.2.70~dfsg-2_amd64 bug

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.