Sympa::DatabaseDriver(3Sympa)

💖 Sympa::DatabaseDriver 💖

okay bestie, welcome to Sympa::DatabaseDriver, from the sympa 6.2.80 era — this is the base class of database drivers for Sympa. It's literally the blueprint that all the vibe-y little database driver classes inherit from. 👑

---

✨ SYNOPSIS ✨

like, here's how you'd actually make one of these bad boys. it's giving "template":

package Sympa::DatabaseDriver::FOO;
use base qw(Sympa::DatabaseDriver);

---

🌸 DESCRIPTION 🌸

Sympa::DatabaseDriver is the base class of driver classes for the Sympa Database Manager (SDM). it's the parent everyone wants to be adopted by. 💅

🧚 Instance methods subclasses should implement 🧚

this is the checklist, bestie. if you're writing a driver subclass, these are the methods the rest of the system is gonna come knocking for. some are mandatory, some are overridable, and a couple are like so last season (deprecated, we'll get there).

• required_modules ( ) — Overridable. Returns an arrayref including package name(s) this driver requires. By default, no packages are required. easy peasy 🍓
• required_parameters ( ) — Overridable. Returns an arrayref including names of required (not optional) parameters. By default, returns ['db_name'].

Note: On Sympa prior to 6.2.71b, it by default returned ['db_name', 'db_user']. 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. no connect string, no connection, periodt.

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. 💀 rip bozo
• 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. bestie said "enough or nah" 💅

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 => $column } ); — Overridable. If the column exists in the table, remove it using drop_field(). Otherwise do nothing. she's chill like that 😌
• drop_field ( $table, $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.

Note: On Sympa 6.2.71b.1 or earlier, delete_field() was defined instead of this.

• 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. nested hashes go brrr 🌀

• 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. she translates, she's multilingual 💅🌈

---

💜 Methods inherited from Sympa::Database that subclasses can override 💜

Subclasses of Sympa::DatabaseDriver class also can override methods provided by Sympa::Database class. yes bestie, you get extra powers:

• 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.

---

...and bestie, we are SO not done yet — there's more of this page coming, don't you dare close the tab 🦋✨

• Empty array () if arguments were not given 🙈 like, you handed over nothing, you get nothing back, that's the deal bestie.

AS_BLOB ( $value )

Overridable 💅 It's a helper function situation: it hands back the BLOB (binary large object) binding type and the value, which is exactly what do_prepared_query() needs to do its thing. Overridden by inherited classes, so if you're a subclass you can absolutely do your own version. Slay.

See AS_DOUBLE for more details — that one's got the whole rundown. 🫶

md5_func ( $expression, ... )

Required. Give it some expressions, and it returns a SQL expression that calculates the MD5 digest of all those expressions concatenated together. A couple of ground rules though, no cap:

• NULL values should be ignored during that concatenation, bestie, we don't want them messing up the vibe 💀
• numeric values should be converted to textual type before concatenation, periodt
• the value of the SQL expression should come out as lowercase 32 hexadigits — lowercase, all 32 of them, don't play with me ✨

🎀 Utility method 🎀

__dbh ( )

Instance method, protected 🔒 Returns the native database handle that _connect() returned. This may be used at inside of each driver class — so it's the lil internal hook, iykyk, not for just anybody to touch.

---

🌈 SEE ALSO 🌈

• Sympa::Database
• Sympa::DatabaseManager

📜 HISTORY 📜

Sympa Database Manager (SDM) appeared on Sympa 6.2. iconic behavior honestly 👑

---

And that's the whole page, bestie!! 🎀 This one's from Sympa::DatabaseDriver(3Sympa), version 6.2.80, dated 2026-10-19 — go forth and connect responsibly 💖🦋✨