ArangoDB Manual Pages
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 Troubleshooting.
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
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  ERROR Database directory version (1.2) is lower than server version (1.3). 2013-05-10T08:35:59Z  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  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  INFO Starting upgrade from version 1.2 to 1.3 2013-05-10T08:38:41Z  INFO Found 20 defined task(s), 8 task(s) to run ... 2013-05-10T08:38:43Z  INFO Upgrade successfully finished 2013-05-10T08:38:43Z  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
- Upgrade ArangoDB by package manager (Example
zypper update arangodb)
- check configuration file:
- Upgrade database files with
Mac OS X binary package
- You can find the new Mac OS X packages here:
- check configuration file:
- Upgrade database files `/usr/sbin/arangod –upgrade'
Mac OS X with homebrew
- Upgrade ArangoDB by `brew upgrade arangodb'
- check configuration file:
- Upgrade database files
In case you upgrade from a previous version of ArangoDB, please make sure you perform the changes to the configuration file as described in New and Changed Command-Line Options. Otherwise ArangoDB 1.3 will not start properly.
In order to support node modules and packages, a new command-line option was introduced:
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
contains the new
Example values for
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
The configuration options
--dispatcher.report-intervall have been renamed to
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.
The configure options
--enable-arangob have been removed. These should not have been used by end users anyway, so this change should not have an effect.
If the server does not start after an upgrade, please check that your configuration contains the
node directory in the
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  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
Please also check the logfile written by ArangoDB for further errors messages.