diff options
| author | Mike Bayer <mike_mp@zzzcomputing.com> | 2017-05-17 13:05:04 -0400 |
|---|---|---|
| committer | Mike Bayer <mike_mp@zzzcomputing.com> | 2017-05-17 17:08:23 -0400 |
| commit | 912fb6c2d54d7f2fcda654a8f7702d122e8b8d70 (patch) | |
| tree | bc9fb26d88acc7631fce8eacbfd90d53253f2584 /doc | |
| parent | 4c6917e1d68a8baab7efe10e9ce5e5c8187f65ca (diff) | |
| download | sqlalchemy-912fb6c2d54d7f2fcda654a8f7702d122e8b8d70.tar.gz | |
Add new configuration, inspection for baked queries
Added new flag :paramref:`.Session.enable_baked_queries` to the
:class:`.Session` to allow baked queries to be disabled
session-wide, reducing memory use. Also added new :class:`.Bakery`
wrapper so that the bakery returned by :paramref:`.BakedQuery.bakery`
can be inspected.
Change-Id: I5657af7a99d2b24c89d6aee1343f432728e3f807
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/build/changelog/changelog_12.rst | 9 | ||||
| -rw-r--r-- | doc/build/orm/extensions/baked.rst | 30 |
2 files changed, 38 insertions, 1 deletions
diff --git a/doc/build/changelog/changelog_12.rst b/doc/build/changelog/changelog_12.rst index 3d0b7fa08..d8efd74a9 100644 --- a/doc/build/changelog/changelog_12.rst +++ b/doc/build/changelog/changelog_12.rst @@ -13,6 +13,15 @@ .. changelog:: :version: 1.2.0b1 + .. change:: baked_opts + :tags: feature, ext + + Added new flag :paramref:`.Session.enable_baked_queries` to the + :class:`.Session` to allow baked queries to be disabled + session-wide, reducing memory use. Also added new :class:`.Bakery` + wrapper so that the bakery returned by :paramref:`.BakedQuery.bakery` + can be inspected. + .. change:: 3988 :tags: bug, orm :tickets: 3988 diff --git a/doc/build/orm/extensions/baked.rst b/doc/build/orm/extensions/baked.rst index 0dceedc4a..593293b46 100644 --- a/doc/build/orm/extensions/baked.rst +++ b/doc/build/orm/extensions/baked.rst @@ -332,6 +332,27 @@ to arrive at the current "baked" approach. Starting from the management, removal of all redundant Python execution, and queries built up with conditionals needed to be addressed, leading to the final approach. +Disabling Baked Queries Session-wide +------------------------------------ + +The flag :paramref:`.Session.enable_baked_queries` may be set to False, +causing all baked queries to not use the cache when used against that +:class:`.Session`:: + + session = Session(engine, enable_baked_queries=False) + +Like all session flags, it is also accepted by factory objects like +:class:`.sessionmaker` and methods like :meth:`.sessionmaker.configure`. + +The immediate rationale for this flag is to reduce memory use in the case +that the query baking used by relationship loaders and other loaders +is not desirable. It also can be used in the case that an application +which is seeing issues potentially due to cache key conflicts from user-defined +baked queries or other baked query issues can turn the behavior off, in +order to identify or eliminate baked queries as the cause of an issue. + +.. versionadded:: 1.2 + Lazy Loading Integration ------------------------ @@ -350,7 +371,11 @@ Opting out with the bake_queries flag The :func:`.relationship` construct includes a flag :paramref:`.relationship.bake_queries` which when set to False will cause -that relationship to opt out of caching queries. +that relationship to opt out of caching queries. Additionally, the +:paramref:`.Session.enable_baked_queries` setting can be used to disable +all "baked query" use. These flags can be useful to conserve memory, +when memory conservation is more important than performance for a particular +relationship or for the application overall. API Documentation ----------------- @@ -360,6 +385,9 @@ API Documentation .. autoclass:: BakedQuery :members: +.. autoclass:: Bakery + :members: + .. autoclass:: Result :members: |