hare-orm 0.9.0__py3-none-any.whl

hare/dialects/clickhouse/client/constants.py

@@ -0,0 +1,211 @@
+from __future__ import annotations
+
+import datetime
+import ipaddress
+import re
+import uuid
+from decimal import Decimal
+
+#: A read grouped ``WITH TOTALS`` - as the dialect writes the modifier; its totals row is read with its rows.
+CLICKHOUSE_WITH_TOTALS_PATTERN = re.compile(r"\sWITH TOTALS\b")
+#: A write of stored rows - an UPDATE or a DELETE, a mutation or a lightweight one; the server reports no
+#: count of the rows it changes.
+CLICKHOUSE_ROW_WRITE_PATTERN = re.compile(
+    r"\s*(?:ALTER\s+TABLE\s+.+?\s+(?:UPDATE|DELETE)\s|UPDATE\s|DELETE\s+FROM\s)", re.IGNORECASE | re.DOTALL
+)
+#: The mutations a failed write names - ``... during execution of mutation 'mutation_9.txt' ...`` or
+#: ``... of mutations 'mutation_10.txt, mutation_9.txt' ...``.
+CLICKHOUSE_FAILED_MUTATIONS_PATTERN = re.compile(r"execution of mutations? '([^']+)'")
+
+#: Stops failed mutations of a table - one left would fail every later mutation of the table, and
+#: could still change its rows once the write that made it has raised; only a mutation that has failed
+#: is stopped (``{0}``: ``ON CLUSTER``,
+#: ``{1}``: the table's name, ``{2}``: the mutations' ids, as literals).
+CLICKHOUSE_KILL_MUTATIONS_TEMPLATE = (
+    "KILL MUTATION{on_cluster} WHERE database = {database} AND table = {table} AND mutation_id IN ({ids}) "
+    "AND latest_fail_reason != ''"
+)
+
+#: The ClickHouse error code of a session another request of it still holds - a statement the client
+#: stopped waiting for runs on in the session of its transaction.
+CLICKHOUSE_SESSION_IS_LOCKED_ERROR_CODE = 373
+#: How long a rollback waits for its session held by such a statement - the server's own session
+#: timeout, after which the session ends with its transaction anyway.
+CLICKHOUSE_LOCKED_SESSION_ROLLBACK_SECONDS = 60
+#: How often a rollback asks again for its session held by such a statement.
+CLICKHOUSE_LOCKED_SESSION_RETRY_SECONDS = 0.05
+
+#: The ClickHouse error codes of a statement against the data - a violated CHECK constraint.
+CLICKHOUSE_INTEGRITY_ERROR_CODES = frozenset({469})
+#: The ClickHouse error code of a value of a type it can't convert - NULL written into a NOT NULL
+#: column among them, told apart by its message.
+CLICKHOUSE_CANNOT_CONVERT_TYPE_ERROR_CODE = 70
+CLICKHOUSE_NULL_INTO_NOT_NULL_MESSAGE = "Cannot convert NULL to a non-nullable type"
+
+#: The ClickHouse error code of a TTL the server keeps none by.
+CLICKHOUSE_BAD_TTL_EXPRESSION_ERROR_CODE = 450
+#: What a TTL of a nullable column takes - the server keeps no TTL of a value that may be NULL.
+CLICKHOUSE_NULLABLE_TTL_EXPRESSION_HINT = (
+    "a TTL is of a moment that is never NULL - the column is nullable: assumeNotNull(seen) + INTERVAL 30 DAY, or "
+    "ifNull(seen, now()) + INTERVAL 30 DAY"
+)
+#: How the server names a nullable type in an error.
+CLICKHOUSE_NULLABLE_TYPE_MARK = "Nullable("
+
+#: The server setting stopping a statement that runs longer, in seconds.
+CLICKHOUSE_MAX_EXECUTION_TIME_SETTING = "max_execution_time"
+#: How much longer than the server's limit of a statement the HTTP client waits for its answer.
+CLICKHOUSE_HTTP_RECEIVE_TIMEOUT_MARGIN_SECONDS = 1
+#: The ClickHouse error code of a statement the server can't run yet - in a transaction, one of a
+#: table or a type of query transactions don't take.
+CLICKHOUSE_NOT_IMPLEMENTED_ERROR_CODE = 48
+#: A transaction's statement met a part another transaction holds - retrying the transaction can succeed.
+CLICKHOUSE_SERIALIZATION_ERROR_CODE = 650
+#: The failure of a mutation, wrapping the error it met - a serialization error by this text.
+CLICKHOUSE_UNFINISHED_ERROR_CODE = 341
+CLICKHOUSE_SERIALIZATION_ERROR_MESSAGE = "Serialization error"
+#: The part of that error's message for a correlated subquery reading a column of a table joined to the
+#: query around it.
+CLICKHOUSE_JOINED_CORRELATED_COLUMN_MESSAGE = "can't find correlated column"
+#: What the refusal of such a subquery adds to the server's message.
+CLICKHOUSE_JOINED_CORRELATED_COLUMN_HINT = (
+    "ClickHouse correlates a subquery by the columns of the outer query's own table only - an "
+    "OuterReference across a relation (OuterReference('book__author_id')) reads a joined one; reach "
+    "the relation inside the subquery instead (Author.objects.filter(books__id=OuterReference('book_id')))"
+)
+
+#: The ClickHouse error codes of a connection that can't be used: the server refused or dropped it.
+CLICKHOUSE_CONNECTION_ERROR_CODES = frozenset({209, 210})
+
+#: The ClickHouse error codes of refused credentials - a password required or wrong. No retry fixes
+#: them: a ConfigurationError, as on PostgreSQL.
+CLICKHOUSE_AUTHENTICATION_ERROR_CODES = frozenset({194, 516})
+CLICKHOUSE_AUTHENTICATION_FAILED_MESSAGE = (
+    "Authentication failed connecting to ClickHouse as user {user!r} - check the configured password/credentials. "
+    "Exception: {error}"
+)
+
+#: The ClickHouse error code of a database that doesn't exist, and how the server names it - the
+#: connection's own database missing is a ConfigurationError, as on PostgreSQL.
+CLICKHOUSE_UNKNOWN_DATABASE_ERROR_CODE = 81
+CLICKHOUSE_UNKNOWN_DATABASE_TEXT = "Database {database} does not exist"
+CLICKHOUSE_MISSING_DATABASE_MESSAGE = "Can't use database {database} - it doesn't exist. Exception: {error}"
+
+#: Where a ClickHouse error message names its error code - ``Code: 469.``.
+CLICKHOUSE_ERROR_CODE_PREFIX = "Code: "
+
+#: The arguments a client takes besides its connection settings - every other one must be a setting.
+CLICKHOUSE_CLIENT_BASE_SETTINGS = frozenset({"connection_alias"})
+
+#: The database of a connection naming none.
+CLICKHOUSE_DEFAULT_DATABASE = "default"
+#: The values of the connection settings left unset.
+CLICKHOUSE_CONNECTION_OPTION_DEFAULTS = {
+    "secure": False,
+    "native_port": None,
+    "compress": True,
+    "connect_timeout": 10,
+    "send_receive_timeout": 300,
+    "cluster": None,
+    "async_insert": False,
+    "wait_for_async_insert": True,
+    "transactions": False,
+    "keeper_hosts": None,
+}
+
+#: The interactive client ``hare dbshell`` opens - it speaks ClickHouse's native protocol, on its own
+#: port (``native_port``; the client's default without it), not the HTTP port.
+CLICKHOUSE_SHELL_PROGRAM = "clickhouse-client"
+
+CLICKHOUSE_SHELL_PASSWORD_VARIABLE = "CLICKHOUSE_PASSWORD"  # nosec B105 - an environment variable name
+
+#: What may come before a statement's first word: spaces, opening brackets and comments.
+CLICKHOUSE_STATEMENT_PREFIX_PATTERN = re.compile(r"(?:\s+|\(|--[^\n]*|/\*.*?\*/)*", re.DOTALL)
+
+#: The first words of the statements that return rows - every other statement is a command.
+CLICKHOUSE_ROW_RETURNING_KEYWORDS = frozenset({"SELECT", "WITH", "SHOW", "DESCRIBE", "DESC", "EXPLAIN", "EXISTS"})
+
+#: The types of the values a driver's binary insert writes as they are - a column holding no other
+#: is passed to it untouched. A ``datetime`` is not among them: ``type()`` of one is not ``date``.
+CLICKHOUSE_INSERTED_AS_IS_TYPES = frozenset({int, float, bool, type(None), Decimal, uuid.UUID, datetime.date})
+#: The types of the values of a column of mixed types the insert writes as they are - a date is
+#: not among them: each is checked to be one ClickHouse stores.
+CLICKHOUSE_INSERTED_UNCHANGED_VALUE_TYPES = frozenset(
+    {int, float, bool, type(None), Decimal, uuid.UUID, ipaddress.IPv4Address, ipaddress.IPv6Address}
+)
+
+#: The types of a column of moments, each written in UTC.
+CLICKHOUSE_INSERTED_MOMENT_COLUMN_TYPES = frozenset({datetime.datetime, type(None)})
+
+#: The types of a column of text.
+CLICKHOUSE_INSERTED_TEXT_COLUMN_TYPES = frozenset({str, type(None)})
+
+#: The most statements whose placeholder layout a ClickHouse client keeps - the statements of an
+#: application's queries are few; a raw statement of ever different text must not grow it for good.
+CLICKHOUSE_QUERY_TEMPLATE_CACHE_MAX_SIZE = 4096
+
+#: How many rows a batch of a streamed query holds when the reader names no number.
+CLICKHOUSE_STREAM_BATCH_SIZE = 1000
+
+#: The statements of a transaction's control.
+CLICKHOUSE_BEGIN_TRANSACTION_SQL = "BEGIN TRANSACTION"
+CLICKHOUSE_COMMIT_SQL = "COMMIT"
+CLICKHOUSE_ROLLBACK_SQL = "ROLLBACK"
+#: Why the statements of a transaction after a failed one are refused - the server rolled it back.
+CLICKHOUSE_TRANSACTION_ABORTED_MESSAGE = (
+    "A statement of the ClickHouse transaction failed - the server rolled the transaction back and takes no "
+    "statement of it but its ROLLBACK"
+)
+#: What a transaction's client takes over from the client it is opened on.
+CLICKHOUSE_TRANSACTION_CLIENT_ATTRIBUTES = (
+    "host",
+    "port",
+    "user",
+    "password",
+    "database",
+    "options",
+    "cluster",
+    "dialect",
+    "query_class",
+    "pool_statistics",
+)
+#: The column types of a table - of the database given, of the connection's with an empty name.
+CLICKHOUSE_TABLE_COLUMN_TYPES_SQL = (
+    "SELECT name, type FROM system.columns WHERE database = if($1 = '', currentDatabase(), $1) AND table = $2"
+)
+
+#: What a connection learns of the server: whether it has the table of its ClickHouse Keeper connections -
+#: the keys of series (generateSerialID) need a Keeper it reaches.
+CLICKHOUSE_SERVER_FACTS_SQL = (
+    "SELECT (SELECT count() FROM system.tables WHERE database = 'system' AND name = 'zookeeper_connection') "
+    "AS keeper_tables"
+)
+CLICKHOUSE_KEEPER_CONNECTIONS_SQL = "SELECT count() AS keepers FROM system.zookeeper_connection"
+#: The next keys of a series.
+CLICKHOUSE_KEY_SERIES_TAKE_SQL = "SELECT generateSerialID({series}) FROM numbers({count})"
+#: How many keys a series lags behind the greatest key of its table - its next key taken, and the ones
+#: up to the greatest key still to be.
+CLICKHOUSE_KEY_SERIES_GAP_SQL = "SELECT (SELECT max({key}) FROM {table}) - generateSerialID({series}) AS gap"
+#: Keys of a series taken and dropped - the series moved past them. Their greatest one is read: a key no
+#: expression reads isn't taken.
+CLICKHOUSE_KEY_SERIES_SKIP_SQL = "SELECT max(generateSerialID({series})) AS last FROM numbers({count})"
+#: The format of an external table's data.
+CLICKHOUSE_TAB_SEPARATED_FORMAT = "TabSeparated"
+#: The name of the external table of the n-th set of a statement, and of its n-th column.
+CLICKHOUSE_EXTERNAL_SET_NAME_TEMPLATE = "hare_set_{}"
+CLICKHOUSE_EXTERNAL_SET_COLUMN_TEMPLATE = "value{}"
+#: The characters of a text the ``TabSeparated`` format escapes, but the line break between rows.
+CLICKHOUSE_TAB_SEPARATED_SPECIAL_CHARACTERS = ("\\", "\t", "\r", "\0")
+#: How a text is escaped in a value of the ``TabSeparated`` format.
+CLICKHOUSE_TAB_SEPARATED_ESCAPES = str.maketrans({"\\": "\\\\", "\t": "\\t", "\n": "\\n", "\r": "\\r", "\0": "\\0"})
+
+#: The refusal of a savepoint - a ClickHouse transaction has none.
+CLICKHOUSE_NO_SAVEPOINTS_MESSAGE = "ClickHouse transactions have no savepoints"
+
+#: The error of a statement whose connection was closed while it opened - closed in its turn.
+CLICKHOUSE_CLOSED_WHILE_OPENING_MESSAGE = "The connection was closed while it was opening"
+
+#: The error of a statement on a client closed and dropped - it opens no connection again.
+CLICKHOUSE_DISCARDED_CLIENT_MESSAGE = (
+    "The connection {alias!r} was closed and dropped - a query runs on the connection the context gives now"
+)

hare/dialects/clickhouse/client/declarations.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import dataclasses
+from typing import Any
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class ClickhouseDriverErrors:
+    """The exception classes of a ClickHouse driver, one class or several of each sort - read by
+    the shared client only once a statement failed.
+
+    Attributes:
+        server: An error the server reported, its message naming the ClickHouse error code.
+        connection: The server couldn't be reached or the connection broke.
+        driver: Any other error of the driver.
+    """
+
+    server: type[Exception] | tuple[type[Exception], ...]
+    connection: type[Exception] | tuple[type[Exception], ...]
+    driver: type[Exception] | tuple[type[Exception], ...]
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class ClickhouseValueSet:
+    """The values of a long ``IN`` list bound as one parameter - sent as an external table by a read,
+    written as a list of literals by any other statement.
+
+    Attributes:
+        column_types: The type of each value of a row - one for a list of single values.
+        rows: The values - single values, or a tuple per row of several.
+    """
+
+    column_types: tuple[str, ...]
+    rows: list[Any]
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class ClickhouseExternalSet:
+    """An external table a read sends beside its statement, named by the statement in place of a list.
+
+    Attributes:
+        name: The table's name.
+        value_set: Its values.
+    """
+
+    name: str
+    value_set: ClickhouseValueSet

hare/dialects/clickhouse/cluster/clickhouse_cluster.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+from hare.dialects.clickhouse.client.constants import CLICKHOUSE_DEFAULT_DATABASE
+from hare.dialects.clickhouse.cluster.clickhouse_cluster_statements import ClickhouseClusterStatements
+from hare.dialects.clickhouse.cluster.constants import (
+    CLICKHOUSE_DATABASE_ENGINE_SQL,
+    CLICKHOUSE_DISTRIBUTED_CREATE_PATTERN,
+    CLICKHOUSE_DISTRIBUTED_TABLES_SQL,
+    CLICKHOUSE_REPLICA_SYNC_TEMPLATE,
+    CLICKHOUSE_REPLICATED_DATABASE_ENGINE,
+    CLICKHOUSE_REPLICATED_ENGINE_PREFIX,
+    CLICKHOUSE_TABLE_ENGINE_SQL,
+)
+from hare.dialects.clickhouse.introspection.clickhouse_sql_parts import ClickhouseSqlParts
+from hare.dialects.clickhouse.introspection.constants import CLICKHOUSE_PLAIN_IDENTIFIER_PATTERN
+from hare.dialects.clickhouse.types.clickhouse_type_names import ClickhouseTypeNames
+from hare.exceptions import ConfigurationError
+
+if TYPE_CHECKING:
+    from hare.dialects.clickhouse.client.clickhouse_client import ClickhouseClient
+
+
+class ClickhouseCluster:
+    """The cluster a connection belongs to (its ``cluster`` setting): what the connection's database
+    replicates by itself, which of its tables are distributed, and how a statement runs on it.
+
+    Args:
+        client: The connection.
+        name: The cluster's name, as the servers know it.
+
+    Raises:
+        ConfigurationError: The name isn't a cluster's name.
+    """
+
+    __slots__ = ("client", "name", "distributed_tables", "replicates_schema")
+
+    def __init__(self, client: ClickhouseClient, name: str) -> None:
+        if not CLICKHOUSE_PLAIN_IDENTIFIER_PATTERN.fullmatch(name):
+            raise ConfigurationError(f"A ClickHouse connection's cluster must be a cluster's name, got {name!r}")
+        self.client = client
+        self.name = name
+        #: The local table of each distributed table of the server, by its database and name - None until
+        #: read; read again after a script, which may create and drop tables.
+        self.distributed_tables: dict[tuple[str, str], str] | None = None
+        #: Whether the database replicates a change of the schema itself - None until read.
+        self.replicates_schema: bool | None = None
+
+    def forget_tables(self) -> None:
+        """Has the distributed tables read again by the next statement that needs them."""
+        self.distributed_tables = None
+
+    @property
+    def database(self) -> str:
+        """The connection's database - of a table a statement names without one."""
+        return self.client.database or CLICKHOUSE_DEFAULT_DATABASE
+
+    async def fetch_distributed_tables(self) -> dict[tuple[str, str], str]:
+        """The distributed tables of the server.
+
+        Returns:
+            The database and name of each -> the name of the local table whose rows it spreads.
+        """
+        if self.distributed_tables is None:
+            rows = await self.client.execute_dicts(CLICKHOUSE_DISTRIBUTED_TABLES_SQL)
+            self.distributed_tables = {}
+            for row in rows:
+                local_table = ClickhouseSqlParts.get_name_argument(
+                    ClickhouseTypeNames.get_type_parts(str(row["engine_full"]))[1][2]
+                )
+                if local_table is not None:
+                    self.distributed_tables[str(row["database"]), str(row["name"])] = local_table
+        return self.distributed_tables
+
+    async def fetch_replicates_schema(self) -> bool:
+        """Whether the connection's database replicates a change of the schema by itself - a database
+        of the ``Replicated`` engine, which refuses ``ON CLUSTER``.
+
+        Returns:
+            Whether it does.
+        """
+        if self.replicates_schema is None:
+            rows = await self.client.execute_dicts(CLICKHOUSE_DATABASE_ENGINE_SQL)
+            self.replicates_schema = bool(rows) and rows[0]["engine"] == CLICKHOUSE_REPLICATED_DATABASE_ENGINE
+        return self.replicates_schema
+
+    async def get_statements(self, statements: Sequence[str]) -> list[str]:
+        """What the statements of a script run as on the cluster.
+
+        Args:
+            statements: The statements.
+
+        Returns:
+            The statements - a change of the schema over the cluster, a change of a distributed
+            table where it belongs.
+        """
+        distributed_tables = dict(await self.fetch_distributed_tables())
+        replicates_schema = await self.fetch_replicates_schema()
+        cluster_statements = []
+        for statement in statements:
+            cluster_statements.extend(
+                ClickhouseClusterStatements.get_statements(
+                    statement,
+                    self.name,
+                    distributed_tables,
+                    database=self.database,
+                    replicates_schema=replicates_schema,
+                )
+            )
+            # A distributed table the script creates takes the statements after it.
+            if (created := CLICKHOUSE_DISTRIBUTED_CREATE_PATTERN.match(statement)) is not None:
+                created_database, created_table = ClickhouseClusterStatements.get_table_key(created.group("name"))
+                distributed_tables[created_database or self.database, created_table] = (
+                    ClickhouseClusterStatements.get_table_name(created.group("local"))
+                )
+        return cluster_statements
+
+    async def get_write_sql(self, write_sql: str) -> str:
+        """What a write of stored rows runs as on the cluster - the rows of a distributed table are
+        changed in its local table on every server.
+
+        Args:
+            write_sql: The write.
+
+        Returns:
+            The write over the cluster.
+        """
+        distributed_tables = await self.fetch_distributed_tables()
+        if not distributed_tables:
+            return write_sql
+        (cluster_write_sql,) = ClickhouseClusterStatements.get_statements(
+            write_sql, self.name, distributed_tables, database=self.database, replicates_schema=True
+        )
+        return cluster_write_sql
+
+    def get_database_statement(self, statement: str) -> str:
+        """A statement creating or dropping the connection's database, on every server.
+
+        Args:
+            statement: ``CREATE DATABASE ...`` or ``DROP DATABASE ...``.
+
+        Returns:
+            The statement over the cluster.
+        """
+        return ClickhouseClusterStatements.get_statements(statement, self.name, {}, database=self.database)[0]
+
+    async def synchronize_table(self, table_name: str) -> None:
+        """Waits until the connection's server holds every row written to a replicated table through
+        the other replicas.
+
+        Args:
+            table_name: The table.
+        """
+        rows = await self.client.execute_dicts(CLICKHOUSE_TABLE_ENGINE_SQL, [table_name])
+        if rows and str(rows[0]["engine"]).startswith(CLICKHOUSE_REPLICATED_ENGINE_PREFIX):
+            await self.client.execute_script(
+                CLICKHOUSE_REPLICA_SYNC_TEMPLATE.format(
+                    table=self.client.dialect.literals.quote_identifier(table_name)
+                )
+            )

hare/dialects/clickhouse/cluster/clickhouse_cluster_statements.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from hare.dialects.clickhouse.cluster.constants import (
+    CLICKHOUSE_CLUSTER_STATEMENT_PATTERN,
+    CLICKHOUSE_COLUMN_CHANGE_PATTERN,
+    CLICKHOUSE_COLUMN_REWRITE_CLAUSE_PATTERN,
+    CLICKHOUSE_COLUMN_STORAGE_PATTERN,
+    CLICKHOUSE_DICTIONARY_RELOAD_PATTERN,
+    CLICKHOUSE_ON_CLUSTER_PATTERN,
+    CLICKHOUSE_RENAME_STATEMENT_PATTERN,
+    CLICKHOUSE_ROW_CHANGE_PATTERN,
+)
+from hare.dialects.clickhouse.introspection.clickhouse_sql_parts import ClickhouseSqlParts
+
+
+class ClickhouseClusterStatements:
+    """The statements of a connection to a cluster: a change of the schema runs on every server
+    (``ON CLUSTER``), and a change of a distributed table goes where it belongs - a change of rows and of
+    storage to the local table on every server, a change of columns to both tables."""
+
+    @classmethod
+    def get_statements(
+        cls,
+        statement: str,
+        cluster: str,
+        distributed_tables: Mapping[tuple[str, str], str],
+        *,
+        database: str,
+        replicates_schema: bool = False,
+    ) -> list[str]:
+        """Returns what a statement runs as on a cluster.
+
+        Args:
+            statement: One statement.
+            cluster: The cluster's name.
+            distributed_tables: The database and name of each distributed table -> the name of the
+                local table whose rows it spreads, in the same database.
+            database: The connection's database - of a table the statement names without one.
+            replicates_schema: Whether the database replicates a change of the schema itself - then
+                nothing names the cluster but a change of a distributed table's rows.
+
+        Returns:
+            The statements - the statement itself when it is none a cluster runs another way.
+        """
+        if ClickhouseSqlParts.search_outside_strings(CLICKHOUSE_ON_CLUSTER_PATTERN, statement):
+            return [statement]
+        on_cluster_sql = "" if replicates_schema else f" ON CLUSTER {cluster}"
+        if CLICKHOUSE_RENAME_STATEMENT_PATTERN.match(statement):
+            return [f"{statement.rstrip().rstrip(';')}{on_cluster_sql}"]
+        if (reload_match := CLICKHOUSE_DICTIONARY_RELOAD_PATTERN.fullmatch(statement)) is not None:
+            cluster_sql = f"{on_cluster_sql.lstrip()} " if on_cluster_sql else ""
+            return [f"{reload_match.group(1)}{cluster_sql}{reload_match.group(2)}"]
+        match = CLICKHOUSE_CLUSTER_STATEMENT_PATTERN.fullmatch(statement)
+        if match is None:
+            return [statement]
+        head, name, rest = match.group("head"), match.group("name"), match.group("rest")
+        verb = head.split()[0].upper()
+        table_database, table_name = cls.get_table_key(name)
+        local_table = distributed_tables.get((table_database or database, table_name))
+        changes_rows = verb == "DELETE" or (verb == "ALTER" and CLICKHOUSE_ROW_CHANGE_PATTERN.match(rest) is not None)
+        if local_table is None:
+            # The rows of a table are changed where the statement is sent: a replicated table copies
+            # the change to its replicas itself.
+            return [statement if changes_rows else f"{head}{name}{on_cluster_sql}{rest}"]
+        local_name = cls.get_local_name(name, local_table)
+        if changes_rows:
+            # Over the cluster whatever the database replicates: each shard holds rows of its own.
+            return [f"{head}{local_name} ON CLUSTER {cluster}{rest}"]
+        local_statement = f"{head}{local_name}{on_cluster_sql}{rest}"
+        distributed_statement = f"{head}{name}{on_cluster_sql}{rest}"
+        if verb == "ALTER" and cls.changes_columns(rest):
+            # The local table's rows are rewritten with the change - the distributed table has none.
+            distributed_rest = CLICKHOUSE_COLUMN_REWRITE_CLAUSE_PATTERN.sub("", rest)
+            return [local_statement, f"{head}{name}{on_cluster_sql}{distributed_rest}"]
+        # The distributed table itself is created and dropped; any other change is of the storage.
+        return [distributed_statement] if verb in {"CREATE", "DROP"} else [local_statement]
+
+    @staticmethod
+    def changes_columns(alter_sql: str) -> bool:
+        """Whether an ``ALTER TABLE`` changes what columns a table has - not how one is stored.
+
+        Args:
+            alter_sql: The statement after its table's name.
+
+        Returns:
+            Whether a distributed table takes the change with its local one.
+        """
+        return (
+            CLICKHOUSE_COLUMN_CHANGE_PATTERN.match(alter_sql) is not None
+            and ClickhouseSqlParts.search_outside_strings(CLICKHOUSE_COLUMN_STORAGE_PATTERN, alter_sql) is None
+        )
+
+    @staticmethod
+    def get_table_key(name_sql: str) -> tuple[str | None, str]:
+        """The database and the own name of a table, as a statement names it.
+
+        Args:
+            name_sql: The name - quoted or plain, with its database or without.
+
+        Returns:
+            The database without its quotes - None for a name without one - and the table's own name.
+        """
+        name, rest = ClickhouseSqlParts.get_leading_identifier(name_sql)
+        if not rest.startswith("."):
+            return None, name
+        table_name, _ = ClickhouseSqlParts.get_leading_identifier(rest[1:])
+        return name, table_name
+
+    @staticmethod
+    def get_name_parts(name_sql: str) -> tuple[str, str]:
+        """Splits how a statement names a table into its database and its own name.
+
+        Args:
+            name_sql: The name - quoted or plain, with its database or without.
+
+        Returns:
+            The database with the dot after it, as written - empty without one - and the table's own name
+            without its quotes.
+        """
+        name, rest = ClickhouseSqlParts.get_leading_identifier(name_sql)
+        if not rest.startswith("."):
+            return "", name
+        table_name, _ = ClickhouseSqlParts.get_leading_identifier(rest[1:])
+        return name_sql[: len(name_sql) - len(rest) + 1], table_name
+
+    @classmethod
+    def get_table_name(cls, name_sql: str) -> str:
+        """A table's own name of how a statement names it.
+
+        Args:
+            name_sql: The name - quoted or plain, with its database or without.
+
+        Returns:
+            The name without its quotes and its database.
+        """
+        return cls.get_table_key(name_sql)[1]
+
+    @classmethod
+    def get_local_name(cls, name_sql: str, local_table: str) -> str:
+        """The local table of a distributed one, named as a statement names the distributed one.
+
+        Args:
+            name_sql: The distributed table as the statement names it.
+            local_table: The local table's name.
+
+        Returns:
+            The local table - quoted, in the same database.
+        """
+        database_sql, _ = cls.get_name_parts(name_sql)
+        # A backslash escapes the next character of a quoted name, a doubled quote is one.
+        quoted_table = local_table.replace("\\", "\\\\").replace('"', '""')
+        return f'{database_sql}"{quoted_table}"'

hare/dialects/clickhouse/cluster/constants.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import re
+
+#: The engine of a database replicating its DDL to its servers by itself.
+CLICKHOUSE_REPLICATED_DATABASE_ENGINE = "Replicated"
+CLICKHOUSE_DATABASE_ENGINE_SQL = "SELECT engine FROM system.databases WHERE name = currentDatabase()"
+#: The tables of the server spreading the rows of a local table over the cluster, with their databases.
+CLICKHOUSE_DISTRIBUTED_TABLES_SQL = (
+    "SELECT database, name, engine_full FROM system.tables WHERE engine = 'Distributed'"
+)
+#: The engines keeping a copy of a table's rows on every replica.
+CLICKHOUSE_REPLICATED_ENGINE_PREFIX = "Replicated"
+CLICKHOUSE_TABLE_ENGINE_SQL = "SELECT engine FROM system.tables WHERE database = currentDatabase() AND name = $1"
+#: A replica brought up to the rows written through the other ones.
+CLICKHOUSE_REPLICA_SYNC_TEMPLATE = "SYSTEM SYNC REPLICA {table}"
+#: The engine of a table spreading the rows of a local one over a cluster, by a key or to any shard.
+#: ``{database}`` - ``currentDatabase()`` for a table of the connection's database, the name of another.
+CLICKHOUSE_DISTRIBUTED_ENGINE_TEMPLATE = "Distributed({cluster}, {database}, {table}{sharding_key})"
+CLICKHOUSE_DISTRIBUTED_TABLE_TEMPLATE = "CREATE {or_replace}TABLE {exists}{table} AS {local_table} ENGINE = {engine};"
+#: The engine of the journal of applied migrations on a cluster.
+CLICKHOUSE_REPLICATED_JOURNAL_ENGINE = "ReplicatedMergeTree"
+#: The servers a cluster runs a statement on.
+CLICKHOUSE_CLUSTER_HOSTS_SQL = (
+    "SELECT count() AS hosts, uniqExact(shard_num) AS shards FROM system.clusters WHERE cluster = $1"
+)
+#: A name in backquotes or double quotes - a backslash escapes the next character, a doubled quote is one.
+CLICKHOUSE_QUOTED_NAME = r'(?:`(?:[^`\\]|\\.|``)+`|"(?:[^"\\]|\\.|"")+")'
+#: The name of a table - quoted or plain, with its database or without.
+CLICKHOUSE_STATEMENT_NAME = (
+    rf"(?:{CLICKHOUSE_QUOTED_NAME}|[A-Za-z_][A-Za-z0-9_]*)(?:\.(?:{CLICKHOUSE_QUOTED_NAME}|[A-Za-z_][A-Za-z0-9_]*))?"
+)
+#: The statements a cluster runs on every server, each up to the name ``ON CLUSTER`` follows.
+CLICKHOUSE_CLUSTER_STATEMENT_PATTERN = re.compile(
+    r"\s*(?P<head>"
+    r"CREATE\s+(?:OR\s+REPLACE\s+)?(?:TABLE|VIEW|MATERIALIZED\s+VIEW|DICTIONARY|DATABASE)\s+(?:IF\s+NOT\s+EXISTS\s+)?"
+    r"|ALTER\s+TABLE\s+"
+    r"|DROP\s+(?:TABLE|VIEW|DICTIONARY|DATABASE)\s+(?:IF\s+EXISTS\s+)?"
+    r"|TRUNCATE\s+TABLE\s+(?:IF\s+EXISTS\s+)?"
+    r"|DELETE\s+FROM\s+"
+    rf")(?P<name>{CLICKHOUSE_STATEMENT_NAME})(?P<rest>.*)",
+    re.IGNORECASE | re.DOTALL,
+)
+#: A rename - ``ON CLUSTER`` closes it.
+CLICKHOUSE_RENAME_STATEMENT_PATTERN = re.compile(r"\s*RENAME\s+(?:TABLE|DICTIONARY)\s", re.IGNORECASE)
+#: A dictionary loaded again - ``ON CLUSTER`` stands before its name.
+CLICKHOUSE_DICTIONARY_RELOAD_PATTERN = re.compile(
+    r"(\s*SYSTEM\s+RELOAD\s+DICTIONARY\s+)(.*)", re.IGNORECASE | re.DOTALL
+)
+#: A statement naming its cluster itself.
+CLICKHOUSE_ON_CLUSTER_PATTERN = re.compile(r"\sON\s+CLUSTER\s", re.IGNORECASE)
+#: The first words of the statements changing rows, not the schema - a mutation, a lightweight DELETE:
+#: they run where they are sent, but for the rows of a distributed table.
+CLICKHOUSE_ROW_CHANGE_PATTERN = re.compile(r"\s*(?:UPDATE|DELETE)\s", re.IGNORECASE)
+#: The changes of a table's columns a distributed table takes as its local one does.
+CLICKHOUSE_COLUMN_CHANGE_PATTERN = re.compile(
+    r"\s*(?:(?:ADD|DROP|MODIFY|RENAME|COMMENT)\s+COLUMN|MODIFY\s+COMMENT)\s", re.IGNORECASE
+)
+#: The rewrite of a column's rows a column change ends with (``MODIFY COLUMN ..., UPDATE c = c WHERE 1``) -
+#: a distributed table holds no rows and takes no mutation, it takes the column change alone.
+CLICKHOUSE_COLUMN_REWRITE_CLAUSE_PATTERN = re.compile(
+    rf",\s*UPDATE\s+({CLICKHOUSE_QUOTED_NAME}|\w+)\s*=\s*\1\s+WHERE\s+1\s*;?\s*$", re.IGNORECASE
+)
+#: The changes of how a column is stored - of the local table alone.
+CLICKHOUSE_COLUMN_STORAGE_PATTERN = re.compile(r"\s(?:CODEC\s*\(|TTL\s|REMOVE\s+(?:CODEC|TTL)\b)", re.IGNORECASE)
+#: The setting a write into a distributed table waits for its shards by.
+CLICKHOUSE_CLUSTER_SESSION_SETTINGS = {"distributed_foreground_insert": 1}
+#: A distributed table created by a script - the statements after it are run by it.
+CLICKHOUSE_DISTRIBUTED_CREATE_PATTERN = re.compile(
+    r"\s*CREATE\s+(?:OR\s+REPLACE\s+)?TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?"
+    rf"(?P<name>{CLICKHOUSE_STATEMENT_NAME})\s+AS\s+(?P<local>{CLICKHOUSE_STATEMENT_NAME})\s+ENGINE\s*=\s*Distributed\b",
+    re.IGNORECASE,
+)
+#: The macro a replica path names its shard by - a replicated table's replicas are then those of one shard.
+CLICKHOUSE_SHARD_MACRO = "{shard}"
+#: The refusal of a distributed table whose local tables a plain engine keeps on a cluster with several
+#: replicas of a shard - a written row lands on one replica, and a read may ask another.
+CLICKHOUSE_UNREPLICATED_LOCAL_TABLES_MESSAGE = (
+    "{model}: the local tables of the distributed table are kept by {engine} on the cluster {cluster!r}, whose "
+    "shards have several replicas - a row written lands on one replica, and a read may ask another. Store "
+    'them by a Replicated engine (ClickhouseTableOptions(engine="ReplicatedMergeTree", ...))'
+)

hare/dialects/clickhouse/connection/__init__.py

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