Hawkin
/
arangodb
mirror of https://gitee.com/bigwinds/arangodb
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
arangodb/Documentation/Manual/Upgrading13.md

8.1 KiB
Raw Blame History

Upgrading to ArangoDB 1.3

@NAVIGATE_Upgrading13 @EMBEDTOC{Upgrading13TOC}

Upgrading

ArangoDB 1.3 provides a lot of new features and APIs when compared to ArangoDB 1.2. The most important one being true multi-collection transactions support.

The following list contains changes in ArangoDB 1.3 that are not 100% downwards-compatible to ArangoDB 1.2.

Existing users of ArangoDB 1.2 should read the list carefully and make sure they have undertaken all necessary steps and precautions before upgrading from ArangoDB 1.2 to ArangoDB 1.3. Please also check @ref Upgrading13Troubleshooting.

Database Directory Version Check and Upgrade

Starting with ArangoDB 1.1, arangod will perform a database version check at startup. This has not changed in ArangoDB 1.3.

The version check will look for a file named VERSION in its database directory. If the file is not present, arangod in version 1.3 will perform an auto-upgrade (can also be considered a database "initialisation"). This auto-upgrade will create the system collections necessary to run ArangoDB, and it will also create the VERSION file with a version number like 1.3 inside.

If the VERSION file is present but is from a non-matching version of ArangoDB (e.g. ArangoDB 1.2 if you upgrade), arangod will refuse to start. Instead, it will ask you start the server with the option --upgrade. Using the --upgrade option will make the server trigger any required upgrade tasks to migrate data from ArangoDB 1.2 to ArangoDB 1.3.

This manual invocation of an upgrade shall ensure that users have full control over when they perform any updates/upgrades of their data, and do not risk running an incompatible tandem of server and database versions.

If you try starting an ArangoDB 1.3 server with a database created by an earlier version of ArangoDB, and did not invoke the upgrade procedure, the output of ArangoDB will look like this:

> bin/arangod --server.endpoint tcp://127.0.0.1:8529 --database.directory /tmp/12

...
2013-05-10T08:35:59Z [9017] ERROR Database directory version (1.2) is lower than server version (1.3).
2013-05-10T08:35:59Z [9017] ERROR It seems like you have upgraded the ArangoDB binary. If this is what you wanted to do, please restart with the --upgrade option to upgrade the data in the database directory.
2013-05-10T08:35:59Z [9017] FATAL Database version check failed. Please start the server with the --upgrade option
...

So it is really necessary to forcefully invoke the upgrade procedure. Please create a backup of your database directory before upgrading. Please also make sure that the database directory and all subdirectories and files in it are writeable for the user you run ArangoDB with.

As mentioned, invoking the upgrade procedure can be done by specifying the additional command line option --upgrade as follows:

> bin/arangod --server.endpoint tcp://127.0.0.1:8529 --database.directory /tmp/12 --upgrade

...
2013-05-10T08:38:41Z [9039] INFO Starting upgrade from version 1.2 to 1.3
2013-05-10T08:38:41Z [9039] INFO Found 20 defined task(s), 8 task(s) to run
...
2013-05-10T08:38:43Z [9039] INFO Upgrade successfully finished
2013-05-10T08:38:43Z [9039] INFO database version check passed
...

The upgrade procecure will execute the defined tasks to run arangod with all new features and data formats. It should normally run without problems and indicate success at its end. If it detects a problem that it cannot fix, it will halt on the first error and warn you.

Re-starting arangod with the --upgrade option will execute only the previously failed and not yet executed tasks.

Upgrading from ArangoDB 1.2 to ArangoDB 1.3 will rewrite data in the collections' datafiles. The upgrade procedure will create a backup of all files it processes, in case something goes wrong.

In case the upgrade did not produce any problems and ArangoDB works well for you after the upgrade, you may want to remove these backup files manually.

All collection datafiles will be backed up in the original collection directories in the database directory. You can easily detect the backup files because they have a filename ending in .old.

Upgrade a binary package

Linux:

  • Upgrade ArangoDB by package manager (Example zypper update arangodb)
  • check configuration file: /etc/arangodb/arangod.conf
  • Upgrade database files with /etc/init.d/arangodb upgrade

Mac OS X binary package

  • You can find the new Mac OS X packages here: http://www.arangodb.org/repositories/MacOSX
  • check configuration file: /etc/arangodb/arangod.conf
  • Upgrade database files `/usr/sbin/arangod --upgrade'

Mac OS X with homebrew

  • Upgrade ArangoDB by `brew upgrade arangodb'
  • check configuration file: /usr/local/Cellar/1.X.Y/etc/arangodb/arangod.conf
  • Upgrade database files /usr/local/sbin/arangod --upgrade

In case you upgrade from a previous version of ArangoDB, please make sure you perform the changes to the configuration file as described in @ref Upgrading13Options. Otherwise ArangoDB 1.3 will not start properly.

New and Changed Command-Line Options

In order to support node modules and packages, a new command-line option was introduced:

--javascript.package-path <directory>

must be used to specify the directory containing the NPM packages. This is option is presented in the pre-defined configuration files. In case a created your own configuration, you need to add this option and also make sure that

--javascript.modules-path <directories>

contains the new node directory.

Example values for --javascript.modules-path and --javascript.package-path are:

--javascript.modules-path = DIR/js/server/modules;DIR/js/common/modules;DIR/js/node

--javascript.package-path = DIR/js/npm

where DIR is the directory that contains the shared data installed by ArangoDB during installation. It might be /usr/local/share/arangodb, but the actual value is system-dependent.

Not adding the node directory to --javascript.modules-path or not setting --javascript.package-path will result in server startup errors.

The configuration options --scheduler.report-intervall and --dispatcher.report-intervall have been renamed to --scheduler.report-interval and --dispatcher.report-interval.

These are rarely used debugging options that are not contained in any of the configuration files shipped with ArangoDB, so the changed name should not have an effect for end users.

Removed Features

The configure options --enable-zone-debug and --enable-arangob have been removed. These should not have been used by end users anyway, so this change should not have an effect.

Troubleshooting

If the server does not start after an upgrade, please check that your configuration contains the node directory in the --javascript.modules-path, and that the parameter --javascript.package-path is set.

On systems with rlimit, ArangoDB 1.3 will also require the minimum number of file descriptors it can use to be 256. If the limit is set to a lower value, ArangoDB will try to increase the limit to 256. If raising the limit does fail, ArangoDB will refuse to start, and fail with an error message like

2013-05-10T09:00:40Z [11492] FATAL cannot raise the file descriptor limit to 256, got 'Operation not permitted'

In this case the number of file descriptors should be increased. Please note that 256 is a minimum value and that you should allow ArangoDB to use much more file descriptors if you afford it.

To avoid the file descriptor check on startup in an emergency case, you can use the startup option

--server.descriptors-minimum 0

Please also check the logfile written by ArangoDB for further errors messages.

@BNAVIGATE_Upgrading13