Skip to content

Conversation

@Mostafa-Wael-Elsahity
Copy link

@Mostafa-Wael-Elsahity Mostafa-Wael-Elsahity commented Dec 18, 2025

Add automatic JSON deserialization support

This PR implements automatic JSON deserialization for columns declared with the JSON type, as requested in #612. It introduces a new use_json_converters=True option that allows the library to automatically handle nested Python structures (dictionaries, lists, and tuples) by storing them in JSON columns and deserializing them back into native Python objects upon retrieval.

Key Changes

  • Database Constructor: Added a use_json_converters: bool = False argument. When enabled:
    • Registers a custom SQLite converter for the JSON type using json.loads.
    • Enables sqlite3.PARSE_DECLTYPES on the connection.
    • Updates COLUMN_TYPE_MAPPING to include "JSON": "JSON".
  • Type Inference: Modified suggest_column_types (and types_for_column_types) to accept a json_converters parameter. If True, nested structures are inferred as dict or list (mapping to JSON) rather than str.
  • CLI Commands: Added a --use-json-converters flag to the following commands:
    • query
    • memory
    • insert
    • upsert
    • bulk
  • create-table Support: The create-table CLI command and Table.create() API now explicitly support "JSON" (case-insensitive) as a valid column type.

Validation

  • New Tests:
    • Added tests/test_issue_612.py to test the Python API behavior, including round-trip serialization/deserialization, type inference, and edge cases (null values, malformed JSON).
    • Added tests/test_cli_json_converters.py to verify the new CLI flags and JSON type support.
  • Regression Testing: Ran the full test suite (1,072 tests), and all passed.
  • Linting & Types: Verified that the codebase passes black, flake8, and mypy checks.

Documentation

  • Updated docs/python-api.rst to document the new Database argument.
  • Updated docs/cli.rst to document the new --use-json-converters flag and the JSON type for create-table.
  • Added a changelog entry for the upcoming 3.40 release in docs/changelog.rst.

Closes #612


📚 Documentation preview 📚: https://sqlite-utils--698.org.readthedocs.build/en/698/

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Automatic JSON de-serialization

1 participant