Add opt-in Database(deserialize_json=True) to parse JSON strings back into dict/list on read

Values inserted as dict/list are serialized to JSON TEXT columns, but rows
fetched via .rows/.rows_where()/.get()/.search()/.query() previously always
came back as raw strings. This adds an opt-in constructor flag that parses
any string value that looks like a JSON object or array back into a
dict/list, without changing the default (raw string) behavior.

Fixes #612
This commit is contained in:
Parker Gurney 2026-08-05 14:23:56 -07:00
commit 064625da59
3 changed files with 67 additions and 5 deletions

View file

@ -2287,6 +2287,21 @@ For example:
""").fetchall()
# Returns [('Felton, CA',)]
Values read back out through the Python API - via ``.rows``, ``.rows_where()``, ``.get()``,
``.search()`` or ``.query()`` - come back as the raw JSON string that was stored, not as a
``dict`` or ``list``, since that is the value SQLite actually returned. Pass
``deserialize_json=True`` to the ``Database()`` constructor to opt in to automatically parsing
any string value that looks like a JSON object or array back into a ``dict`` or ``list``:
.. code-block:: python
db = sqlite_utils.Database("museums.db", deserialize_json=True)
print(db["niche_museums"].get(1))
# {'id': 1, 'name': 'The Bigfoot Discovery Museum', ..., 'hours': {'Monday': [11, 18], ...}}
This defaults to ``False``, so existing code that expects raw strings continues to work
unchanged.
.. _python_api_conversions:
Converting column values using SQL functions