Formally deprecate old db search backends (#7651)

As per #7633

docs/getting_started/integrating_into_django.md

@@ -59,6 +59,18 @@ Add a `WAGTAIL_SITE_NAME` - this will be displayed on the main dashboard of the
 WAGTAIL_SITE_NAME = 'My Example Site'
 ```
 
+<!--- RemovedInWagtail217Warning (wagtail.search.backends.database will be made the default and will not need to be added explicitly here) -->
+
+Add the `WAGTAILSEARCH_BACKENDS` setting to enable full-text searching:
+
+```python
+WAGTAILSEARCH_BACKENDS = {
+    'default': {
+        'BACKEND': 'wagtail.search.backends.database',
+    }
+}
+```
+
 Various other settings are available to configure Wagtail's behaviour - see [Settings](/reference/settings).
 
 ## URL configuration

docs/reference/contrib/postgres_search.rst

@@ -4,6 +4,11 @@
 PostgreSQL search engine
 ========================
 
+.. warning::
+
+    | This search backend is deprecated, and has been replaced by ``wagtail.search.backends.database``. See :ref:`wagtailsearch_backends`.
+
+
 This contrib module provides a search engine backend using
 `PostgreSQL full-text search capabilities <https://www.postgresql.org/docs/current/static/textsearch.html>`_.
 

docs/releases/2.15.rst

@@ -149,6 +149,46 @@ Bug fixes
 Upgrade considerations
 ======================
 
+Database search backends replaced
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following search backends (configured in ``WAGTAILSEARCH_BACKENDS``) have been deprecated:
+
+ - ``wagtail.search.backends.db`` (the default if ``WAGTAILSEARCH_BACKENDS`` is not specified)
+ - ``wagtail.contrib.postgres_search.backend``
+
+Both of these backends have now been replaced by ``wagtail.search.backends.database``. This new
+backend supports all of the features of the PostgreSQL backend, and also supports other databases.
+It will be made the default backend in Wagtail 2.17. To enable the new backend, edit (or add) the
+``WAGTAILSEARCH_BACKENDS`` setting as follows:
+
+.. code-block:: python
+
+    WAGTAILSEARCH_BACKENDS = {
+        'default': {
+            'BACKEND': 'wagtail.search.backends.database',
+        }
+    }
+
+Also remove ``'wagtail.contrib.postgres_search'`` from ``INSTALLED_APPS`` if this was previously set.
+
+After switching to this backend, you will need to run the ``manage.py update_index`` management
+command to populate the search index (see :ref:`update_index`).
+
+If you have used the PostgreSQL-specific ``SEARCH_CONFIG``, this will continue to work as before with the new backend. For example:
+
+.. code-block:: python
+
+    WAGTAILSEARCH_BACKENDS = {
+        'default': {
+            'BACKEND': 'wagtail.search.backends.database',
+            'SEARCH_CONFIG': 'english',
+        }
+    }
+
+However, as a PostgreSQL specific feature, this will be ignored when using a different database.
+
+
 Admin homepage panels, summary items and action menu items now use components
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -266,31 +306,6 @@ can find out the relation name as follows:
         COMMENTS_RELATION_NAME = 'comments'
 
 
-Database backends replaced
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The following search backends (configured in ``WAGTAILSEARCH_BACKENDS``) have been deprecated:
-
- - ``wagtail.search.backends.db``
- - ``wagtail.contrib.postgres_search.backend``
-
-Both of these backends have now moved to ``wagtail.search.backends.database``.
-This new backend supports all of the features of the PostgreSQL backend, and also supports other databases.
-
-If you have used the PostgreSQL-specific ``SEARCH_CONFIG``, this will continue to work as before with the new backend. For example:
-
-.. code-block:: python
-
-    WAGTAILSEARCH_BACKENDS = {
-        'default': {
-            'BACKEND': 'wagtail.search.backends.database',
-            'SEARCH_CONFIG': 'english',
-        }
-    }
-
-However, as a PostgreSQL specific feature, this will be ignored when using a different database.
-
-
 Bulk action views not covered by existing hooks
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/topics/search/backends.rst

@@ -5,7 +5,7 @@
 Backends
 ========
 
-Wagtailsearch has support for multiple backends, giving you the choice between using the database for search or an external service such as Elasticsearch. The database backend is enabled by default.
+Wagtailsearch has support for multiple backends, giving you the choice between using the database for search or an external service such as Elasticsearch.
 
 You can configure which backend to use with the ``WAGTAILSEARCH_BACKENDS`` setting:
 
@@ -63,13 +63,13 @@ Database Backend (default)
 
 ``wagtail.search.backends.database``
 
-.. versionchanged:: 2.15
-
-    The default database search backend was changed from ``wagtail.search.backends.db``
-
 The database search backend searches content in the database using the full text search features of the database backend in use (such as PostgreSQL FTS, SQLite FTS5).
 This backend is intended to be used for development and also should be good enough to use in production on sites that don't require any Elasticsearch specific features.
 
+.. versionchanged:: 2.15
+
+    ``wagtail.search.backends.database`` replaces the old ``wagtail.search.backends.db`` backend which works using simple substring matching only. ``wagtail.search.backends.db`` is still the default if ``WAGTAILSEARCH_BACKENDS`` is not specified; ``wagtail.search.backends.database`` will become the default in Wagtail 2.17.
+
 
 .. _wagtailsearch_backends_elasticsearch:
 

docs/topics/search/index.rst

@@ -38,6 +38,6 @@ See :ref:`wagtailsearch_searching`.
 Backends
 ========
 
-Wagtail provides three backends for storing the search index and performing search queries: Elasticsearch, the database, and PostgreSQL (Django >=1.10 required). It's also possible to roll your own search backend.
+Wagtail provides two backends for storing the search index and performing search queries: one using the database's full-text search capabilities, and another using Elasticsearch. It's also possible to roll your own search backend.
 
 See :ref:`wagtailsearch_backends`

wagtail/contrib/postgres_search/apps.py

@@ -14,7 +14,12 @@ class PostgresSearchConfig(AppConfig):
 
     def ready(self):
 
-        warnings.warn('The wagtail.contrib.postgres_search app will be deprecated in a future release. Please update your search backend to \'wagtail.search.backends.database\', which will pick up a Postgres backend automatically.', RemovedInWagtail217Warning)
+        warnings.warn(
+            "The wagtail.contrib.postgres_search backend is deprecated and has been replaced by "
+            "wagtail.search.backends.database. "
+            "See https://docs.wagtail.io/en/stable/releases/2.15.html#database-search-backends-replaced",
+            category=RemovedInWagtail217Warning
+        )
 
         @register(Tags.compatibility, Tags.database)
         def check_if_postgresql(app_configs, **kwargs):

wagtail/contrib/postgres_search/backend.py

@@ -18,6 +18,7 @@ from wagtail.search.backends.base import (
 from wagtail.search.index import AutocompleteField, RelatedFields, SearchField, get_indexed_models
 from wagtail.search.query import And, Boost, MatchAll, Not, Or, Phrase, PlainText
 from wagtail.search.utils import ADD, MUL, OR
+from wagtail.utils.deprecation import RemovedInWagtail217Warning
 
 from .models import IndexEntry
 from .query import Lexeme, RawSearchQuery
@@ -26,6 +27,14 @@ from .utils import (
     get_sql_weights, get_weight)
 
 
+warnings.warn(
+    "The wagtail.contrib.postgres_search backend is deprecated and has been replaced by "
+    "wagtail.search.backends.database. "
+    "See https://docs.wagtail.io/en/stable/releases/2.15.html#database-search-backends-replaced",
+    category=RemovedInWagtail217Warning
+)
+
+
 EMPTY_VECTOR = SearchVector(Value('', output_field=TextField()))
 
 

wagtail/project_template/project_name/settings/base.py

@@ -157,6 +157,14 @@ MEDIA_URL = '/media/'
 
 WAGTAIL_SITE_NAME = "{{ project_name }}"
 
+# Search
+# https://docs.wagtail.io/en/stable/topics/search/backends.html
+WAGTAILSEARCH_BACKENDS = {
+    'default': {
+        'BACKEND': 'wagtail.search.backends.database',
+    }
+}
+
 # Base URL to use when referring to full URLs within the Wagtail admin backend -
 # e.g. in notification emails. Don't include '/admin' or a trailing slash
 BASE_URL = 'http://example.com'

wagtail/search/backends/__init__.py

@@ -18,7 +18,8 @@ def get_search_backend_config():
 
     # Make sure the default backend is always defined
     search_backends.setdefault('default', {
-        'BACKEND': 'wagtail.search.backends.database',
+        # RemovedInWagtail217Warning - will switch to wagtail.search.backends.database
+        'BACKEND': 'wagtail.search.backends.db',
     })
 
     return search_backends

wagtail/search/backends/database/fallback.py

@@ -12,7 +12,16 @@ from wagtail.search.query import And, Boost, MatchAll, Not, Or, Phrase, PlainTex
 from wagtail.search.utils import AND, OR
 
 
-# This file contains a dummy implementation of the database backend, to be used only if the current default database is neither PostgreSQL, nor MySQL, nor SQLite.
+# This file implements a database search backend using basic substring matching, and no
+# database-specific full-text search capabilities. It will be used in the following cases:
+# * The current default database is SQLite <3.19, or something other than PostgreSQL, MySQL or
+#   SQLite
+# * 'wagtail.search.backends.database.fallback' is specified directly as the search backend
+# * The deprecated 'wagtail.search.backends.db' backend is active; this is the default when no
+#   WAGTAILSEARCH_BACKENDS setting is present.
+#
+# RemovedInWagtail217Warning - the default will be switched to wagtail.search.backends.database
+# and wagtail.search.backends.db will be dropped.
 
 
 MATCH_ALL = "_ALL_"

wagtail/search/backends/db.py

@@ -1,16 +1,13 @@
-import sys
+from warnings import warn
 
-from wagtail.utils.deprecation import MovedDefinitionHandler, RemovedInWagtail217Warning
+from wagtail.search.backends.database.fallback import (  # noqa
+    DatabaseSearchBackend, DatabaseSearchQueryCompiler, DatabaseSearchResults, SearchBackend)
+from wagtail.utils.deprecation import RemovedInWagtail217Warning
 
 
-# If users still import their backend from here, they will get a deprecation warning. The actual backend implementation is now in a submodule (database).
-
-
-MOVED_DEFINITIONS = {
-    'DatabaseSearchQueryCompiler': ('wagtail.search.backends.database', 'DatabaseSearchQueryCompiler'),
-    'DatabaseSearchResults': ('wagtail.search.backends.database', 'DatabaseSearchResults'),
-    'DatabaseSearchBackend': ('wagtail.search.backends.database', 'DatabaseSearchBackend'),
-    'SearchBackend': ('wagtail.search.backends.database', 'SearchBackend'),
-}
-
-sys.modules[__name__] = MovedDefinitionHandler(sys.modules[__name__], MOVED_DEFINITIONS, RemovedInWagtail217Warning)
+warn(
+    "The wagtail.search.backends.db search backend is deprecated and has been replaced by "
+    "wagtail.search.backends.database. "
+    "See https://docs.wagtail.io/en/stable/releases/2.15.html#database-search-backends-replaced",
+    category=RemovedInWagtail217Warning
+)