hare-orm 0.9.0__py3-none-any.whl

hare/dialects/postgresql/schema/tables/postgresql_table_partitions.py

@@ -0,0 +1,229 @@
+from __future__ import annotations
+
+from collections.abc import Collection
+from typing import TYPE_CHECKING, Any, cast
+
+from hare.ddl.constraints.exclusion_constraint import ExclusionConstraint
+from hare.ddl.table_options import TableOptions
+from hare.dialects.base.schema.tables.table_partitions import TablePartitions
+from hare.dialects.postgresql.partitioning.partitioning import BoundValueRenderer, Partitioning
+from hare.dialects.postgresql.partitioning.partitions.partition import Partition
+from hare.dialects.postgresql.postgresql_table_options import PostgresqlTableOptions
+from hare.dialects.postgresql.schema.constants import (
+    POSTGRESQL_PARTITION_CREATE_TEMPLATE,
+    POSTGRESQL_SET_DEFAULT_TABLESPACE_SQL,
+)
+from hare.exceptions import ConfigurationError, UnSupportedError
+from hare.models import Model
+
+if TYPE_CHECKING:
+    from hare.dialects.postgresql.schema.postgresql_schema_editor import PostgresqlSchemaEditor
+
+
+class PostgresqlTablePartitions(TablePartitions):
+    """TablePartitions as PostgreSQL writes it."""
+
+    __slots__ = ()
+
+    editor: PostgresqlSchemaEditor
+
+    async def alter_table_options(
+        self, model: type[Model], old_options: TableOptions | None, new_options: TableOptions | None
+    ) -> None:
+        """Changes a table's storage in place: ``SET TABLESPACE``, ``SET LOGGED``/``SET UNLOGGED``,
+        ``SET (...)``/``RESET (...)`` of the storage parameters that changed - on each partition of
+        a partitioned table, which holds none itself - and the partitions added or removed. A change
+        of how the table is partitioned (to or from a partitioned table, another strategy or key,
+        another count of hash partitions) can't be made in place: the table is created anew and
+        its rows are copied.
+
+        Args:
+            model: The model rendered with its new options.
+            old_options: The previous ``PostgresqlTableOptions``, None for none.
+            new_options: The new ``PostgresqlTableOptions``, None for none.
+        """
+        old = cast("PostgresqlTableOptions", old_options or PostgresqlTableOptions())
+        new = cast("PostgresqlTableOptions", new_options or PostgresqlTableOptions())
+        if old.with_partitions({}).partitioning != new.with_partitions({}).partitioning:
+            await self.recreate_table(model)
+            return
+        old_partitions, new_partitions = old.get_partitions(), new.get_partitions()
+        for name, partition in old_partitions.items():
+            if new_partitions.get(name) != partition:
+                await self.remove_partition(model, partition)
+        qualified_table = self.editor.qualify_table_name(model._meta.db_table, model._meta.schema)
+        # A partition added below is created with the new options already.
+        added_partition_names = {
+            name for name, partition in new_partitions.items() if old_partitions.get(name) != partition
+        }
+        stored_tables = self.get_stored_table_names(model, new, skipped_partition_names=added_partition_names)
+        if old.tablespace != new.tablespace:
+            # A partitioned table's own tablespace is the one its new partitions are created in.
+            for table in dict.fromkeys([qualified_table, *stored_tables]):
+                await self.set_tablespace(table, new.tablespace)
+        if old.unlogged != new.unlogged:
+            await self.editor.run_sql(f"ALTER TABLE {qualified_table} SET {'UNLOGGED' if new.unlogged else 'LOGGED'}")
+        removed_parameters = [name for name in old.storage_parameters if name not in new.storage_parameters]
+        changed_parameters = {
+            name: value
+            for name, value in new.storage_parameters.items()
+            if name not in old.storage_parameters or old.storage_parameters[name] != value
+        }
+        for stored_table in stored_tables:
+            if removed_parameters:
+                await self.editor.run_sql(f"ALTER TABLE {stored_table} RESET ({', '.join(removed_parameters)})")
+            if changed_parameters:
+                await self.editor.run_sql(
+                    f"ALTER TABLE {stored_table} SET ({new.get_storage_parameters_sql(changed_parameters)})"
+                )
+        for name, partition in new_partitions.items():
+            if old_partitions.get(name) != partition:
+                await self.add_partition(model, partition)
+
+    def get_partition_create_sqls(self, model: type[Model], safe: bool) -> list[str]:
+        options = self.editor.get_partitioned_options(model)
+        if options is None:
+            return []
+        if not self.editor.client.features.supports_partitioned_exclusion_constraints and any(
+            isinstance(constraint, ExclusionConstraint) for constraint in model._meta.constraints
+        ):
+            raise UnSupportedError(
+                f"{model.__name__}: a partitioned table takes an exclusion constraint from PostgreSQL 17 on"
+            )
+        partitioning = cast("Partitioning", options.partitioning)
+        bound_sqls = partitioning.get_partition_bound_sqls(self.get_bound_value_renderer(model, partitioning))
+        return [
+            self.get_partition_create_sql(model, options, partition_name, bound_sql, safe)
+            for partition_name, bound_sql in bound_sqls.items()
+        ]
+
+    def get_partition_table_names(self, model: type[Model]) -> list[str]:
+        options = self.editor.get_partitioned_options(model)
+        if options is None:
+            return []
+        return [
+            Partitioning.get_partition_table_name(model._meta.db_table, partition_name)
+            for partition_name in cast("Partitioning", options.partitioning).get_partition_names()
+        ]
+
+    async def add_partition(self, model: type[Model], partition: Partition) -> None:
+        """Creates a partition of a model's partitioned table.
+
+        Args:
+            model: The model rendered with the partition.
+            partition: The partition.
+
+        Raises:
+            ConfigurationError: The model's table isn't partitioned.
+        """
+        options = self.editor.get_partitioned_options(model)
+        if options is None:
+            raise ConfigurationError(f"{model.__name__}: a partition can only be added to a partitioned table")
+        partitioning = cast("Partitioning", options.partitioning)
+        bound_sql = partition.get_bound_sql(self.get_bound_value_renderer(model, partitioning))
+        await self.editor.run_sql(self.get_partition_create_sql(model, options, partition.name, bound_sql, safe=False))
+
+    async def remove_partition(self, model: type[Model], partition: Partition) -> None:
+        """Detaches a partition from a model's table and drops it - with its rows.
+
+        Args:
+            model: The model.
+            partition: The partition.
+        """
+        schema = model._meta.schema
+        qualified_partition = self.editor.qualify_table_name(
+            Partitioning.get_partition_table_name(model._meta.db_table, partition.name), schema
+        )
+        qualified_table = self.editor.qualify_table_name(model._meta.db_table, schema)
+        await self.editor.run_sql(f"ALTER TABLE {qualified_table} DETACH PARTITION {qualified_partition}")
+        await self.editor.run_sql(f"DROP TABLE {qualified_partition}")
+
+    def get_bound_value_renderer(self, model: type[Model], partitioning: Partitioning) -> BoundValueRenderer:
+        """How the values of a partition's bound are written for a model's key columns.
+
+        Args:
+            model: The partitioned model.
+            partitioning: Its partitioning.
+
+        Returns:
+            Renders the value of the key column at a position as an SQL literal.
+        """
+        key_fields = partitioning.get_key_fields(model)
+
+        def render_value(position: int, value: Any) -> str:
+            if value is None:
+                return "NULL"
+            db_value = self.editor.client.dialect.types.get_db_value(key_fields[position], value, model)
+            return self.editor.client.dialect.literals.get_literal_sql(db_value)
+
+        return render_value
+
+    def get_partition_create_sql(
+        self, model: type[Model], options: PostgresqlTableOptions, partition_name: str, bound_sql: str, safe: bool
+    ) -> str:
+        """The statement creating one partition - with the storage parameters and tablespace of the
+        table's options, which a partitioned table itself can't hold.
+
+        Args:
+            model: The partitioned model.
+            options: Its table options.
+            partition_name: The partition's name.
+            bound_sql: Its bound (``FOR VALUES ...``/``DEFAULT``).
+            safe: Whether it is created only when it doesn't exist yet.
+
+        Returns:
+            The statement.
+        """
+        schema = model._meta.schema
+        partition_table = Partitioning.get_partition_table_name(model._meta.db_table, partition_name)
+        return POSTGRESQL_PARTITION_CREATE_TEMPLATE.format(
+            exists=self.editor.table_creation.get_exists_sql(safe),
+            partition=self.editor.qualify_table_name(partition_table, schema),
+            table=self.editor.qualify_table_name(model._meta.db_table, schema),
+            bound=bound_sql,
+            storage=options.get_storage_sql(self.editor.quote),
+        )
+
+    def get_stored_table_names(
+        self, model: type[Model], options: PostgresqlTableOptions, skipped_partition_names: Collection[str] = ()
+    ) -> list[str]:
+        """The tables holding a model's rows - its table, or each partition of a partitioned one.
+
+        Args:
+            model: The model.
+            options: Its table options.
+            skipped_partition_names: Partitions to leave out.
+
+        Returns:
+            The qualified table names.
+        """
+        schema = model._meta.schema
+        if options.partitioning is None:
+            return [self.editor.qualify_table_name(model._meta.db_table, schema)]
+        return [
+            self.editor.qualify_table_name(Partitioning.get_partition_table_name(model._meta.db_table, name), schema)
+            for name in options.partitioning.get_partition_names()
+            if name not in skipped_partition_names
+        ]
+
+    async def set_tablespace(self, qualified_table: str, tablespace: str | None) -> None:
+        """Moves a table to a tablespace.
+
+        Args:
+            qualified_table: The table.
+            tablespace: The tablespace, None for the database's default one.
+        """
+        if tablespace:
+            await self.editor.run_sql(f"ALTER TABLE {qualified_table} SET TABLESPACE {self.editor.quote(tablespace)}")
+        else:
+            table_literal = "'" + qualified_table.replace("'", "''") + "'"
+            await self.editor.run_sql(POSTGRESQL_SET_DEFAULT_TABLESPACE_SQL.format(table=table_literal))
+
+    async def recreate_table(self, model: type[Model]) -> None:
+        """Creates a model's table anew with its rows - for a change PostgreSQL can't make in
+        place, such as how the table is partitioned.
+
+        Args:
+            model: The model rendered from the state the table is created to.
+        """
+        await self.editor.table_rebuild.remake_table(model, model)

hare/dialects/postgresql/schema/tables/postgresql_table_rebuild.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Any
+
+from hare.dialects.base.schema.tables.table_rebuild import TableRebuild
+from hare.dialects.postgresql.schema.constants import (
+    POSTGRESQL_RESYNC_SEQUENCE_TEMPLATE,
+    POSTGRESQL_SEQUENCE_OWNER_NONE_TEMPLATE,
+    POSTGRESQL_TABLE_COPY_SUFFIX,
+)
+from hare.sql.identifiers import Identifiers
+
+if TYPE_CHECKING:
+    from hare.dialects.postgresql.schema.postgresql_schema_editor import PostgresqlSchemaEditor
+    from hare.fields.field import Field
+    from hare.models import Model
+
+
+class PostgresqlTableRebuild(TableRebuild):
+    """TableRebuild as PostgreSQL makes it: the names of a table's primary key and unique constraints
+    are the names of their indexes, taken in the whole schema while the old table exists - the rows
+    wait in a copy while the table is dropped and created anew under the same names. The views of the
+    model, which depend on the table, are dropped before it and the objects of the model created again
+    after it; its sequences outlive it, their values too."""
+
+    __slots__ = ()
+
+    editor: PostgresqlSchemaEditor
+
+    async def remake_table(
+        self,
+        old_model: type[Model],
+        new_model: type[Model],
+        altered_fields: Sequence[tuple[Field[Any], Field[Any]]] = (),
+    ) -> None:
+        """Creates a table anew from the model it is rebuilt to, with its rows: they are kept in a copy
+        of the table while the table is dropped and created from the model with its partitions,
+        indexes, constraints, comments and triggers; then they are put back, the sequences of
+        generated keys moved past them and the foreign keys of other tables referencing the table set
+        again.
+
+        Args:
+            old_model: The model the table matches now.
+            new_model: The model the table is rebuilt to.
+            altered_fields: (old, new) fields paired otherwise than by name - a renamed field.
+        """
+        meta = new_model._meta
+        qualified_table = self.editor.qualify_table_name(meta.db_table, meta.schema)
+        copy_table_name = Identifiers.get_within_limit(f"{meta.db_table}{POSTGRESQL_TABLE_COPY_SUFFIX}")
+        qualified_copy = self.editor.qualify_table_name(copy_table_name, meta.schema)
+        # The foreign keys of other tables referencing the table - the relations of the state.
+        await self.editor.foreign_key_rebuild.drop_incoming_foreign_keys(old_model)
+        await self.editor.run_sql(f"CREATE TABLE {qualified_copy} AS SELECT * FROM {qualified_table}")  # nosec B608
+        await self.drop_table_dependents(old_model)
+        await self.editor.run_sql(f"DROP TABLE {qualified_table}")
+        await self.editor.run_sqls(
+            self.editor.table_creation.get_schema_objects_before_table_sqls(new_model, safe=True)
+        )
+        model_sql_data = self.editor.table_creation.get_model_sql_data(new_model)
+        await self.editor.run_sql(model_sql_data.table_sql)
+        for trigger in meta.triggers:
+            for statement in self.editor.trigger_statements.get_trigger_create_sqls(new_model, trigger, safe=True):
+                await self.editor.run_sql(statement)
+        for constraint_sql in model_sql_data.constraint_sqls:
+            await self.editor.run_sql(constraint_sql)
+        column_mapping = self.get_column_mapping(old_model, new_model, altered_fields)
+        if column_mapping:
+            await self.copy_table_rows(new_model, meta.db_table, copy_table_name, column_mapping)
+        await self.editor.run_sql(f"DROP TABLE {qualified_copy}")
+        await self.resync_generated_key_sequences(new_model)
+        await self.editor.foreign_key_rebuild.add_incoming_foreign_keys(new_model)
+        # The views read the rows put back - a materialized view is filled from them.
+        await self.editor.run_sqls(
+            self.editor.table_creation.get_schema_objects_after_table_sqls(new_model, safe=True)
+        )
+
+    async def drop_table_dependents(self, model: type[Model]) -> None:
+        """Drops what a model declares that the drop of its table would refuse to leave or take along:
+        its materialized views and views - in the reverse of their creation order - and the ownership
+        of its sequences by its columns.
+
+        Args:
+            model: The model the table matches now.
+        """
+        meta = model._meta
+        for materialized_view in reversed(meta.materialized_views):
+            await self.editor.materialized_views.drop_materialized_view(model, materialized_view)
+        for view in reversed(meta.views):
+            await self.editor.views.drop_view(model, view)
+        for sequence in meta.sequences:
+            if sequence.owned_by is not None:
+                await self.editor.run_sql(
+                    POSTGRESQL_SEQUENCE_OWNER_NONE_TEMPLATE.format(
+                        sequence=self.editor.qualify_object_name(model, sequence.name)
+                    )
+                )
+
+    async def resync_generated_key_sequences(self, model: type[Model]) -> None:
+        """Moves the sequence of each generated key column of a table past the keys its rows hold.
+
+        Args:
+            model: The model of the table.
+        """
+        meta = model._meta
+        qualified_table = self.editor.qualify_table_name(meta.db_table, meta.schema)
+        table_literal = "'" + qualified_table.replace("'", "''") + "'"
+        for field in meta.fields_map.values():
+            if field.pk and field.generated and field.model_field_name in meta.fields_db_projection:
+                column = meta.fields_db_projection[field.model_field_name]
+                await self.editor.run_sql(
+                    POSTGRESQL_RESYNC_SEQUENCE_TEMPLATE.format(
+                        table_literal=table_literal,
+                        column_literal="'" + column.replace("'", "''") + "'",
+                        column=self.editor.quote(column),
+                        table=qualified_table,
+                    )
+                )

hare/dialects/postgresql/schema/triggers/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

hare/dialects/postgresql/schema/triggers/postgresql_trigger_statements.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from hare.ddl.schema_objects.trigger import Trigger
+from hare.dialects.base.schema.triggers.trigger_statements import TriggerStatements
+from hare.dialects.postgresql.constants import (
+    POSTGRESQL_DEFAULT_TRIGGER_LANGUAGE,
+)
+from hare.dialects.postgresql.schema.constants import POSTGRESQL_DISABLE_TRIGGER_TEMPLATE
+from hare.models import Model
+
+if TYPE_CHECKING:
+    from hare.dialects.postgresql.schema.postgresql_schema_editor import PostgresqlSchemaEditor
+
+
+class PostgresqlTriggerStatements(TriggerStatements):
+    """TriggerStatements as PostgreSQL writes it."""
+
+    __slots__ = ()
+
+    editor: PostgresqlSchemaEditor
+
+    def get_trigger_create_sqls(self, model: type[Model], trigger: Trigger, safe: bool = False) -> list[str]:
+        """The statements creating `trigger`'s backing function and the trigger itself - shared
+        by add_trigger() and generate_schemas().
+
+        Args:
+            model: The model the trigger is declared on.
+            trigger: The trigger.
+            safe: Replace an existing function and trigger of the same name instead of failing.
+
+        Returns:
+            The DDL statements, in execution order.
+        """
+        table = self.editor.qualify_table_name(model._meta.db_table, model._meta.schema)
+        # The function lives in the model's schema, like its table - same-named functions of several
+        # schemas don't collide, and dropping the schema drops it.
+        qualified_function = self.editor.qualify_table_name(trigger.function_name, model._meta.schema)
+        function_template = (
+            self.editor.TRIGGER_FUNCTION_CREATE_OR_REPLACE_TEMPLATE
+            if safe
+            else self.editor.TRIGGER_FUNCTION_CREATE_TEMPLATE
+        )
+        statements = [
+            function_template.format(
+                function_name=qualified_function,
+                body=trigger.body.sql,
+                language=trigger.language or POSTGRESQL_DEFAULT_TRIGGER_LANGUAGE,
+            )
+        ]
+        if safe:
+            statements.append(
+                self.editor.TRIGGER_DROP_IF_EXISTS_TEMPLATE.format(
+                    trigger_name=self.editor.quote(trigger.name), table=table
+                )
+            )
+        when_sql = self.get_when_sql(model, trigger)
+        when_clause = f"\n    WHEN ({when_sql})" if when_sql else ""
+        if trigger.deferrable:
+            statements.append(
+                self.editor.TRIGGER_CONSTRAINT_CREATE_TEMPLATE.format(
+                    trigger_name=self.editor.quote(trigger.name),
+                    timing=trigger.timing,
+                    on=trigger.on,
+                    table=table,
+                    initially="DEFERRED" if trigger.initially_deferred else "IMMEDIATE",
+                    for_each=trigger.for_each,
+                    when_clause=when_clause,
+                    function_name=qualified_function,
+                )
+            )
+        else:
+            statements.append(
+                self.editor.TRIGGER_CREATE_TEMPLATE.format(
+                    trigger_name=self.editor.quote(trigger.name),
+                    timing=trigger.timing,
+                    on=trigger.on,
+                    table=table,
+                    for_each=trigger.for_each,
+                    when_clause=when_clause,
+                    function_name=qualified_function,
+                )
+            )
+        if not trigger.enabled:
+            statements.append(
+                POSTGRESQL_DISABLE_TRIGGER_TEMPLATE.format(table=table, trigger_name=self.editor.quote(trigger.name))
+            )
+        return statements
+
+    async def add_trigger(self, model: type[Model], trigger: Trigger) -> None:
+        for statement in self.get_trigger_create_sqls(model, trigger):
+            await self.editor.run_sql(statement)
+
+    async def remove_trigger(self, model: type[Model], trigger: Trigger) -> None:
+        table = self.editor.qualify_table_name(model._meta.db_table, model._meta.schema)
+        qualified_function = self.editor.qualify_table_name(trigger.function_name, model._meta.schema)
+        await self.editor.run_sql(
+            self.editor.TRIGGER_DROP_TEMPLATE.format(trigger_name=self.editor.quote(trigger.name), table=table)
+        )
+        await self.editor.run_sql(self.editor.TRIGGER_FUNCTION_DROP_TEMPLATE.format(function_name=qualified_function))
+
+    async def alter_trigger(self, model: type[Model], old_trigger: Trigger, new_trigger: Trigger) -> None:
+        # PostgreSQL can't alter a trigger's timing, events or body - it is dropped and created
+        # again.
+        await self.remove_trigger(model, old_trigger)
+        await self.add_trigger(model, new_trigger)
+
+    async def rename_trigger(self, model: type[Model], old_trigger: Trigger, new_trigger: Trigger) -> None:
+        if old_trigger.name == new_trigger.name:
+            return
+        if self.editor.RENAME_TRIGGER_TEMPLATE and self.editor.RENAME_TRIGGER_FUNCTION_TEMPLATE:
+            table = self.editor.qualify_table_name(model._meta.db_table, model._meta.schema)
+            await self.editor.run_sql(
+                self.editor.RENAME_TRIGGER_TEMPLATE.format(
+                    table=table,
+                    old_name=self.editor.quote(old_trigger.name),
+                    new_name=self.editor.quote(new_trigger.name),
+                )
+            )
+            # A renamed trigger's backing function is renamed to match, keeping
+            # Trigger.function_name's f"{name}_fn" convention consistent - RENAME TO takes just
+            # the new bare name, a function can't change schema this way (nor does it need to).
+            qualified_old_function = self.editor.qualify_table_name(old_trigger.function_name, model._meta.schema)
+            await self.editor.run_sql(
+                self.editor.RENAME_TRIGGER_FUNCTION_TEMPLATE.format(
+                    function_name=qualified_old_function,
+                    new_function_name=self.editor.quote(new_trigger.function_name),
+                )
+            )
+            return
+        await self.remove_trigger(model, old_trigger)
+        await self.add_trigger(model, new_trigger)
+
+    async def move_trigger_to_schema(
+        self, model: type[Model], trigger: Trigger, old_schema: str | None, new_schema: str | None
+    ) -> None:
+        """Moves the trigger's function - it lives in the table's schema."""
+        await self.editor.schemas.move_object_to_schema(
+            "FUNCTION", f"{self.editor.qualify_table_name(trigger.function_name, old_schema)}()", new_schema
+        )

hare/dialects/postgresql/search/__init__.py

@@ -0,0 +1,8 @@
+"""PostgreSQL's own part of full-text search - lexemes, weight labels and the tsvector/tsquery SQL
+terms; the search expressions are ``hare.search``'s."""
+
+from __future__ import annotations
+
+from hare.dialects.postgresql.search.lexemes.lexeme import Lexeme
+
+__all__ = ["Lexeme"]

hare/dialects/postgresql/search/constants.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import re
+
+#: The tsquery function per search type, keyed by ``SearchType`` values.
+SEARCH_TYPE_FUNCTIONS: dict[str, str] = {
+    "plain": "PLAINTO_TSQUERY",
+    "phrase": "PHRASETO_TSQUERY",
+    "raw": "TO_TSQUERY",
+    "websearch": "WEBSEARCH_TO_TSQUERY",
+}
+
+#: The tsquery operator joining two queries, keyed by ``SearchOperator`` values.
+POSTGRESQL_SEARCH_QUERY_OPERATORS: dict[str, str] = {"and": " && ", "or": " || "}
+
+#: The ``ts_headline()`` option of each ``SearchHeadline`` argument.
+POSTGRESQL_HEADLINE_OPTION_NAMES: dict[str, str] = {
+    "start_sel": "StartSel",
+    "stop_sel": "StopSel",
+    "max_words": "MaxWords",
+    "min_words": "MinWords",
+    "short_word": "ShortWord",
+    "highlight_all": "HighlightAll",
+    "max_fragments": "MaxFragments",
+    "fragment_delimiter": "FragmentDelimiter",
+}
+
+#: The operator joining the vectors of a ``TSVectorField``'s sources in its generation expression.
+POSTGRESQL_TS_VECTOR_CONCATENATION_SQL = " || "
+#: A weighted source vector as PostgreSQL echoes it back - ``setweight(<vector>, 'A'::"char")``.
+POSTGRESQL_TS_VECTOR_WEIGHTED_PATTERN = re.compile(
+    r"setweight\((?P<vector>.+), '(?P<weight>[A-D])'::\"char\"\)", re.DOTALL
+)
+#: A source vector - ``to_tsvector('english'::regconfig, <source>)``.
+POSTGRESQL_TS_VECTOR_PATTERN = re.compile(
+    r"to_tsvector\('(?P<config>(?:[^']|'')+)'::regconfig, (?P<source>.+)\)", re.DOTALL
+)
+#: The source of a vector - its column made text and its NULL empty:
+#: ``(COALESCE(title, ''::character varying))::text``, ``COALESCE(body, ''::text)``,
+#: ``COALESCE((number)::text, ''::text)``.
+POSTGRESQL_TS_VECTOR_SOURCE_PATTERN = re.compile(
+    r"\(?COALESCE\(\(?(?P<column>\"(?:[^\"]|\"\")+\"|[a-z_][a-z0-9_$]*)\)?(?:::text)?, ''::[a-z ]+\)\)?(?:::text)?"
+)

hare/dialects/postgresql/search/criterion/__init__.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from hare.dialects.postgresql.search.criterion.declarations import Comp, TsInfixOperator
+from hare.dialects.postgresql.search.criterion.search_criterion import SearchCriterion
+from hare.dialects.postgresql.search.criterion.ts_query_function import TsQueryFunction
+from hare.dialects.postgresql.search.criterion.ts_query_invert import TsQueryInvert
+
+__all__ = [
+    "Comp",
+    "SearchCriterion",
+    "TsQueryFunction",
+    "TsInfixOperator",
+    "TsQueryInvert",
+]

hare/dialects/postgresql/search/criterion/declarations.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from hare.sql.enums import Comparator
+from hare.sql.terms.infix_operator import InfixOperator
+
+
+class Comp(Comparator):
+    """hare.sql comparator for Postgres full-text search's ``@@`` match operator."""
+
+    search = " @@ "
+
+
+class TsInfixOperator(InfixOperator):
+    """A text search operator between two tsvectors or tsqueries (``||``, ``&&``)."""

hare/dialects/postgresql/search/criterion/search_criterion.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from hare.dialects.postgresql.search.criterion.declarations import Comp, TsInfixOperator
+from hare.dialects.postgresql.search.criterion.ts_query_function import TsQueryFunction
+from hare.dialects.postgresql.search.criterion.ts_query_invert import TsQueryInvert
+from hare.dialects.postgresql.search.functions.plain_to_ts_query import PlainToTsQuery
+from hare.dialects.postgresql.search.functions.to_ts_vector import ToTsVector
+from hare.sql.terms.criteria.basic_criterion import BasicCriterion
+from hare.sql.terms.term import Term
+from hare.sql.terms.values.value_wrapper import ValueWrapper
+
+
+class SearchCriterion(BasicCriterion):
+    """A ``tsvector @@ tsquery`` filter criterion, as used by the ``search`` field lookup.
+
+    Args:
+        term: The column (or already-built tsvector term) to match against.
+        expression: The search text, or an already-built tsquery term.
+        vectorize: If True, wraps ``term`` in ``TO_TSVECTOR()``; set False when ``term`` is
+            already a tsvector (e.g. a `TSVectorField`).
+        config: Text search configuration name (e.g. a `TSVectorField`'s own configured
+            language) - without it, TO_TSVECTOR()/PLAINTO_TSQUERY() both fall back to Postgres's
+            session default_text_search_config, which silently mismatches a column whose stored
+            vector was built with a DIFFERENT config (e.g. "russian"). Only applied to the pieces
+            this constructor builds - an already-built ``expression`` term is used as-is, and when
+            no config is given, the vectorized column uses that query's own configuration.
+    """
+
+    def __init__(
+        self, term: Term, expression: Term | str, vectorize: bool = True, config: str | Term | None = None
+    ) -> None:
+        vector_config = config
+        if vector_config is None and isinstance(expression, Term):
+            vector_config = self.get_query_config(expression)
+        vector = ToTsVector(term, config=vector_config) if vectorize else term
+        query = expression if isinstance(expression, Term) else PlainToTsQuery(ValueWrapper(expression), config=config)
+        super().__init__(Comp.search, vector, query)
+
+    @classmethod
+    def get_query_config(cls, query: Term) -> Term | None:
+        """The text search configuration an already-built tsquery term was built with.
+
+        Args:
+            query: The tsquery term.
+
+        Returns:
+            The configuration term, or None when the query has none (or its combined parts
+            disagree on one).
+        """
+        if isinstance(query, TsQueryFunction):
+            return query.config_term
+        if isinstance(query, TsQueryInvert):
+            return cls.get_query_config(query.term)
+        if isinstance(query, TsInfixOperator):
+            left_config = cls.get_query_config(query.left)
+            right_config = cls.get_query_config(query.right)
+            if left_config is None or right_config is None:
+                return None
+            if isinstance(left_config, ValueWrapper) and isinstance(right_config, ValueWrapper):
+                return left_config if left_config.value == right_config.value else None
+            return left_config if left_config is right_config else None
+        return None

hare/dialects/postgresql/search/criterion/ts_query_function.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from hare.sql.terms.functions.function import Function
+from hare.sql.terms.term import Term
+
+
+class TsQueryFunction(Function):
+    """A tsquery-building function call (``PLAINTO_TSQUERY(config, value)`` etc.), remembering its
+    text search configuration.
+
+    Args:
+        name: The SQL function name.
+        value: The query text term.
+        config_term: The configuration term, when given.
+    """
+
+    def __init__(self, name: str, value: Term, config_term: Term | None = None) -> None:
+        args = (config_term, value) if config_term is not None else (value,)
+        super().__init__(name, *args)
+        self.config_term = config_term