Migrating Data from v3 to v4

Upgrading your Arches installation is a complex process, as a significant backend redesign was implemented in v4. We have developed the following documentation (and the code to support it) to guide you through the process. You will be performing a combination of shell commands and basic file manipulation.

Before migrating data, you’ll need to install Arches 4 and make a new project. You can name your project whatever you want, but throughout this documentation we’ll refer to it as my_project. You can customize the templates and images in your project any time (before or after migrating the data). We recommend adding a Mapbox key right away so you can use the map for visual checks during the migration.

See also

Refer to Installation and Projects and Packages for more about how to create an Arches 4 project.

Before moving on, you must be able to run the Django devserver from your v4 project, and view it in a browser at http://localhost:8000.

Once you are ready, you can begin the migration process. The overall form of the process goes like this:

  • Export data from existing v3 Arches installation
  • Create a v4 package (Arches-HIP users: this is already done for you)
  • Place the v3 data into the Package directories
  • Run commands to convert the v3 data to v4 data
  • Load the package into any v4 project

We have further documented this workflow with two step-by-step guides: one for v3 users who are using Arches-HIP, and one for those who have created custom packages. You’ll find these guides below.

Exporting Your Data From v3

Before migrating to v4, you must export all of your data from v3. Before you begin, however, you’ll need to install some enhanced commands into your v3 app. This is a simple process:

  1. Download and unzip arches3-export-utils-master.zip (source)
  2. Copy the “management” directory into your v3 app alongside the settings.py file.
  3. In your v3 environment, run python manage.py v3v4 --help to make sure the new commands have been been installed.

Warning

Be sure to backup your v3 database before beginning the export process.

Now you are ready to begin exporting your data from v3. Follow these steps:

After you have all the v3 data exported, you are ready to follow the appropriate workflow for your deployment.

Migrating Your Data

The workflow you must use for the migration depends on the nature of your v3 deployment.

Arches-HIP App

If your v3 deployment of Arches was based on Arches-HIP, and you did not modify any of the graphs (beyond perhaps changing node names) you can use the Arches-HIP Workflow. If you have changed the RDM content that’s fine, it will be preserved through the migration.