once again note pydantic is never really going to work

In #9894 we see that pydantic's dataclass feature is doing an
end run around SQLAlchemy's collection mechanics that can't
be fixed without special steps, which we would surmise
is what SQLModel is doing here:

https://github.com/tiangolo/sqlmodel/blob/43a689d369f52b72aac60efd71111aba7d84714d/sqlmodel/main.py#L507

We don't do that, so note that we really are not supporting pydantic
directly; use SQLModel which was designed to resolve these issues.

Change-Id: I3e35e108546022c83d6c0ae73e32432cdc75d325

diff --git a/doc/build/orm/dataclasses.rst b/doc/build/orm/dataclasses.rst
index 240ec75892dd04b0ba1ea67991f13763f1d44546..1421b0ad2bc871f1176791ddecd5ff4e6bad57f7 100644 (file)
--- a/doc/build/orm/dataclasses.rst
+++ b/doc/build/orm/dataclasses.rst
@@ -528,6 +528,15 @@ variable may be generated::
 Integrating with Alternate Dataclass Providers such as Pydantic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+.. warning::  Pydantic's dataclass layer is **not fully compatible with
+   SQLAlchemy's class instrumentation without additional internal changes, and
+   many features such as related collections may not work correctly.**.
+
+   For Pydantic compatibility, please consider the
+   `SQLModel <https://sqlmodel.tiangolo.com/>` ORM which is built with
+   Pydantic on top of SQLAlchemy ORM, which includes special implementation
+   details which **explicitly resolve** these incompabilities.
+
 SQLAlchemy's :class:`_orm.MappedAsDataclass` class
 and :meth:`_orm.registry.mapped_as_dataclass` method call directly into
 the Python standard library ``dataclasses.dataclass`` class decorator, after