LucidDbUpgrade

From Eigenpedia

Jump to: navigation, search

Contents

Overview

This page explains how to upgrade an instance of LucidDB.

Before reading on, here are a few important points to note:

  • Upgrade is currently a manual procedure requiring some care. (Adding automated upgrade support would be a very useful contribution to LucidDB!)
  • The catalog.sql script was introduced in version 0.7.2; before this, there was no way to bring the system views up to date after upgrade.
  • Best practice is to make a cold backup of your existing installation before attempting any upgrade.

Procedure

  1. Unpack and install the new LucidDB version in a new location. So, for example, you might have an old version installed as /home/sderkins/luciddb-0.7.1. In that case, unpack the new version in /home/sderkins/luciddb-0.7.2. (We'll use those two paths as examples in the rest of this procedure; replace them with your site-specific locations.) Run the install script, but do not attempt to start the new server at the same time as the old server.
  2. If the old server is not already running, start it now.
  3. Connect to the old server via sqllineClient and issue this command to export the catalog metadata in XMI form (saving it to a file in the old server installation directory):
    CALL SYS_ROOT.EXPORT_CATALOG_XMI('/home/sderkins/luciddb-0.7.1/FarragoCatalogDump.xmi');
    (This may take a little while, depending on how big your schemas are; a server with Mondrian's FOODMART schema loaded and analyzed could take about half a minute; the resulting export file size is about 6MB.)
  4. !quit from sqllineClient. Do not execute any other commands on the old instance after this.
  5. Shut down the old server and verify that it was a clean shutdown. See LucidDbBackupRestore for how to do this, and what to do if the shutdown failed.
  6. In the new server location, run bin/sqllineEngine (instead of the usual lucidDbServer). This will start up LucidDB in a no-network maintenance mode process with the usual sqlline command-line interface.
  7. Issue this command to prepare the server for catalog migration:
    ALTER SYSTEM REPLACE CATALOG;
    (This may take a while; it also exports some metadata to a system-defined location for use on restart.)
  8. !quit from sqllineEngine. Do not execute any other commands (if you try it, you'll get internal errors).
  9. Copy the physical database file (db.dat) from the old server location to the new one, overwriting the empty one that just got installed, e.g.
    cp -f /home/sderkins/luciddb-0.7.1/catalog/db.dat /home/sderkins/luicddb-0.7.2/catalog/db.dat
  10. Copy the catalog metadata XMI (created in step 3) from the old server location to the new catalog location, e.g.
    cp -f /home/sderkins/luciddb-0.7.1/FarragoCatalogDump.xmi /home/sderkins/luciddb-0.7.2/catalog/FarragoCatalogDump.xmi
    (be sure to force an overwrite since step 7 will have created an unneeded file in the target location).
  11. Start the new server in the usual way (lucidDbServer). (This will take time proportional to the export in step 3, since it has to import the metadata into the new catalog.)
  12. Special case for upgrade from 0.7.1: Use sqllineClient to execute the following two cleanup commands:
    drop procedure sys_boot.sys_boot.save_test_parameters;
    drop procedure sys_boot.sys_boot.clean_test;
    (If you are upgrading from 0.7.2 or later, you do not need to execute these commands; continue with step 13.)
  13. Using sqllineClient, execute the install/catalog.sql from the new server installation, e.g.
    sqllineClient --run=/home/sderkins/luciddb-0.7.2/install/catalog.sql
  14. Check the sqlline output to verify that there were no errors while running catalog.sql.
  15. Shut the new server down and back it up so that if anything goes wrong subsequently, you won't have to repeat the upgrade process.

Notes

  • If you used relative paths in any SQL object definitions (e.g. the location of a flatfile directory or .jar file), you may encounter problems with the new server not being able to find those objects. This may even interfere with the migration procedure above (e.g. executing catalog.sql). In general, avoiding relative paths in object definitions is a good practice; if you can't avoid them for some reason, you may need to take compensating measures (e.g. create symlinks or carry out the upgrade in-place rather than side-by-side).
  • If your db.dat file is very large, you may prefer to move it rather than copy it during step 9. This assumes that you have backed the old server up before starting.

Restore Across Versions

Suppose you have an old backup taken from version 0.7.1, and now you want to restore it onto 0.7.2. As noted in LucidDbBackupRestore, you can't do this via the direct restore procedure since the versions don't match. Instead, do this:

  1. Re-install a fresh copy of 0.7.1
  2. Restore your old backup in that environment
  3. Upgrade that environment to a fresh copy of 0.7.2, using the procedure above.

(Attempting the same thing in the downgrade direction is unlikely to work.)