Migration

This guide explains how to use the asreview migrate command to ensure your database or projects are compatible with the latest stable version of ASReview, specifically for migrating from version 1 (v1) to version 2 (v2).

Migration Steps Version 1 to Version 2

Follow these two steps to complete the migration process:

Step 1: Backing Up Before Migration

Before starting the migration, it is recommended to back up both the database and the projects folder. This precaution prevents data loss and provides a recovery point in case of errors.

Backing up the default SQLite3 database can be done by copying the database file to a different location:

cp /home/username/.asreview/asreview.production.sqlite /home/username/new_folder

The project files are located in the dedicated ASReview folder. To create a copy of all files recursively:

cp -r /home/username/.asreview /home/username/new_folder

For server administrators using the ASReview Lab Docker stack, backing up the projects and database requires executing commands within the running Docker containers.

To start, identify the active containers:

docker ps --format "{{.Names}}"

Example output:

asreview-server-stack-server-1
asreview-server-stack-asreview-1
asreview-server-stack-database-1

Back up the PostgreSQL database using the following command:

docker exec -u postgres asreview-server-stack-database-1 pg_dump asreview_db > /home/username/new_folder/asreview.backup.sql

To back up all project files, copy the contents of the project_folder volume from the container to the host system:

docker cp asreview-server-stack-asreview-1:/project_folder /home/username/new_folder/asreview-projects-backup

Step 2: Migrate the Database

The first step is to migrate the database, which includes user profiles and other related data.

Run the following command to migrate the database:

asreview migrate --db

If you are using a custom database URI, specify the URI of the database.

asreview migrate --db --db-uri sqlite:///custom_database.sqlite

By default, the value is taken from the environment variable ASREVIEW_LAB_SQLALCHEMY_DATABASE_URI. If not set, the default is asreview.production.sqlite in the ASReview folder.

Server administrators using the ASReview Lab Docker stack should run the migration command inside the Docker container. For example:

docker exec -it asreview-server-stack-asreview-1 asreview migrate --db

Step 3: Migrate the Projects

After migrating the database, proceed to migrate the projects format.

Run the following command:

asreview migrate --projects

This ensures that all your projects are updated to the latest compatible format.

To perform the project migration within the ASReview Lab Docker stack, run the following command inside the container:

docker exec -it asreview-server-stack-asreview-1 asreview migrate --projects