Migrations

Migrations are executed following the initial invocation of fm any fm subcommand after updating fm.

Manual Migration Procedure

When the benches have been archived then you can use the following migration guide to migrate a bench.

`v0.11.0 - v0.13.4`

Create a template bench with the same name as the previous one.
```
fm create frappe.localhost --template
```
Replace the workspace directory from the previous bench with the one from the new bench.
Verify whether the environment variables match those in the previous bench docker-compose.yml file.
Start the bench.
```
fm start frappe.localhost 
```

Your bench should now be successfully migrated.

`v0.10.0`

If you need to manually migrate your bench, follow these steps:

Navigate to your bench directory. For example, if you want to migrate the bench frappe.localhost located at ~/frappe/archived/frappe.localhost.
```
cd ~/frappe/archived/frappe.localhost
```
Start the Docker Compose project using the following command. Ignore nginx container port bind issues.
```
docker compose up -d
```

Open a shell in the frappe container with the specified user and working directory.

docker compose exec --user frappe --workdir /workspace/frappe-bench frappe bash

Change the directory to /workspace/frappe-bench and run the command to take a backup.
```
bench --site <benchname> backup
```
Ensure that the backup is successfully created in the directory /workspace/frappe-bench/sites/<benchname>/private/backup and contains the required data.
Remove all containers and volumes.

This command will delete MariaDB data as well. To prevent this, exclude the -v option from the command.
```
docker compose down -v
```
Create a template bench with the same name as the previous one.
```
fm create frappe.localhost --template
```
Replace the workspace directory from the previous bench with the one from the new bench.
Start the bench.
```
fm start frappe.localhost 
```
Retrieve the required global-db info and bench db-info using the command.
```
fm info frappe.localhost
```
Note down the global database password (GLOBAL_DB_PASS), user (GLOBAL_DB_USER), bench database user (SITE_DB_USER), database password (SITE_DB_PASS), and database name (SITE_DB_NAME).
Open the shell of the bench:
```
fm shell frappe.localhost
```

Set up the database using the gathered information.

# Set up variables using the info from step 9.

GLOBAL_DB_USER='REPLACE_ME_WITH_GLOBAL_DB_USER'
GLOBAL_DB_PASS='REPLACE_ME_WITH_GLOBAL_DB_PASS'
SITE_DB_NAME='REPLACE_ME_WITH_SITE_DB_NAME'
SITE_DB_USER='REPLACE_ME_WITH_SITE_DB_USER'
SITE_DB_PASS='REPLACE_ME_WITH_SITE_DB_PASS'
SITE_DB_SQL_GZ_PATH='REPLACE_ME_WITH_SITE_DB_SQL_GZ_PATH'
# path should look like this   /workspace/frappe-bench/sites/frappe.localhost/private/backups/20240205_153643-frappe_localhost-database.sql.gz
SITE_DB_SQL_PATH='REPLACE_ME_WITH_SITE_DB_SQL_PATH'

# Gunzip the database

gunzip $SITE_DB_SQL_GZ_PATH

# Create the database

/usr/bin/mariadb -u"$GLOBAL_DB_USER" -p"$GLOBAL_DB_PASS" -h'global-db' -P3306 -e 'CREATE DATABASE IF NOT EXISTS `'"$SITE_DB_NAME"'`;'

# Create the user

/usr/bin/mariadb -u"$GLOBAL_DB_USER" -p"$GLOBAL_DB_PASS" -h'global-db' -P3306 -e 'CREATE USER `'"$SITE_DB_USER"'`@`%` IDENTIFIED BY "'"$SITE_DB_PASS"'";'

# Grant all privileges to the newly created user for the created database

/usr/bin/mariadb -u"$GLOBAL_DB_USER" -p"$GLOBAL_DB_PASS" -h'global-db' -P3306 -e 'GRANT ALL PRIVILEGES ON `'"$SITE_DB_NAME"'`.* TO `'"$SITE_DB_USER"'`@`%`;'

# Import the database

/usr/bin/mariadb -u"$SITE_DB_USER" -p"$SITE_DB_PASS" -h'global-db' -P3306 $SITE_DB_NAME < $SITE_DB_SQL_PATH