[AlexeyShalaev]

Closes #59.

Problem

BasePostgresConfig.use_orjson_serialization defaulted to True, but orjson ships only with the [orjson]/[all] extras. Following the quick start (pip install "sqlalchemy-foundation-kit[settings]", a config with defaults, create_async_session_manager(config)) failed with ImportError: orjson is required before anything connected. So did the dishka and dependency-injector integrations. Every other entry point (AsyncSessionManager, the builder) already defaults to False.

Change

• use_orjson_serialization defaults to False. The field docstring says why it's opt-in.
• Defaults table, the orjson section of the configuration guide (it is now off by default, becomes the engine's JSON serializer for every JSON/JSONB column, and accepts values json.dumps rejects), docs/agents.md (the BasePostgresConfig row, the extras rule, a "Fixed since" row), the README and the protocol docstring example.

Considered and rejected

• None meaning "orjson if importable". It would keep current installs unchanged, but how JSON columns serialize would then depend on whether another package happened to pull orjson in. That's the coupling the issue argued against.
• Adding orjson to [settings]. Same coupling, tied to the configuration extra instead.

Breaking change

fix!:, with a BREAKING CHANGE: footer. Who notices: services that have orjson installed, kept the default, and write values into JSON columns that only orjson serializes. Measured on PostgreSQL 17 through AsyncSessionManager:

use_orjson=True  datetime -> stored
use_orjson=True  uuid     -> stored
use_orjson=False datetime -> StatementError: (builtins.TypeError) Object of type datetime is not JSON serializable
use_orjson=False uuid     -> StatementError: (builtins.TypeError) Object of type UUID is not JSON serializable

Migration: use_orjson_serialization=True (or the matching env var) keeps the old behaviour. Services whose JSON columns hold plain JSON types see no difference. With #56 also !, the next release is a minor (0.5.0) under bump-minor-pre-major. No org repo pins this package.

Evidence

New tests against the old contrib/settings/postgres.py (swapped in from origin/master): the quick-start test fails with the reporter's exact ImportError: orjson is required ... pip install 'sqlalchemy-foundation-kit[orjson]'. The companion test, where opting in without the extra still raises naming the extra, passes on both.

The reporter's script after the fix, with orjson blocked from importing:

use_orjson_serialization = False
manager created

Gate: make check clean; make test 628 passed.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!