From 2f146b172ad228e40f1e8d5f1d2abc888ae5e669 Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Tue, 30 Aug 2022 09:50:03 -0400 Subject: apply consistent ORM mutable notes for all mutable SQL types in https://github.com/sqlalchemy/sqlalchemy/discussions/8447 I was surprised that we didnt have any notes about using Mutable for ARRAY classes, since we have them for HSTORE and JSON. Add a consistent topic box for these so we have something to point towards. Change-Id: Idfa1b2cbee67024545f4fa299e4c875075ec7d3f --- lib/sqlalchemy/dialects/postgresql/array.py | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) (limited to 'lib/sqlalchemy/dialects/postgresql/array.py') diff --git a/lib/sqlalchemy/dialects/postgresql/array.py b/lib/sqlalchemy/dialects/postgresql/array.py index 515eb2d15..3132e875e 100644 --- a/lib/sqlalchemy/dialects/postgresql/array.py +++ b/lib/sqlalchemy/dialects/postgresql/array.py @@ -201,6 +201,31 @@ class ARRAY(sqltypes.ARRAY): conjunction with the :class:`.ENUM` type. For a workaround, see the special type at :ref:`postgresql_array_of_enum`. + .. container:: topic + + **Detecting Changes in ARRAY columns when using the ORM** + + The :class:`_postgresql.ARRAY` type, when used with the SQLAlchemy ORM, + does not detect in-place mutations to the array. In order to detect + these, the :mod:`sqlalchemy.ext.mutable` extension must be used, using + the :class:`.MutableList` class:: + + from sqlalchemy.dialects.postgresql import ARRAY + from sqlalchemy.ext.mutable import MutableList + + class SomeOrmClass(Base): + # ... + + data = Column(MutableList.as_mutable(ARRAY(Integer))) + + This extension will allow "in-place" changes such to the array + such as ``.append()`` to produce events which will be detected by the + unit of work. Note that changes to elements **inside** the array, + including subarrays that are mutated in place, are **not** detected. + + Alternatively, assigning a new array value to an ORM element that + replaces the old one will always trigger a change event. + .. seealso:: :class:`_types.ARRAY` - base array type -- cgit v1.2.1