Fixed #19031 -- Added a warning when using override_settings with 'DATABASES'

3 files changed, 27 insertions, 1 deletions

diff --git a/docs/ref/signals.txt b/docs/ref/signals.txt
index 0253832b8d..d4f261cadb 100644
--- a/docs/ref/signals.txt
+++ b/docs/ref/signals.txt
@@ -553,7 +553,8 @@ This signal is sent when the value of a setting is changed through the
 :func:`django.test.utils.override_settings` decorator/context manager.
 
 It's actually sent twice: when the new value is applied ("setup") and when the
-original value is restored ("teardown").
+original value is restored ("teardown"). Use the ``enter`` argument to
+distinguish between the two.
 
 Arguments sent with this signal:
 
@@ -567,6 +568,11 @@ Arguments sent with this signal:
     The value of the setting after the change. For settings that initially
     don't exist, in the "teardown" phase, ``value`` is ``None``.
 
+``enter``
+    .. versionadded:: 1.7
+
+        A boolean; ``True`` if the setting is applied, ``False`` if restored.
+
 template_rendered
 -----------------
 
diff --git a/docs/releases/1.7.txt b/docs/releases/1.7.txt
index 8d967ff469..2cf1cd326e 100644
--- a/docs/releases/1.7.txt
+++ b/docs/releases/1.7.txt
@@ -38,6 +38,9 @@ Minor features
   contains extra parameters passed to the ``content-type`` header on a file
   upload.
 
+* The ``enter`` argument was added to the
+  :data:`~django.test.signals.setting_changed` signal.
+
 Backwards incompatible changes in 1.7
 =====================================
 
diff --git a/docs/topics/testing/overview.txt b/docs/topics/testing/overview.txt
index 6f75a3b7a8..73f2daa294 100644
--- a/docs/topics/testing/overview.txt
+++ b/docs/topics/testing/overview.txt
@@ -1403,6 +1403,23 @@ The decorator can also be applied to test case classes::
     the original ``LoginTestCase`` is still equally affected by the
     decorator.
 
+.. warning::
+
+    The settings file contains some settings that are only consulted during
+    initialization of Django internals. If you change them with
+    ``override_settings``, the setting is changed if you access it via the
+    ``django.conf.settings`` module, however, Django's internals access it
+    differently. Effectively, using ``override_settings`` with these settings
+    is probably not going to do what you expect it to do.
+
+    We do not recommend using ``override_settings`` with :setting:`DATABASES`.
+    Using ``override_settings`` with :setting:`CACHES` is possible, but a bit
+    tricky if you are using internals that make using of caching, like
+    :mod:`django.contrib.sessions`. For example, you will have to reinitialize
+    the session backend in a test that uses cached sessions and overrides
+    :setting:`CACHES`.
+
+
 You can also simulate the absence of a setting by deleting it after settings
 have been overriden, like this::