If you already run an older version of refdb and want to upgrade to the latest version, you may have to change a few things in your local setup in order to reuse existing databases and existing configuration files. This section lists all backwards-incompatible changes of the past few versions (the complete list since the days of yore can be found in the file README).
Note: The file UPGRADING contains instructions how to avoid losing your data in the case of non-trivial changes in the new version.
In order to support the new link elements, the database schema of the common database has changed. The name of the database was therefore changed back to refdb. This will allow to run 0.9.4 and older versions in parallel if desired.
The support for extended notes required substantial changes in the database schema of the reference databases. It is required to export all existing references to risx files and reimport them into new databases after upgrading to 0.9.4:
Make all sorts of backups of your existing databases. Use the native tools of your database server to create SQL dumps. In case of MySQL or SQLite databases, you can also make copies of the subdirectories and files, respectively.
While still running your pre-0.9.4 installation, use the refdbc command getref -t risx -o dbname.xml :ID:>0 to dump your databases to XML files.
After installing and starting 0.9.4, create a new database and read back your existing data with the refdbc command addref -t risx newdbname.xml<
The citation key code had some serious flaws in previous versions. In order to work around these flaws it is recommended to re-create existing databases from a risx dump. This will fix the following issues:
In order to work properly in SGML documents, the citation keys must be all uppercase. Mixed case is fine if you use only XML or BibTeX.
In order to avoid troubles with incompatible character encodings, the citation keys should be restricted to the 7-bit ASCII range.
The following procedure is recommended to re-create your databases:
Make all sorts of backups of your existing databases. Use the native tools of your database server to create SQL dumps. In case of MySQL or SQLite databases, you can also make copies of the subdirectories and files, respectively.
After upgrading to 0.9.3, use the refdbc command getref -t risx -o dbname.xml :ID:>0 to dump your databases to XML files.
Decide whether you want to use your setup for SGML documents. If you will use SGML documents, the citation keys have to be all uppercase. You can do this manually, use a Perl one-liner, or configure refdbd to uppercase citation keys when adding datasets. Use either the -U command line switch or set the upper_citekey configuration variable appropriately. You can of course process XML and LaTeX documents with these settings as well, but you'll have to enter the citation keys in their uppercase forms in XML and LaTeX documents.
Create a new database and read back your existing data with the refdbc command addref -t risx newdbname.xml
The schema of the common database refdb has changed. To allow old and new refdb versions to run in parallel, versions 0.9 and later use refdb1 as the common database. Create this database after installation of the refdb components according to the user manual.
The refdbvar database used by refdb versions prior to 0.9 is obsolete. After upgrading to 0.9 you may safely drop this database.
The schema of the reference databases has changed. The main table t_refdb now has an additional column for the citation keys. In order to use your existing reference databases, please follow the instructions in the file UPGRADING.
The configuration files are now expected to be in a subdirectory refdb of the system configuration directory. The example configuration files will be installed in this new location. To reuse your existing configuration files, please move these to the new location and add entries for variables new in 0.9.
The remoteadmin configuration variable for refdbd now uses 't' and 'f' as argument instead of '1' and '0'.
The cgiurl configuration variable for refdbc was renamed to cssurl which better reflects its purpose (ok, it was a braino to call it cgiurl in the first place).