Background

In this article, we will share how to upgrade the dj-stripe package flawlessly and carefully.

As we know, dj-stripe always squashes the migration files, which means its migration files are completely changed, and leading to migration issues.

So, you can’t immediately upgrade your package too far, for example, from 2.4.0 to 2.7.0,
because it will cause breaking changes, especially in your database migrations.

How to do it?

For example, if your dj-stripe version is 2.4.0 and your migration files are referring to the old version.

First, you need to find which version has that old migration. For example:

1. Search for the latest version that is closest to your package version, for example: 2.4.0 to 2.5.0.
2. Visit this link to find it: https://github.com/dj-stripe/dj-stripe/tags.
3. Cross-check the release notes.
4. Find which dj-stripe version is still compatible with your migration file, for example: 0006_2_3.py.
5. Find the last migration file of the latest version at https://github.com/dj-stripe/dj-stripe/tree/2.5.0/djstripe/migrations (for example: 0008_2_5.py) (both files must exist; if not, it means the new version is no longer compatible with your version).

Old Migration	New Migration

1. Update your requirements.txt file from dj-stripe==2.4.0 to dj-stripe==2.5.0
2. Run the manage.py migrate djstripe command (this command must not fail; if it does, cross-check steps 1-6).

(env-my-project) ➜  my-project git:(development) ✗ docker-compose -f local.yml run django python manage.py migrate djstripe
[+] Creating 3/0
 ✔ Container my-project-redis-1     Running                                                                                                                                                                                  0.0s
 ✔ Container my-project-mailhog-1   Running                                                                                                                                                                                  0.0s
 ✔ Container my-project-postgres-1  Running                                                                                                                                                                                  0.0s
PostgreSQL is available
System check identified some issues:

WARNINGS:
?: (djstripe.W001) The Stripe API version has a non-default value of '2024-04-10'. Non-default versions are not explicitly supported, and may cause compatibility issues.
	HINT: Use the dj-stripe default for Stripe API version: 2020-08-27
Operations to perform:
  Apply all migrations: djstripe
Running migrations:
  Applying djstripe.0008_2_5... OK

1. And then, after migrating it, change your migration file to refer to the new version (e.g., from 0006_2_3 to 0008_2_5).

1. Repeat the same process for higher version.

If you have an issue with the Stripe version, we can also try upgrading it in the requirements.txt file.
Check out this issue for more information: https://github.com/dj-stripe/dj-stripe/issues/1842#issuecomment-1319185657.

stripe>=4.0.0,<5.0.0  # https://github.com/dj-stripe/dj-stripe/issues/1842#issuecomment-1319185657

Conclusion

1. Find the closest version that compatible with your version (for doing migration).
2. Update the dependency in requirements.txt file and then deploy it.
   • Don’t forget to run the python manage.py migrate djstripe command.
3. Change your migration file to refer to the new version (e.g., from 0006_2_3 to 0008_2_5), and then deploy it.

Alternatives

• https://stackoverflow.com/a/31122841