Changes between Version 3 and Version 4 of JSON1Extension

Timestamp:

Aug 14, 2020, 2:29:04 AM (5 years ago)

Author:

Sage Abdullah

Comment:

Add workaround by dynamically loading the extension

JSON1Extension

@@ -8 +8 @@
 on Python's `sqlite3`__ library. If the extension is not enabled on your installation, a system error
 (``fields.E180``) will be raised. To check if the extension is enabled on your installation, you can
-do a query with one of the functions included in the extension, e.g. ``JSON()``. For example::
+do a query with one of the functions included in the extension, e.g. ``JSON()``. For example:
+
+.. code-block:: python
 
     >>> import sqlite3
@@ -27 +29 @@
 packages and enabled by default. If that's not the case on your installation, then do the following:
 
-- Download the `SQLite amalgamation`__, with or without the configuration script.
+- Download the `SQLite amalgamation`_, with or without the configuration script.
 - Extract the source code archive and enter the directory of the result.
 - Compile the source code using the ``-DSQLITE_ENABLE_JSON1`` flag to enable the JSON1
@@ -47 +49 @@
 - Now, the JSON1 extension should be ready to be used in Python and Django.
 
-.. __: https://www.sqlite.org/download.html
+.. _SQLite amalgamation: https://www.sqlite.org/download.html
 .. __: https://www.sqlite.org/howtocompile.html
 
@@ -83 +85 @@
 .. __: https://www.sqlite.org/download.html
 
+Other workarounds
+=================
+
+Load the JSON1 extension dynamically
+------------------------------------
+
+The following workaround works by compiling the JSON1 extension as a loadable extension
+and loading it when the database connection is created by utilizing Django's |connection_created|__
+signal. It hasn't been tested, but it should work on Linux, macOS, and Windows.
+
+.. |connection_created| replace:: ``connection_created``
+.. __: https://docs.djangoproject.com/en/3.1/ref/signals/#connection-created
+
+- Download the `SQLite amalgamation`_, with or without the configuration script.
+- Extract the source code archive and enter the directory of the result.
+- Follow the instructions to `compile a loadable extension`__ according to your operating system,
+  but replace the ``YourCode.c`` placeholder to point to ``ext/misc/json1.c``.
+
+  For example, on Linux it would be::
+
+    gcc -g -fPIC -shared ext/misc/json1.c -o json1.so
+
+  On macOS, it would be::
+
+    gcc -g -fPIC -dynamiclib ext/misc/json1.c -o json1.dylib
+
+  On Windows with MSVC, it would be::
+
+    cl ext/misc/json1.c -link -dll -out:json1.dll
+
+  On Windows with MinGW, it would be::
+
+    gcc -g -shared ext/misc/json1.c -o json1.dll
+
+.. __: https://www.sqlite.org/loadext.html#compiling_a_loadable_extension
+
+- Place the compiled JSON1 extension somewhere desirable.
+- Create a signal handler for the ``connection_created`` signal. For example:
+
+  .. code-block:: python
+
+    def load_json1(connection, **kwargs):
+        if connection.vendor != 'sqlite':
+            return
+        connection.connection.enable_load_extension(True)
+        connection.connection.load_extension('./json1')
+
+  You should replace ``'./json1'`` if your compiled extension is stored under a different directory.
+
+- Connect the receiver function in one of your apps' ``ready()`` function.
+
+  .. code-block:: python
+
+    class MyAppConfig(AppConfig):
+        # ...
+
+        def ready(self):
+            connection_created.connect(load_json1)
+
+  You can also connect the function using the ``@receiver`` decorator. For more information,
+  read the docs on how to `connect receiver functions`__.
+
+.. __: https://docs.djangoproject.com/en/3.1/topics/signals/#connecting-receiver-functions
 }}}