如何让SQLAlchemy在PostgreSQL下将JSONB作为JSON默认别名

两种可落地的方案，都能做到同一份ORM代码在PostgreSQL环境自动使用JSONB，其余数据库（包括SQLite）自动使用基础JSON类型，不需要为不同环境维护两套Schema定义。

方案1：自定义自适应类型（推荐，兼容性最好） #

用SQLAlchemy自带的TypeDecorator实现动态类型加载，逻辑可控，不会出现全局污染。

1. 先定义通用自适应JSON类型：

from sqlalchemy import JSON
from sqlalchemy.types import TypeDecorator

class AutoJSON(TypeDecorator):
    impl = JSON
    cache_ok = True

    def load_dialect_impl(self, dialect):
        # 检测当前连接的数据库方言
        if dialect.name == "postgresql":
            from sqlalchemy.dialects.postgresql import JSONB
            return dialect.type_descriptor(JSONB())
        # 非PostgreSQL方言统一使用基础JSON类型
        return dialect.type_descriptor(JSON())

2. ORM模型中所有JSON字段统一使用这个自定义类型即可：

from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column

class Base(DeclarativeBase):
    pass

class BizData(Base):
    __tablename__ = "biz_data"
    id: Mapped[int] = mapped_column(primary_key=True)
    config: Mapped[dict] = mapped_column(AutoJSON)
    report_attr: Mapped[dict] = mapped_column(AutoJSON)

这个方案的优势：

• 无全局副作用，只有显式使用AutoJSON的字段会做类型适配
• 自动适配序列化、查询语法生成逻辑：PostgreSQL下自动支持JSONB的所有操作符、索引，和你直接写JSONB类型的效果完全一致；SQLite下自动适配SQLite原生JSON类型的语法，不会出现类型不兼容报错
• 扩展方便，后续如果要给MySQL等其他数据库做特殊类型适配，只需要在load_dialect_impl方法里加对应分支即可

方案2：全局覆写PostgreSQL方言的JSON编译规则（适合存量代码改造） #

如果你的现有代码已经在所有字段上写了JSON类型，不想逐个修改字段定义，可以直接通过编译规则全局替换PostgreSQL下JSON类型的编译结果：

from sqlalchemy import JSON
from sqlalchemy.dialects.postgresql import JSONB
from sqlalchemy.ext.compiler import compiles

@compiles(JSON, "postgresql")
def _pg_json_to_jsonb(type_, compiler, **kw):
    return compiler.visit_JSONB(JSONB(), **kw)

注意事项：

• 这个规则全局生效，所有定义为JSON的字段，在PostgreSQL环境下都会被创建为JSONB类型
• 如果你有部分字段刻意需要在PostgreSQL下使用普通JSON而非JSONB，不要用这个方案
• 建议使用SQLAlchemy 2.0及以上版本，低版本（<1.4）可能存在值绑定类型不匹配的问题

两种方案都不需要修改现有报表查询逻辑，SQLAlchemy会根据当前连接的方言自动生成对应数据库支持的JSON操作语法，同一份代码可以直接在简单场景（SQLite）和复杂场景（PostgreSQL）下运行。

内容的提问来源于stack exchange，提问作者Technaton