From: Mike Bayer Date: Sun, 16 Feb 2014 17:43:46 +0000 (-0500) Subject: - add cross-linking for passive_deletes / passive_updates X-Git-Tag: rel_0_8_5~17 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=0dc4beaa08b97cc48b993ad9910c5ccfec061044;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git - add cross-linking for passive_deletes / passive_updates --- diff --git a/doc/build/orm/collections.rst b/doc/build/orm/collections.rst index 053369baa7..354cfbca45 100644 --- a/doc/build/orm/collections.rst +++ b/doc/build/orm/collections.rst @@ -112,7 +112,7 @@ from the database, the ``children`` collection stays empty. Using Passive Deletes ---------------------- -Use ``passive_deletes=True`` to disable child object loading on a DELETE +Use :paramref:`~.relationship.passive_deletes` to disable child object loading on a DELETE operation, in conjunction with "ON DELETE (CASCADE|SET NULL)" on your database to automatically cascade deletes to child objects:: @@ -142,7 +142,7 @@ to automatically cascade deletes to child objects:: * When using SQLite, foreign key support must be enabled explicitly. See :ref:`sqlite_foreign_keys` for details. -When ``passive_deletes`` is applied, the ``children`` relationship will not be +When :paramref:`~.relationship.passive_deletes` is applied, the ``children`` relationship will not be loaded into memory when an instance of ``MyClass`` is marked for deletion. The ``cascade="all, delete-orphan"`` *will* take effect for instances of ``MyOtherClass`` which are currently present in the session; however for diff --git a/doc/build/orm/relationships.rst b/doc/build/orm/relationships.rst index 67a41c8087..e5534534a2 100644 --- a/doc/build/orm/relationships.rst +++ b/doc/build/orm/relationships.rst @@ -221,8 +221,8 @@ There are several possibilities here: this feature, the database itself can be made to automatically delete rows in the "secondary" table as referencing rows in "child" are deleted. SQLAlchemy can be instructed to forego actively loading in the ``Child.parents`` - collection in this case using the ``passive_deletes=True`` directive - on :func:`.relationship`; see :ref:`passive_deletes` for more details + collection in this case using the :paramref:`~.relationship.passive_deletes` + directive on :func:`.relationship`; see :ref:`passive_deletes` for more details on this. Note again, these behaviors are *only* relevant to the ``secondary`` option @@ -1354,13 +1354,13 @@ of sync for any moment. For databases that don't support this, such as SQLite and MySQL without their referential integrity options turned -on, the ``passive_updates`` flag can +on, the :paramref:`~.relationship.passive_updates` flag can be set to ``False``, most preferably on a one-to-many or many-to-many :func:`.relationship`, which instructs SQLAlchemy to issue UPDATE statements individually for objects referenced in the collection, loading them into memory if not already locally present. The -``passive_updates`` flag can also be ``False`` in +:paramref:`~.relationship.passive_updates` flag can also be ``False`` in conjunction with ON UPDATE CASCADE functionality, although in that case the unit of work will be issuing extra SELECT and UPDATE statements unnecessarily. @@ -1385,16 +1385,17 @@ A typical mutable primary key setup might look like:: ForeignKey('user.username', onupdate="cascade") ) -``passive_updates`` is set to ``True`` by default, +:paramref:`~.relationship.passive_updates` is set to ``True`` by default, indicating that ON UPDATE CASCADE is expected to be in place in the usual case for foreign keys that expect to have a mutating parent key. -``passive_updates=False`` may be configured on any +A :paramref:`~.relationship.passive_updates` setting of False may be configured on any direction of relationship, i.e. one-to-many, many-to-one, and many-to-many, although it is much more effective when placed just on the one-to-many or many-to-many side. -Configuring the ``passive_updates=False`` only on the +Configuring the :paramref:`~.relationship.passive_updates` +to False only on the many-to-one side will have only a partial effect, as the unit of work searches only through the current identity map for objects that may be referencing the one with a diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py index 02dd788777..d5fdbae76e 100644 --- a/lib/sqlalchemy/orm/__init__.py +++ b/lib/sqlalchemy/orm/__init__.py @@ -555,6 +555,11 @@ def relationship(argument, secondary=None, **kwargs): after a flush occurs so this is a very special use-case setting. + .. seealso:: + + :ref:`passive_deletes` - Introductory documentation + and examples. + :param passive_updates=True: Indicates loading and INSERT/UPDATE/DELETE behavior when the source of a foreign key value changes (i.e. an "on update" @@ -581,10 +586,13 @@ def relationship(argument, secondary=None, **kwargs): are expected and the database in use doesn't support CASCADE (i.e. SQLite, MySQL MyISAM tables). - Also see the passive_updates flag on ``mapper()``. + .. seealso:: + + :ref:`passive_updates` - Introductory documentation and + examples. - A future SQLAlchemy release will provide a "detect" feature for - this flag. + :paramref:`.mapper.passive_updates` - a similar flag which + takes effect for joined-table inheritance mappings. :param post_update: this indicates that the relationship should be handled by a @@ -1061,7 +1069,7 @@ def mapper(class_, local_table=None, *args, **params): When False, it is assumed that the database does not enforce referential integrity and will not be issuing its own CASCADE - operation for an update. The :class:`.Mapper` here will + operation for an update. The unit of work process will emit an UPDATE statement for the dependent columns during a primary key change.