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.
Once again, the database schema of the main database has changed. However, starting from this version the name of the main database is a configure option. If you do not have to run this and an older version in parallel, you don't have to change the configuration. However, if you want to keep your existing setup while test-driving the new version, there is a new configure switch --with-main-db to set the name of the main database.
In the first case, you'll have to replace your existing main database with the new version. In the second case, you create another main database with a different name. Only the new version of refdb will be able to access this database if configured properly.
Finally, a bug in the MySQL table definitions was fixed. If you're using MySQL as your database engine, you'll have to migrate your reference databases as well. 0.9.5 provides a SQL script that changes the table definitions appropriately.
The citation and bibliography style DTD (citestlylex.dtd) was extended to facilitate the formatting of bibliographies in terms of indentation and font sizes. Styles written with older versions of the DTD will continue to work with refdb 0.9.5 or later. However, if you want to use the new features, you should extend the style files according to the new DTD and add the styles again.
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 RIS 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 ris -o dbname.ris :ID:>0 to dump your databases to RIS files.
After installing and starting 0.9.4, create a new database and read back your existing data with the refdbc command addref -t ris -d newdbname dbname.ris
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).