Merge pull request #268 from rpkilby/migration-example

Resolves #255 - deprecate project, add migration example

Author: rpkilby

.github/workflows/main.yml

@@ -14,7 +14,7 @@ jobs:
     strategy:
       matrix:
         python-version: ["3.13"]
-        toxenv: ["dist", "lint", "warnings"]
+        toxenv: ["dist", "lint", "warnings", "migration-example"]
     continue-on-error: ${{ matrix.toxenv == 'warnings' }}
 
     steps:

.gitignore

@@ -9,3 +9,4 @@ dist/
 .env
 .env/
 .venv/
+*.sqlite3

README.rst

@@ -15,14 +15,33 @@ jsonfield
 **jsonfield** is a reusable model field that allows you to store validated JSON, automatically handling
 serialization to and from the database. To use, add ``jsonfield.JSONField`` to one of your models.
 
-**Warning!**
 
-    Django 3.1 `introduced`_ a native ``JSONField`` that supports all database backends. New projects should
-    preference Django's implemenation to ``jsonfield``, and existing users should migrate off of this package.
+Deprecation & Migration to Django's native ``JSONField``
+--------------------------------------------------------
+
+Django 3.1 `introduced`_ a native ``JSONField`` that supports all database backends. As such, this package is
+considered deprecated and will be archived in the future. Existing projects should migrate to Django's implemenation.
 
 .. _introduced: https://docs.djangoproject.com/en/stable/releases/3.1/#jsonfield-for-all-supported-database-backends
 
 
+Migrating from ``jsonfield.JSONField`` to ``models.JSONField`` *should* generally be straightforward. After swapping
+field classes, ``python manage.py migrate`` will generate ``AlterField`` operations that should correctly migrate
+your field data. However, if this does not work for your case, you will instead need to create a data migration.
+The process will roughly look like:
+
+* Rename ``<field>`` to ``old_<field>``, create migration.
+* Add a nullable ``<field> = models.JSONField(null=True, ...)``, create migration.
+* Create an empty migration file, add  ``RunPython`` operation that reserializes
+  the ``old_<field>`` data into the new ``<field>``.
+* Update ``<field>`` to not nullable, delete ``old_<field>``, create migration.
+* Manually combine the operations into a single migration file.
+
+Examples can be found in the `migration-example`_ project.
+
+.. _migration-example: https://github.com/rpkilby/jsonfield/tree/master/migration-example/
+
+
 Installation
 ------------
 

migration-example/manage.py

@@ -0,0 +1,24 @@
+#!/usr/bin/env python
+"""Django's command-line utility for administrative tasks."""
+import os
+import sys
+
+
+def main():
+    """Run administrative tasks."""
+    sys.path.append('src')
+    sys.path.append('tests')
+    os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'settings')
+    try:
+        from django.core.management import execute_from_command_line
+    except ImportError as exc:
+        raise ImportError(
+            "Couldn't import Django. Are you sure it's installed and "
+            "available on your PYTHONPATH environment variable? Did you "
+            "forget to activate a virtual environment?"
+        ) from exc
+    execute_from_command_line(sys.argv)
+
+
+if __name__ == '__main__':
+    main()

migration-example/src/alterfield/__init__.py

@@ -0,0 +1,31 @@
+# Generated by Django 5.2.4 on 2025-07-04 21:22
+
+import jsonfield.fields
+from django.db import migrations, models
+
+
+def populate(apps, schema_editor):
+    AlterFieldModel = apps.get_model('alterfield', 'AlterFieldModel')
+
+    AlterFieldModel.objects.create(data=1)
+    AlterFieldModel.objects.create(data="foobar")
+    AlterFieldModel.objects.create(data={"foo": "bar"})
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='AlterFieldModel',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('data', jsonfield.fields.JSONField()),
+            ],
+        ),
+        migrations.RunPython(populate, migrations.RunPython.noop)
+    ]

migration-example/src/alterfield/migrations/0001_initial.py

@@ -0,0 +1,18 @@
+# Generated by Django 5.2.4 on 2025-07-04 21:51
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('alterfield', '0001_initial'),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name='alterfieldmodel',
+            name='data',
+            field=models.JSONField(),
+        ),
+    ]

migration-example/src/alterfield/migrations/0002_alter_alterfieldmodel_data.py

@@ -0,0 +1,5 @@
+from django.db import models
+
+
+class AlterFieldModel(models.Model):
+    data = models.JSONField()