Update migration guide (#264)

Ref: https://github.com/inventree/InvenTree/issues/11338

_posts/2026-02-12-db-update.md

@@ -17,6 +17,8 @@ In such a case, you will need to perform a database update procedure to migrate
 
 ## Migration Guide
 
+*Note: This procedure was updated on 2026-02-19*
+
 Our documentation provides a detailed [database migration guide](https://docs.inventree.org/en/stable/start/migrate/#migrating-between-incompatible-database-versions) to assist users with this process. We recommend that users perform a backup of their database before attempting the migration, and follow the instructions carefully to ensure a smooth transition to the new database version.
 
 Following is an example of the steps involved in migrating an InvenTree installation from a PostgreSQL 13 database to a PostgreSQL 17 database, in the context of a docker installation. The same principles apply for non-docker installations, but the particular commands may differ.
@@ -43,7 +45,23 @@ We also have a data directory, external to the docker containers, with the follo
 
 The new installation will be running InvenTree 1.2.0 with PostgreSQL 17
 
-## Step 1. Perform Backup
+### Data Backup
+
+It is prudent to perform a regular backup of the database, before following the migration procedure. This can be done using the `invoke backup` command, as described in the documentation. This will create a backup of the database and media files in the `data/backup` directory.
+
+## Step 1. Ensure Starting Conditions are Met
+
+- `postgres:13` is set in `docker-compose.yml`
+- `INVENTREE_VERSION=1.1.12` is set in `.env`
+- Database schema has been updated to the latest version:
+
+```
+docker compose up inventree-db -d
+docker compose run --rm inventree-server invoke update
+docker compose down
+```
+
+## Step 2. Perform Manual Backup
 
 The first step is to perform a backup of the existing database. This step must be performed with the old setup (postgres 13 / InvenTree 1.1.12), before we perform any updates to the software.
 
@@ -55,27 +73,31 @@ To perform the backup, we run the following commands:
 
 ```
 docker compose up inventree-db -d
-docker compose run --rm inventree-server invoke backup
+docker compose run --rm inventree-server pg_dump postgresql://pguser@inventree-db:5432/inventree -f /home/inventree/data/backup/db_migrations.sql
 docker compose down
 ```
 
-This will create a backup of the database and media files in the `data/backup` directory.
+*Note: You will be prompted for the password for the `pguser` user. This is the password that you set in the `.env` file (default is `pgpassword`).*
+
+*Note: Do not change the path to the migrations file, this is the internal docker container path, and should not be changed.*
+
+This will create a backup of the database and media files in the `inventree-data/backup` directory (external to the docker containers). The database backup will be saved as `db_migrations.sql`.
 
 Confirm that the backup files have been created before continuing to the next step.
 
-## Step 2. Move Database Directory
+## Step 3. Move Database Directory
 
-The PostgreSQL database files are stored in the `data/pgdb` directory. We need to remove these files, as they are specific to PostgreSQL 13 and will not be compatible with PostgreSQL 17. Rather than deleting them, we will move them to a backup location, just in case we need to revert back to the old setup.
+The PostgreSQL database files are stored in the `inventree-data/pgdb` directory. We need to remove these files, as they are specific to PostgreSQL 13 and will not be compatible with PostgreSQL 17. Rather than deleting them, we will move them to a backup location, just in case we need to revert back to the old setup.
 
 ```
-mv data/pgdb data/pgdb_backup
+mv inventree-data/pgdb inventree-data/pgdb_backup
 ```
 
-Confirm that the `pgdb` directory has been moved to the backup location before continuing to the next step. The `pgdb` directory should no longer exist in the `data` directory.
+Confirm that the `pgdb` directory has been moved to the backup location before continuing to the next step. The `pgdb` directory should no longer exist in the `inventree-data` directory.
 
-## Step 3. Update PostgreSQL Version
+## Step 4. Update PostgreSQL Version
 
-Next, we need to update the PostgreSQL version in the `docker-compose.yml` file. Change the version from `13` to `17`:
+Next, we need to update the PostgreSQL version in the `docker-compose.yml` file. Change the version from `postgres:13` to `postgres:17`:
 
 ![Update PostgreSQL version](/assets/blog/db_update_new_postgres.png)
 
@@ -91,14 +113,27 @@ Now we can restore the data from the backup we created previously, into the new
 
 ```
 docker compose up inventree-db -d
-docker compose run --rm inventree-server invoke migrate
+docker compose run --rm inventree-server psql postgresql://pguser@inventree-db:5432/inventree -f /home/inventree/data/backup/db_migrations.sql
-docker compose run --rm inventree-server invoke restore
 docker compose down
 ```
 
 This will restore the database and media files from the backup we created previously.
 
-## Step 5. Update InvenTree Version
+## Step 5. Verify Database Update
+
+Launch the InvenTree server, and confirm that you can still access your data via the web interface.
+
+```
+docker compose up -d
+```
+
+Once you have confirmed that the data is accessible, you can stop the server again:
+
+```
+docker compose down
+```
+
+## Step 6. Update InvenTree Version
 
 Next, we need to update the InvenTree version in the `.env` file. Change the version from `1.1.12` to `1.2.0`:
 
@@ -117,7 +152,7 @@ docker compose up inventree-db -d
 docker compose run --rm inventree-server invoke update
 ```
 
-## Step 6. Verify New Setup
+## Step 7. Verify New Setup
 
 Finally, we can start the new setup and verify that everything is working as expected.
 
@@ -134,7 +169,7 @@ We can also see that the correct versions of both PostgreSQL and InvenTree are r
 
 ![Docker containers](/assets/blog/db_update_docker.png)
 
-## Step 7. Celebrate!
+## Step 8. Celebrate!
 
 Congratulations! You have successfully migrated your InvenTree installation to the latest version, with an updated PostgreSQL database. You can now enjoy the new features and improvements that come with InvenTree 1.2.0, while also benefiting from the enhanced performance and security of PostgreSQL 17.