next up previous contents index
Next: 7. WWSympa, Sympa's web interface Up: Sympa Mailing Lists Management Software version Previous: 5. sympa.conf parameters   Contents   Index

Subsections


6. Sympa and its database

Most basic feature of Sympa will work without a RDBMS, but WWSympa and bounced require a relational database. Currently you can use one of the following RDBMS : MySQL, PostgreSQL, Oracle, Sybase. Interfacing with other RDBMS requires only a few changes in the code, since the API used, DBI (DataBase Interface), has DBD (DataBase Drivers) for many RDBMS.

6.1 Prerequisites

You need to have a DataBase System installed (not necessarily on the same host as Sympa), and the client libraries for that Database installed on the Sympa host ; provided, of course, that a PERL DBD (DataBase Driver) is available for your chosen RDBMS! Check the DBI Module Availability.

6.2 Installing PERL modules

Sympa will use DBI to communicate with the database system and therefore requires the DBD for your database system. DBI and DBD::YourDB (Msql-Mysql-modules for MySQL) are distributed as CPAN modules. Refer to 3.2.3, page [*] for installation details of these modules.

6.3 Creating a sympa DataBase

6.3.1 Database structure

The sympa database structure is slightly different from the structure of a subscribers file. A subscribers file is a text file based on paragraphs (similar to the config file) ; each paragraph completely describes a subscriber. If somebody is subscribed to two lists, he/she will appear in both subscribers files.

The DataBase distinguishes information relative to a person (e-mail, real name, password) and his/her subscription options (list concerned, date of subscription, reception option, visibility option). This results in a separation of the data into two tables : the user_table and the subscriber_table, linked by a user/subscriber e-mail.

6.3.2 Database creation

The create_db script below will create the sympa database for you. You can find it in the script/ directory of the distribution (currently scripts are available for MySQL, PostgreSQL, Oracle and Sybase).

You can execute the script using a simple SQL shell such as mysql, psql or sqlplus.

Example:

# mysql  < create_db.mysql

6.4 Setting database privileges

We strongly recommend you restrict access to sympa database. You will then set db_user and db_passwd in sympa.conf.

With :

grant all on sympa.* to sympa@localhost identified by 'your_password';
flush privileges;

6.5 Importing subscribers data

6.5.1 Importing data from a text file

You can import subscribers data into the database from a text file having one entry per line : the first field is an e-mail address, the second (optional) field is the free form name. Fields are spaces-separated.

Example:

## Data to be imported
## email        gecos
john.steward@some.company.com           John - accountant
mary.blacksmith@another.company.com     Mary - secretary

To import data into the database :

cat /tmp/my_import_file | sympa.pl --import=my_list

(see 3.6, page [*]).

6.5.2 Importing data from subscribers files

If a mailing list was previously setup to store subscribers into subscribers file (the default mode in versions older then 2.2b) you can load subscribers data into the sympa database. The easiest way is to edit the list configuration using WWSympa (this requires listmaster privileges) and change the data source from file to database ; subscribers data will be loaded into the database at the same time.

If the subscribers file is big, a timeout may occur during the FastCGI execution (Note that you can set a longer timeout with the -idle-timeout option of the FastCgiServer Apache configuration directive). In this case, or if you have not installed WWSympa, you should use the load_subscribers.pl script.

6.6 Extending database table format

You can easily add other fields to subscriber_table and user_table, they will not disturb Sympa because it lists explicitely the field it expects in SELECT queries.

Moreover you can access these database fields from within Sympa (in templates), as far as you list these additional fields in sympa.conf (See 5.10.9, page [*] and 5.10.10, page [*]).

6.7 Sympa configuration

To store subscriber information in your newly created database, you first need to tell Sympa what kind of database to work with, then you must configure your list to access the database.

You define the database source in sympa.conf : db_type, db_name, db_host, db_user, db_passwd.

If you are interfacing Sympa with an Oracle database, db_name is the SID.

All your lists are now configured to use the database, unless you set list parameter user_data_source to file or include.

Sympa will now extract and store user information for this list using the database instead of the subscribers file. Note however that subscriber information is dumped to subscribers.db.dump at every shutdown, to allow a manual rescue restart (by renaming subscribers.db.dump to subscribers and changing the user_data_source parameter), if ever the database were to become inaccessible.


next up previous contents index
Next: 7. WWSympa, Sympa's web interface Up: Sympa Mailing Lists Management Software version Previous: 5. sympa.conf parameters   Contents   Index
root 2003-09-12