diff --git a/docs/getting_started/integrating_into_django.md b/docs/getting_started/integrating_into_django.md index 637ecaa7d7..4e5a97f3bc 100644 --- a/docs/getting_started/integrating_into_django.md +++ b/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' ``` + + +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 diff --git a/docs/reference/contrib/postgres_search.rst b/docs/reference/contrib/postgres_search.rst index 2c8b569e45..09fa0c9667 100644 --- a/docs/reference/contrib/postgres_search.rst +++ b/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 `_. diff --git a/docs/releases/2.15.rst b/docs/releases/2.15.rst index 1c1fba36ea..315817c41b 100644 --- a/docs/releases/2.15.rst +++ b/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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/topics/search/backends.rst b/docs/topics/search/backends.rst index c43077ba9f..44eb09da9e 100644 --- a/docs/topics/search/backends.rst +++ b/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: diff --git a/docs/topics/search/index.rst b/docs/topics/search/index.rst index 73a4892749..5068c271d0 100644 --- a/docs/topics/search/index.rst +++ b/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` diff --git a/wagtail/contrib/postgres_search/apps.py b/wagtail/contrib/postgres_search/apps.py index 97435d67b6..6ff8ac1963 100644 --- a/wagtail/contrib/postgres_search/apps.py +++ b/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): diff --git a/wagtail/contrib/postgres_search/backend.py b/wagtail/contrib/postgres_search/backend.py index 01626d5823..d6c2f063b8 100644 --- a/wagtail/contrib/postgres_search/backend.py +++ b/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())) diff --git a/wagtail/project_template/project_name/settings/base.py b/wagtail/project_template/project_name/settings/base.py index 1031cb7f94..e64d2c24eb 100644 --- a/wagtail/project_template/project_name/settings/base.py +++ b/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' diff --git a/wagtail/search/backends/__init__.py b/wagtail/search/backends/__init__.py index 487f15ff51..5c82c5a99d 100644 --- a/wagtail/search/backends/__init__.py +++ b/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 diff --git a/wagtail/search/backends/database/fallback.py b/wagtail/search/backends/database/fallback.py index 63bad6876a..8ed880651a 100644 --- a/wagtail/search/backends/database/fallback.py +++ b/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_" diff --git a/wagtail/search/backends/db.py b/wagtail/search/backends/db.py index 73ab90db2c..8c46cbd5cf 100644 --- a/wagtail/search/backends/db.py +++ b/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 +)