---
id: sqlalchemy-jsonfield
version: "1.0.3"
license: Apache-2.0
license_treatment: permissive
maintenance: active
---

# SQLAlchemy-JSONField — SQLALchemy JSONField implementation for storing dicts at SQL

License: permissive · Maintenance: active · Downloads: 6.0M/mo

## What it is and what it does

SQLAlchemy-JSONField is a custom column type that abstracts away database-specific JSON handling differences. It lets you store Python dictionaries as JSON in your SQLAlchemy models while automatically choosing between native JSON support (PostgreSQL, modern MySQL, SQLite 3.9+) and text-encoded fallback (MariaDB, Percona, older SQLite). The package handles encoding/decoding transparently and lets you swap JSON libraries (e.g., ujson instead of the standard library json) or enforce string encoding when your database connector has Unicode limitations.

The main problem it solves is the fragmentation across test and production environments: you might test on SQLite but deploy on MySQL or PostgreSQL, and each has different JSON capabilities. Rather than writing conditional logic in your models, you define the field once with optional parameters like `enforce_string` and `enforce_unicode`, and the package adapts to whatever database is actually running.

Use it for:

- Store semi-structured data (nested dicts, lists) in SQLite during testing, then use native JSON in PostgreSQL production without code changes.
- Work around MariaDB's lack of native JSON support by automatically encoding to text while managing Unicode correctly.
- Use a faster JSON library like ujson for serialization/deserialization by passing it to the JSONField constructor.
- Migrate gradually from text-encoded JSON to native JSON as database versions are upgraded, without rewriting model definitions.
- Support multiple database backends in a single codebase where some have JSON and others require text fallback.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Provides a SQLAlchemy column type for storing dictionaries as JSON, with automatic fallback to text encoding for databases that lack native JSON support.

Yes. The package solves a real cross-database compatibility problem with low install friction (one dependency), active maintenance, no known vulnerabilities, and permissive licensing. It's useful if you need to store JSON-like data across heterogeneous database environments or want to swap JSON libraries. Skip it if you're locked into a single database with native JSON support and don't need encoding flexibility.

## Install

pip install sqlalchemy-jsonfield
uv add sqlalchemy-jsonfield
poetry add sqlalchemy-jsonfield

## Installing SQLAlchemy-JSONField

Before you install: Low friction: single runtime dependency on sqlalchemy, wheel distribution available. Active maintenance with recent release (95 days ago) and ongoing repository activity.

License in practice: Apache-2.0 permissive license allows commercial and private use with minimal restrictions.

Quickstart:

import sqlalchemy_jsonfield
import sqlalchemy

class ExampleTable(Base):
    __tablename__ = 'example'
    id = sqlalchemy.Column(sqlalchemy.Integer, primary_key=True)
    json_record = sqlalchemy.Column(
        sqlalchemy_jsonfield.JSONField(enforce_string=True),
        nullable=False
    )

Requires Python 3.9 or later; sqlalchemy must be installed as a runtime dependency.

Verify before relying:

- Whether the package works with SQLAlchemy 2.0+ (version constraint not specified in fact sheet)
- Performance characteristics when handling large JSON documents across different database backends

## Package facts

- License: Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 6.0M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

sqlalchemy json field, store dict in database, json column sqlalchemy, cross-database json storage, sqlite mysql json compatibility, sqlalchemy text json fallback, sqlalchemy-extension, cross-database-compat

[View on SkillFed](https://skillfed.io/packages/sqlalchemy-jsonfield) · [View on PyPI](https://pypi.org/project/sqlalchemy-jsonfield/)