diff --git a/_posts/2026-02-12-1.2.0.md b/_posts/2026-02-12-1.2.0.md index 8b995daa..a4ff9171 100644 --- a/_posts/2026-02-12-1.2.0.md +++ b/_posts/2026-02-12-1.2.0.md @@ -21,7 +21,16 @@ To update to the latest version of InvenTree, please follow the updating instruc ### Django Update -[#10730](https://github.com/inventree/InvenTree/pull/10730) updated the core Django version to 5.2 lts. As part of this update, the minimum required python version has been increased to 3.11. +[#10730](https://github.com/inventree/InvenTree/pull/10730) updated the core Django version to 5.2 lts. + +As part of this update, the following breaking changes have been introduced: + +#### PostgreSQL 14 + +The minimum supported version of PostgreSQL has been increased to 14. This means that users running PostgreSQL 13 will need to perform a manual update of their database in order to continue using InvenTree with the latest version. For more information, please refer to our [update guide]({% link _posts/2026-02-12-db-update.md %}) for a walkthrough of the database update procedure. + +#### Python 3.11 +The minimum supported python version has been increased to 3.11. This means that users running Python 3.10 or earlier will need to update their python installation in order to run InvenTree 1.2.0. ### API changes diff --git a/_posts/2026-02-12-db-update.md b/_posts/2026-02-12-db-update.md new file mode 100644 index 00000000..8e4938e4 --- /dev/null +++ b/_posts/2026-02-12-db-update.md @@ -0,0 +1,136 @@ +--- +author: SchrodingersGat +title: Database Update Procedure +--- + +In our [recent 1.2.0 release]({% link _posts/2026-02-12-1.2.0.md %}), we updated our underlying [django](https://www.djangoproject.com/) version to from 4.2 to 5.2. + +For users running with a PostgreSQL database, Django 5.2 requires a minimum version of PostgreSQL 14. This means that users running PostgreSQL 13 will need to perform a manual update of their database in order to continue using InvenTree with the latest version. + +If you are attempting to update to InvenTree 1.2.0 while still running PostgreSQL 13, you will encounter the following error message: + +``` +django.db.utils.NotSupportedError: PostgreSQL 14 or later is required (found 13.23). +``` + +In such a case, you will need to perform a database update procedure to migrate your existing database from PostgreSQL 13 to PostgreSQL 14 (or later). This process involves backing up your existing database, installing the new version of PostgreSQL, and then restoring your data into the new database. + +## Migration Guide + +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. + +PostgreSQL 17 is recommended as the target version, as it is supported by both the 1.1.x and 1.2.x versions of InvenTree. + +## Starting Conditions + +The starting conditions for this migration are as follows: + +- InvenTree is installed via docker / docker compose (as per the [docker installation instructions](https://docs.inventree.org/en/stable/start/docker_install/)) +- The InvenTree version is pinned to 1.1.12 in the `.env` file +- The database is running PostgreSQL 13 (set via the `docker-compose.yml` file). + +![.env file](/assets/blog/db_update_env.png) + +![.docker-compose.yml file](/assets/blog/db_update_compose.png) + +We also have a data directory, external to the docker containers, with the following structure: + +![Data directory](/assets/blog/db_update_data.png) + +### Target Conditions + +The new installation will be running InvenTree 1.2.0 with PostgreSQL 17 + +## Step 1. Perform 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. + +First, let's confirm that we are running the expected version of InvenTree (1.1.12). + +![Old Setup](/assets/blog/db_update_old_versions.png) + +To perform the backup, we run the following command: + +``` +docker compose run --rm inventree-server invoke backup +``` + +This will create a backup of the database and media files in the `data/backup` directory. + +Confirm that the backup files have been created before continuing to the next step. + +## Step 2. 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. + +``` +mv data/pgdb 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. + +## Step 3. Update PostgreSQL Version + +Next, we need to update the PostgreSQL version in the `docker-compose.yml` file. Change the version from `13` to `17`: + +![Update PostgreSQL version](/assets/blog/db_update_new_postgres.png) + +Pull down the updated docker images: + +``` +docker compose pull +``` + +## Step 4. Restore Data from Backup + +Now we can restore the data from the backup we created previously, into the new PostgreSQL 17 database. Run the following commands: + +``` +docker compose run --rm inventree-server invoke migrate +docker compose run --rm inventree-server invoke restore +``` + +This will restore the database and media files from the backup we created previously. + +## Step 5. 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`: + +![Update InvenTree version](/assets/blog/db_update_new_inventree.png) + +Then, we need to pull down the updated InvenTree server image: + +``` +docker compose pull +``` + +Next, run the InvenTree update procedure: + +``` +docker compose run --rm inventree-server invoke update +``` + +## Step 6. Verify New Setup + +Finally, we can start the new setup and verify that everything is working as expected. + + +``` +docker compose up -d +``` + +Then, you should be able to access your InvenTree instance again, and confirm that you are running the new version (1.2.0): + +![New Setup](/assets/blog/db_update_new_versions.png) + +We can also see that the correct versions of both PostgreSQL and InvenTree are running in the docker containers: + +![Docker containers](/assets/blog/db_update_docker.png) + +## Step 7. 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. + +Please consider [sponsoring the project]({% link contribute.md %}#sponsor), to help us continue to maintain and improve InvenTree for all users. Your support is greatly appreciated! diff --git a/assets/blog/db_update_compose.png b/assets/blog/db_update_compose.png new file mode 100644 index 00000000..90a7208d Binary files /dev/null and b/assets/blog/db_update_compose.png differ diff --git a/assets/blog/db_update_data.png b/assets/blog/db_update_data.png new file mode 100644 index 00000000..76cde4ac Binary files /dev/null and b/assets/blog/db_update_data.png differ diff --git a/assets/blog/db_update_docker.png b/assets/blog/db_update_docker.png new file mode 100644 index 00000000..41b8e270 Binary files /dev/null and b/assets/blog/db_update_docker.png differ diff --git a/assets/blog/db_update_env.png b/assets/blog/db_update_env.png new file mode 100644 index 00000000..51ca5373 Binary files /dev/null and b/assets/blog/db_update_env.png differ diff --git a/assets/blog/db_update_new_inventree.png b/assets/blog/db_update_new_inventree.png new file mode 100644 index 00000000..3eb8c25e Binary files /dev/null and b/assets/blog/db_update_new_inventree.png differ diff --git a/assets/blog/db_update_new_postgres.png b/assets/blog/db_update_new_postgres.png new file mode 100644 index 00000000..040d1dcf Binary files /dev/null and b/assets/blog/db_update_new_postgres.png differ diff --git a/assets/blog/db_update_new_versions.png b/assets/blog/db_update_new_versions.png new file mode 100644 index 00000000..1068243d Binary files /dev/null and b/assets/blog/db_update_new_versions.png differ diff --git a/assets/blog/db_update_old_versions.png b/assets/blog/db_update_old_versions.png new file mode 100644 index 00000000..6e68d97b Binary files /dev/null and b/assets/blog/db_update_old_versions.png differ