Troubleshooting

This document lists common problems and presents possible solutions.

For problems regarding the installation process or things that don't seem to be working correctly after installation, please see Installation-Troubleshooting.

For tips on how to get records from other reference managers or online services into refbase, please see Integration with other reference managers or Integration with online services, respectively.

MySQL migration and character set problems

To migrate your refbase installation from one computer to another, you need to be very careful about the character sets and MySQL versions you're using. Otherwise you will end up with garbled and strange characters when viewing what was once nice accented characters or "umlauts" (like norwegian å, æ, ø, or the german ä, ö, ü or swedish ø).

a) To solve the problem, you need to first check that the character sets used on the two database installations are the same. Use either phpMyAdmin or the MySQL command line interpreter.

phpMyAdmin

• login and click on "Show MySQL system variables"

• then check for these variables:

------------------------------------------------------------------
Varaible:                  Session:             Global:
------------------------------------------------------------------
...
character set client       utf8                 latin1
character set connection   utf8                 latin1
character set database     latin1               latin1
character set results      utf8                 latin1
character set server       latin1               latin1
character set system       utf8                 utf8
...
collation connection       utf8_general_ci      latin1_general_ci
collation database         latin1_general_ci    latin1_general_ci
collation server           latin1_general_ci    latin1_general_ci
...
------------------------------------------------------------------

MySQL

Enter the MySQL command line interpreter, select your refbase MySQL database, and execute following commands:

mysql> SHOW VARIABLES LIKE '%character%';
mysql> SHOW VARIABLES LIKE '%collation%';

Another possibility is to issue following command from the command line shell:

mysqladmin variables | grep "character\|collation"

b) If you see discrepancies between the two database installations with respect to these variables, it is better that they coincide. This can be done by adding two lines to the "[mysqld]" section of the MySQL config file (my.cnf) and restarting your MySQL server. Here's an example for a latin1-based database:

------------------------------------------
...
[mysqld]
#init-connect = 'SET NAMES latin1'
#init-connect = 'SET CHARACTER SET latin1'
character-set-server = latin1
collation-server     = latin1_general_ci
...
------------------------------------------

Note that for some MySQL systems/versions, some variable names seem to use underscores instead of hyphens. As an example, using MySQL 4.1.11 on Mac OS X 10.4, the following settings are recognized in the MySQL config file for latin1 (ISO-8859-1):

[mysqld]
character_set_server = latin1
collation_server = latin1_general_ci

or, in case of UTF-8:

[mysqld]
character_set_server = utf8
collation_server = utf8_general_ci

c) Next you need to "properly" dump the data from your original database, which can be achieved by use of the mysqldump command line program. The regular mysqldump statement (without any flags) may not work correctly, because mysqldump will, by default, output data using the UTF-8 character set. So, if you're using a different character set (such as latin1), you must specify the --default-character-set=WHAT_YOU_FIND_UNDER_character_set_server_ABOVE flag. And if you use an older MySQL version you may also need to use the --compatible flag. Example: assuming your refbase latin1-based database is named refbase and with root being the authorized user, your mysqldump statement would read:

$ mysqldump refbase -u root -p --opt --default-character-set=latin1 > refbase.sql

If you no longer have access to the old database for making this kind of dump, you may try to directly convert the old dump's character set with the iconv command line program. Here we convert the file dump.sql from UTF-8 to latin1 (ISO-8859-1) and write the data into a new file named iso_dump.sql:

$ iconv -f UTF-8 -t ISO-8859-1 dump.sql -o iso_dump.sql

d) You may want to test the new data by loading your MySQL dump file into a separate refbase database. To do so, perform these steps:

• Duplicate your refbase scripts to another directory (e.g. named "refbase_test") within your web directory.

• Copy your MySQL dump file into this new "refbase_test" directory (let's assume the dump file is named "refbase.sql").

• Within this new refbase folder, edit the $databaseName variable in file initialize/db.ini.php so that it has a name that does NOT collide with any existing MySQL database names (this is very important!).

• Access your "refbase_test" directory via the browser and point it to install.php.

• On the install form, enter for "Path to the database structure file" the name of your MySQL dump file (the file from step 2, e.g. "refbase.sql").

• Edit the other fields to suit your server setup and check that the chosen default character set matches the charset of your MySQL dump file, then click the "Install" button.

The above steps can be also used to quickly setup a local read-only copy of your refbase database, e.g. on a personal laptop that is meant to be used in places without internet access.