Upgrading to ArangoDB 3.0

Please read the following sections if you upgrade from a previousversion to ArangoDB 3.0. Please be sure that you have checked the listof changes in 3.0 beforeupgrading.

Migrating databases and collections from ArangoDB 2.8 to 3.0

ArangoDB 3.0 does not provide an automatic update mechanism for databasedirectories created with the 2.x branches of ArangoDB.

In order to migrate data from ArangoDB 2.8 (or an older 2.x version) intoArangoDB 3.0, it is necessary to export the data from 2.8 using arangodump,and then import the dump into a fresh ArangoDB 3.0 with arangorestore.

To do this, first run the 2.8 version of arangodump to export the databasedata into a directory. arangodump will dump the _system database by default.In order to make it dump multiple databases, it needs to be invoked once persource database, e.g.

  1. # in 2.8
  2. arangodump --server.database _system --output-directory dump-system
  3. arangodump --server.database mydb --output-directory dump-mydb
  4. ...

That will produce a dump directory for each database that arangodump iscalled for. If the server has authentication turned on, it may be necessary toprovide the required credentials when invoking arangodump, e.g.

  1. arangodump --server.database _system --server.username myuser --server.password mypasswd --output-directory dump-system

The dumps produced by arangodump can now be imported into ArangoDB 3.0 usingthe 3.0 version of arangodump:

  1. # in 3.0
  2. arangorestore --server.database _system --input-directory dump-system
  3. arangorestore --server.database mydb --input-directory dump-mydb
  4. ...

arangorestore will by default fail if the target database does not exist. It canbe told to create it automatically using the option —create-database true:

  1. arangorestore --server.database mydb --create-database true --input-directory dump-mydb

And again it may be required to provide access credentials when invokingarangorestore:

  1. arangorestore --server.database mydb --create-database true --server.username myuser --server.password mypasswd --input-directory dump-system

Please note that the version of dump/restore should match the server version, i.e.it is required to dump the original data with the 2.8 version of arangodumpand restore it with the 3.0 version of arangorestore.

After that the 3.0 instance of ArangoDB will contain the databases and collectionsthat were present in the 2.8 instance.

Adjusting authentication info

Authentication information was stored per database in ArangoDB 2.8, meaning therecould be different users and access credentials per database. In 3.0, the users arestored in a central location in the _system database. To use the same user setupas in 2.8, it may be required to create extra users and/or adjust their permissions.

In order to do that, please connect to the 3.0 instance with an ArangoShell (thiswill connect to the _system database by default):

  1. arangosh --server.username myuser --server.password mypasswd

Use the following commands to create a new user with some password and grant themaccess to a specific database

  1. require("@arangodb/users").save(username, password, true);
  2. require("@arangodb/users").grantDatabase(username, databaseName, "rw");

For example, to create a user myuser with password mypasswd and give themaccess to databases mydb1 and mydb2, the commands would look as follows:

  1. require("@arangodb/users").save("myuser", "mypasswd", true);
  2. require("@arangodb/users").grantDatabase("myuser", "mydb1", "rw");
  3. require("@arangodb/users").grantDatabase("myuser", "mydb2", "rw");

Existing users can also be updated, removed or listed using the followingcommands:

  1. /* update user myuser with password mypasswd */
  2. require("@arangodb/users").update("myuser", "mypasswd", true);
  4. /* remove user myuser */
  5. require("@arangodb/users").remove("myuser");
  7. /* list all users */
  8. require("@arangodb/users").all();

Foxx applications

The dump/restore procedure described above will not export and re-import Foxx applications.In order to move these from 2.8 to 3.0, Foxx applications should be exported as zip filesvia the 2.8 web interface.

The zip files can then be uploaded in the “Services” section in the ArangoDB 3.0 web interface.Applications may need to be adjusted manually to run in 3.0. Please consult themigration guide for Foxx apps.

An alternative way of moving Foxx apps into 3.0 is to copy the source directory of a 2.8 Foxxapplication manually into the 3.0 Foxx apps directory for the target database (which is normally/var/lib/arangodb3-apps/_db/<dbname>/ but the exact location is platform-specific).