Changes between Initial Version and Version 1 of JSON1Extension

Timestamp:

May 5, 2020, 4:25:08 AM (4 years ago)

Author:

Mariusz Felisiak

Comment:

Enabling JSON1 extension on SQLite.

JSON1Extension

@@ +1 @@
+{{{
+#!text/x-rst
+==================================
+Enabling JSON1 extension on SQLite
+==================================
+
+To use **django.db.models.JSONField** on SQLite, you need to enable the `JSON1 extension`__ 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::
+
+    >>> import sqlite3
+    >>> conn = sqlite3.connect(':memory:')
+    >>> cursor = conn.cursor()
+    >>> cursor.execute('SELECT JSON(\'{"a": "b"}\')')
+
+If the query doesn't throw any errors, then the JSON1 extension is already enabled. Otherwise, follow the instructions below according to your operating system to set it up correctly.
+
+.. __: https://www.sqlite.org/json1.html
+.. __: https://docs.python.org/3/library/sqlite3.html#module-sqlite3
+
+Linux
+=====
+
+On most major Linux distributions, the JSON1 extension is included in their SQLite and/or Python 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.
+- 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 extension. For example::
+
+    gcc -DSQLITE_ENABLE_JSON1 -c -fPIC sqlite3.c
+
+  To enable other extensions, see the `compilation instructions`__.
+- Create a shared library. For example::
+
+    gcc -shared -o libsqlite3.so -fPIC sqlite3.o -ldl -lpthread
+
+- Place the resulting file (`libsqlite3.so`) in a desired directory, e.g. `/usr/lib/sqlite3/`.
+- Set the `LD_PRELOAD` environment variable to use your compiled SQLite every time you run Django. For example::
+
+    export LD_PRELOAD=/usr/lib/sqlite3/libsqlite3.so
+
+- Now, the JSON1 extension should be ready to be used in Python and Django.
+
+.. __: https://www.sqlite.org/download.html
+.. __: https://www.sqlite.org/howtocompile.html
+
+macOS
+=====
+
+On macOS, follow the instructions for Linux above, but instead of setting the `LD_PRELOAD` environment variable, use `DYLD_LIBRARY_PATH`. For example::
+
+    export DYLD_LIBRARY_PATH=/usr/lib/sqlite3
+
+Windows
+=======
+
+- Download the `precompiled DLL`__ that matches your Python installation (32-bit or 64-bit).
+- Locate your Python installation. By default, it should be in `%localappdata%\Programs\Python\PythonXX`, where `XX` is the Python version. For example, it's located in `C:\Users\<username>\AppData\Local\Programs\Python\Python37`. If you added Python installation directory to your ``PATH`` environment variable, you can run the command `where python` on a command prompt to locate it.
+- Enter the `DLLs` directory in your Python installation.
+- Rename (or delete) `sqlite3.dll` inside the `DLLs` directory.
+- Extract `sqlite3.dll` from the downloaded DLL archive and put it in the `DLLs` directory.
+- Now, the JSON1 extension should be ready to be used in Python and Django.
+
+.. __: https://www.sqlite.org/download.html
+
+}}}