sqlide 0.1.0__py3-none-any.whl

sqlide/sql/context.py

@@ -0,0 +1,195 @@
+"""What is the user typing? Pure analysis of the statement around the cursor.
+
+No metadata, no UI: it only says what *kind* of name is expected and which tables the
+statement mentions, so a provider can fetch candidates.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from sqlide.sql.dialects import RULES, Rules
+from sqlide.sql.lexer import (
+    BLOCK_COMMENT,
+    LINE_COMMENT,
+    LPAREN,
+    QIDENT,
+    RPAREN,
+    SEMI,
+    STRING,
+    WORD,
+    WS,
+    Token,
+    tokenize,
+)
+
+TABLE_KEYWORDS = frozenset({"FROM", "JOIN", "INTO", "UPDATE", "TABLE", "DESCRIBE", "TRUNCATE"})
+CLAUSE_KEYWORDS = TABLE_KEYWORDS | {
+    "SELECT", "WHERE", "ON", "GROUP", "ORDER", "HAVING", "SET", "VALUES", "BY", "AND", "OR",
+    "WHEN", "THEN", "ELSE", "USING", "RETURNING",
+}  # fmt: skip
+# a word that follows a table reference but is not its alias
+NOT_ALIAS = frozenset(
+    {
+        "WHERE", "GROUP", "ORDER", "HAVING", "LIMIT", "OFFSET", "UNION", "INTERSECT", "EXCEPT",
+        "JOIN", "INNER", "LEFT", "RIGHT", "FULL", "CROSS", "OUTER", "NATURAL", "ON", "USING",
+        "SET", "VALUES", "SELECT", "RETURNING", "FETCH", "WINDOW", "FOR", "LATERAL", "FINAL",
+        "SAMPLE", "PREWHERE", "SETTINGS", "FORMAT", "AS",
+    }
+)  # fmt: skip
+
+
+@dataclass(frozen=True, slots=True)
+class TableRef:
+    parts: tuple[str, ...]  # ("schema", "table") or ("table",)
+    alias: str = ""
+
+    @property
+    def name(self) -> str:
+        return self.parts[-1]
+
+
+@dataclass(slots=True)
+class Context:
+    # "table": a table name is expected; "column": a column/keyword; "qualified": after "x."
+    kind: str
+    prefix: str  # the partial word before the cursor ("" when none)
+    qualifier: tuple[str, ...] = ()  # names before the last dot
+    tables: list[TableRef] = field(default_factory=list)
+
+    @property
+    def replace_len(self) -> int:
+        return len(self.prefix)
+
+
+def _unquote(s: str) -> str:
+    if len(s) >= 2 and s[0] in '"`[' and s[-1] in '"`]':
+        return s[1:-1]
+    return s
+
+
+def _statement_bounds(text: str, offset: int, toks: list[Token]) -> tuple[int, int]:
+    """Cheap bounds: nearest ';' tokens around the cursor (blank-line splitting is ignored)."""
+    start, end = 0, len(text)
+    for t in toks:
+        if t.kind == SEMI:
+            if t.end <= offset:
+                start = t.end
+            elif t.start >= offset:
+                end = t.start
+                break
+    return start, end
+
+
+def _significant(toks: list[Token], lo: int, hi: int) -> list[Token]:
+    skip = {WS, LINE_COMMENT, BLOCK_COMMENT}
+    return [t for t in toks if t.start >= lo and t.end <= hi and t.kind not in skip]
+
+
+def _table_refs(text: str, toks: list[Token]) -> list[TableRef]:
+    refs: list[TableRef] = []
+    i, n = 0, len(toks)
+    while i < n:
+        t = toks[i]
+        if t.kind == WORD and text[t.start : t.end].upper() in {"FROM", "JOIN", "UPDATE", "INTO"}:
+            i += 1
+            while i < n:
+                ref, i = _read_ref(text, toks, i)
+                if ref is None:
+                    break
+                refs.append(ref)
+                if i < n and text[toks[i].start : toks[i].end] == ",":
+                    i += 1
+                    continue
+                break
+        else:
+            i += 1
+    return refs
+
+
+def _read_ref(text: str, toks: list[Token], i: int) -> tuple[TableRef | None, int]:
+    n = len(toks)
+    parts: list[str] = []
+    while i < n and toks[i].kind in (WORD, QIDENT):
+        parts.append(_unquote(text[toks[i].start : toks[i].end]))
+        if i + 1 < n and text[toks[i + 1].start : toks[i + 1].end] == "." and i + 2 < n:
+            i += 2
+        else:
+            i += 1
+            break
+    if not parts:
+        return None, i
+    alias = ""
+    if i < n and toks[i].kind == WORD and text[toks[i].start : toks[i].end].upper() == "AS":
+        i += 1
+    if i < n and toks[i].kind in (WORD, QIDENT):
+        word = text[toks[i].start : toks[i].end]
+        if toks[i].kind == QIDENT or word.upper() not in NOT_ALIAS:
+            alias = _unquote(word)
+            i += 1
+    return TableRef(tuple(parts), alias), i
+
+
+def analyze(text: str, offset: int, dialect: str = "generic") -> Context | None:
+    """Context at `offset`, or None where completion makes no sense (strings, comments)."""
+    rules: Rules = RULES.get(dialect, RULES["generic"])
+    toks = tokenize(text, rules)
+    for t in toks:
+        if t.kind not in (STRING, LINE_COMMENT, BLOCK_COMMENT) or not t.start < offset <= t.end:
+            continue
+        closed = {
+            STRING: text[t.start : t.end].endswith("'") and t.end - t.start >= 2,
+            BLOCK_COMMENT: text[t.start : t.end].endswith("*/") and t.end - t.start >= 4,
+            LINE_COMMENT: False,  # a line comment runs to the newline, cursor at its end is inside
+        }[t.kind]
+        if offset < t.end or not closed:
+            return None
+    lo, hi = _statement_bounds(text, offset, toks)
+    stmt = _significant(toks, lo, hi)
+
+    # partial word under the cursor
+    p = offset
+    while p > 0 and (text[p - 1].isalnum() or text[p - 1] in "_$"):
+        p -= 1
+    prefix = text[p:offset]
+
+    # qualifier: name(.name)* followed by a dot, directly before the prefix
+    qual: list[str] = []
+    q = p
+    while q > 0 and text[q - 1] == ".":
+        q -= 1
+        end = q
+        if q > 0 and text[q - 1] in '"`]':
+            close = text[q - 1]
+            opener = {'"': '"', "`": "`", "]": "["}[close]
+            start = text.rfind(opener, 0, q - 1)
+            if start == -1:
+                break
+            qual.insert(0, text[start + 1 : q - 1])
+            q = start
+        else:
+            while q > 0 and (text[q - 1].isalnum() or text[q - 1] in "_$"):
+                q -= 1
+            if q == end:
+                break
+            qual.insert(0, text[q:end])
+    refs = _table_refs(text, stmt)
+    if qual:
+        return Context("qualified", prefix, tuple(qual), refs)
+
+    # nearest clause keyword before the word being typed (ignoring closed sub-selects)
+    kind = "column"
+    depth = 0
+    for t in reversed([t for t in stmt if t.end <= p]):
+        if t.kind == RPAREN:
+            depth += 1
+        elif t.kind == LPAREN:
+            if depth == 0:
+                continue
+            depth -= 1
+        elif t.kind == WORD and depth == 0:
+            word = text[t.start : t.end].upper()
+            if word in CLAUSE_KEYWORDS:
+                kind = "table" if word in TABLE_KEYWORDS else "column"
+                break
+    return Context(kind, prefix, (), refs)

sqlide/sql/dialects.py

@@ -0,0 +1,93 @@
+"""Per-dialect lexing and block rules. Dialect ids match DriverDef.dialect."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class BlockRules:
+    """Procedural blocks (BEGIN..END). Only active inside DECLARE/BEGIN/CREATE ROUTINE."""
+
+    openers: frozenset[str] = frozenset()  # statement-level words that open an END-closed block
+    inline_openers: frozenset[str] = frozenset()  # same, but valid anywhere (FOR..LOOP)
+    routines: frozenset[str] = frozenset()  # CREATE <kind> that enters block context
+    expect_begin_for: frozenset[str] = frozenset()  # ';' does not end these until their BEGIN
+    slash_only_for: frozenset[str] = frozenset()  # only '/' ends these (oracle packages)
+    declare_starts_block: bool = False
+    top_begin_block: bool = False  # statement-initial BEGIN is a block, not a transaction
+    tx_words: frozenset[str] = frozenset()  # BEGIN <word> is a transaction start
+    # CREATE <kind> whose body runs to the end of the batch (GO) unless it is a BEGIN..END block
+    batch_scoped: frozenset[str] = frozenset()
+
+
+@dataclass(frozen=True, slots=True)
+class Rules:
+    backslash_escapes: bool = False
+    dollar_quotes: bool = False
+    nested_comments: bool = False
+    backtick: bool = False
+    brackets: bool = False  # [ident]
+    hash_comment: bool = False
+    q_quote: bool = False  # oracle q'[...]'
+    e_strings: bool = False  # postgres E'..\n..'
+    slash_lines: bool = False  # '/' alone on a line ends a statement
+    delimiter_command: bool = False  # mysql client 'DELIMITER x' lines
+    go_batches: bool = False  # 'GO' alone on a line ends a batch
+    block: BlockRules | None = None
+
+
+_F = frozenset
+
+RULES: dict[str, Rules] = {
+    "generic": Rules(dollar_quotes=True, e_strings=True),
+    "postgres": Rules(dollar_quotes=True, nested_comments=True, e_strings=True),
+    "clickhouse": Rules(backslash_escapes=True, backtick=True, hash_comment=True),
+    "mysql": Rules(
+        backslash_escapes=True,
+        backtick=True,
+        hash_comment=True,
+        delimiter_command=True,
+        block=BlockRules(
+            openers=_F({"IF", "WHILE", "REPEAT"}),
+            inline_openers=_F({"LOOP"}),
+            routines=_F({"PROCEDURE", "FUNCTION", "TRIGGER", "EVENT"}),
+            tx_words=_F({"WORK"}),
+        ),
+    ),
+    "oracle": Rules(
+        q_quote=True,
+        slash_lines=True,
+        block=BlockRules(
+            openers=_F({"IF"}),
+            inline_openers=_F({"LOOP"}),
+            routines=_F({"PROCEDURE", "FUNCTION", "TRIGGER", "PACKAGE", "TYPE"}),
+            expect_begin_for=_F({"PROCEDURE", "FUNCTION", "TRIGGER"}),
+            slash_only_for=_F({"PACKAGE", "TYPE"}),  # TYPE only when followed by BODY
+            declare_starts_block=True,
+            top_begin_block=True,
+        ),
+    ),
+    "mssql": Rules(
+        brackets=True,
+        go_batches=True,
+        block=BlockRules(
+            routines=_F({"PROCEDURE", "PROC", "FUNCTION", "TRIGGER"}),
+            top_begin_block=True,
+            tx_words=_F({"TRAN", "TRANSACTION", "DISTRIBUTED"}),
+            batch_scoped=_F({"PROCEDURE", "PROC", "FUNCTION", "TRIGGER"}),
+        ),
+    ),
+    "sqlite": Rules(
+        backtick=True,
+        brackets=True,
+        block=BlockRules(
+            routines=_F({"TRIGGER"}),
+            tx_words=_F({"TRANSACTION", "DEFERRED", "IMMEDIATE", "EXCLUSIVE"}),
+        ),
+    ),
+}
+
+
+def rules_for(dialect: str) -> Rules:
+    return RULES.get(dialect, RULES["generic"])

sqlide/sql/format.py

@@ -0,0 +1,50 @@
+"""SQL pretty-printing (via sqlglot) and line-comment toggling."""
+
+from __future__ import annotations
+
+import sqlglot
+from sqlglot.errors import SqlglotError
+
+from sqlide.sql.dialects import RULES
+from sqlide.sql.splitter import split
+
+_SQLGLOT = {"mssql": "tsql", "generic": None, "h2": None}
+
+
+class FormatError(Exception):
+    pass
+
+
+def format_sql(sql: str, dialect: str = "generic") -> str:
+    """Pretty-print one or more statements; the text is left alone if it cannot be parsed."""
+    name = _SQLGLOT.get(dialect, dialect)
+    parts = [s.text(sql) for s in split(sql, dialect if dialect in RULES else "generic")]
+    try:
+        out = [
+            sqlglot.transpile(part, read=name, write=name, pretty=True)[0]
+            for part in parts
+            if part.strip()
+        ]
+    except SqlglotError as e:
+        raise FormatError(str(e).splitlines()[0]) from e
+    return ";\n\n".join(out)
+
+
+def toggle_line_comments(lines: list[str]) -> list[str]:
+    """Comment all lines, or uncomment them when every non-blank line is already commented."""
+    body = [ln for ln in lines if ln.strip()]
+    if not body:
+        return lines
+    if all(ln.lstrip().startswith("--") for ln in body):
+        out = []
+        for ln in lines:
+            stripped = ln.lstrip()
+            if stripped.startswith("--"):
+                indent = ln[: len(ln) - len(stripped)]
+                rest = stripped[2:]
+                out.append(indent + (rest[1:] if rest.startswith(" ") else rest))
+            else:
+                out.append(ln)
+        return out
+    indent = min(len(ln) - len(ln.lstrip()) for ln in body)
+    return [ln if not ln.strip() else ln[:indent] + "-- " + ln[indent:] for ln in lines]

sqlide/sql/keywords.py

@@ -0,0 +1,143 @@
+"""Keyword and function names offered by autocomplete, per dialect."""
+
+from __future__ import annotations
+
+COMMON_KEYWORDS = [
+    "SELECT",
+    "DISTINCT",
+    "FROM",
+    "WHERE",
+    "GROUP",
+    "BY",
+    "HAVING",
+    "ORDER",
+    "LIMIT",
+    "OFFSET",
+    "UNION",
+    "ALL",
+    "INTERSECT",
+    "EXCEPT",
+    "JOIN",
+    "INNER",
+    "LEFT",
+    "RIGHT",
+    "FULL",
+    "OUTER",
+    "CROSS",
+    "ON",
+    "USING",
+    "AS",
+    "AND",
+    "OR",
+    "NOT",
+    "IN",
+    "IS",
+    "NULL",
+    "LIKE",
+    "BETWEEN",
+    "EXISTS",
+    "CASE",
+    "WHEN",
+    "THEN",
+    "ELSE",
+    "END",
+    "ASC",
+    "DESC",
+    "NULLS",
+    "FIRST",
+    "LAST",
+    "INSERT",
+    "INTO",
+    "VALUES",
+    "UPDATE",
+    "SET",
+    "DELETE",
+    "MERGE",
+    "RETURNING",
+    "CREATE",
+    "ALTER",
+    "DROP",
+    "TRUNCATE",
+    "TABLE",
+    "VIEW",
+    "INDEX",
+    "SCHEMA",
+    "SEQUENCE",
+    "DATABASE",
+    "ADD",
+    "COLUMN",
+    "CONSTRAINT",
+    "PRIMARY",
+    "KEY",
+    "FOREIGN",
+    "REFERENCES",
+    "UNIQUE",
+    "CHECK",
+    "DEFAULT",
+    "BEGIN",
+    "COMMIT",
+    "ROLLBACK",
+    "SAVEPOINT",
+    "WITH",
+    "RECURSIVE",
+    "EXPLAIN",
+    "TRUE",
+    "FALSE",
+    "CAST",
+    "OVER",
+    "PARTITION",
+    "ROWS",
+    "RANGE",
+]
+
+COMMON_FUNCTIONS = [
+    "COUNT",
+    "SUM",
+    "AVG",
+    "MIN",
+    "MAX",
+    "COALESCE",
+    "NULLIF",
+    "ABS",
+    "ROUND",
+    "FLOOR",
+    "CEIL",
+    "LOWER",
+    "UPPER",
+    "LENGTH",
+    "TRIM",
+    "SUBSTRING",
+    "REPLACE",
+    "CONCAT",
+    "ROW_NUMBER",
+    "RANK",
+    "DENSE_RANK",
+    "LAG",
+    "LEAD",
+]
+
+_DIALECT_KEYWORDS = {
+    "postgres": "ILIKE RETURNING LATERAL MATERIALIZED VACUUM ANALYZE COPY SERIAL JSONB ARRAY",
+    "mysql": "SHOW DESCRIBE USE ENGINE AUTO_INCREMENT REPLACE IGNORE STRAIGHT_JOIN",
+    "clickhouse": "FINAL SAMPLE PREWHERE ENGINE SETTINGS FORMAT ARRAY ATTACH DETACH OPTIMIZE",
+    "oracle": "ROWNUM DUAL CONNECT PRIOR MINUS FETCH NEXT ONLY SYSDATE",
+    "mssql": "TOP GO NOLOCK IDENTITY EXEC PROCEDURE DECLARE",
+    "sqlite": "PRAGMA AUTOINCREMENT VACUUM GLOB",
+}
+
+_DIALECT_FUNCTIONS = {
+    "postgres": "NOW GENERATE_SERIES STRING_AGG ARRAY_AGG TO_CHAR DATE_TRUNC JSONB_BUILD_OBJECT",
+    "mysql": "NOW IFNULL GROUP_CONCAT DATE_FORMAT CURDATE",
+    "clickhouse": "toDate toDateTime toString arrayJoin uniq groupArray now today",
+    "oracle": "NVL TO_CHAR TO_DATE SYSDATE DECODE LISTAGG",
+    "mssql": "GETDATE ISNULL DATEADD DATEDIFF STRING_AGG",
+    "sqlite": "IFNULL DATE DATETIME STRFTIME GROUP_CONCAT",
+}
+
+
+def keywords(dialect: str) -> list[str]:
+    return sorted({*COMMON_KEYWORDS, *_DIALECT_KEYWORDS.get(dialect, "").split()})
+
+
+def functions(dialect: str) -> list[str]:
+    return sorted({*COMMON_FUNCTIONS, *_DIALECT_FUNCTIONS.get(dialect, "").split()})

sqlide/sql/lexer.py

@@ -0,0 +1,148 @@
+"""Tolerant SQL tokenizer. Never raises: unterminated strings/comments run to EOF."""
+
+from __future__ import annotations
+
+import re
+from typing import NamedTuple
+
+from sqlide.sql.dialects import Rules
+
+WS, LINE_COMMENT, BLOCK_COMMENT, STRING, QIDENT, WORD, PUNCT, SEMI, LPAREN, RPAREN = range(10)
+
+_WS = re.compile(r"\s+")
+_WORD = re.compile(r"[\w$#@]+")
+_DOLLAR = re.compile(r"\$(?:[^\W\d]\w*)?\$")
+_Q_CLOSE = {"[": "]", "{": "}", "<": ">", "(": ")"}
+
+
+class Token(NamedTuple):
+    kind: int
+    start: int
+    end: int
+
+
+def _scan_quoted(text: str, i: int, quote: str, backslash: bool) -> int:
+    """`i` is on the opening quote; doubled quote escapes it. Returns end (exclusive)."""
+    n, j = len(text), i + 1
+    if backslash:
+        while j < n:
+            ch = text[j]
+            if ch == "\\":
+                j += 2
+            elif ch == quote:
+                if text[j + 1 : j + 2] == quote:
+                    j += 2
+                else:
+                    return j + 1
+            else:
+                j += 1
+        return n
+    while True:
+        k = text.find(quote, j)
+        if k == -1:
+            return n
+        if text[k + 1 : k + 2] == quote:
+            j = k + 2
+            continue
+        return k + 1
+
+
+def tokenize(text: str, rules: Rules) -> list[Token]:
+    out: list[Token] = []
+    n, i = len(text), 0
+    add = out.append
+    while i < n:
+        c = text[i]
+        two = text[i : i + 2]
+        if c.isspace():
+            j = _WS.match(text, i).end()  # type: ignore[union-attr]
+            add(Token(WS, i, j))
+        elif two == "--" or (c == "#" and rules.hash_comment):
+            j = text.find("\n", i)
+            j = n if j == -1 else j
+            add(Token(LINE_COMMENT, i, j))
+        elif two == "/*":
+            j = _scan_block_comment(text, i, rules.nested_comments)
+            add(Token(BLOCK_COMMENT, i, j))
+        elif c == "'":
+            j = _scan_quoted(text, i, "'", rules.backslash_escapes)
+            add(Token(STRING, i, j))
+        elif c in "eE" and rules.e_strings and text[i + 1 : i + 2] == "'":
+            j = _scan_quoted(text, i + 1, "'", True)
+            add(Token(STRING, i, j))
+        elif c in "qQ" and rules.q_quote and text[i + 1 : i + 2] == "'" and _q_ok(text, i + 2):
+            j = _scan_q(text, i)
+            add(Token(STRING, i, j))
+        elif c == '"':
+            j = _scan_quoted(text, i, '"', rules.backslash_escapes)
+            add(Token(QIDENT, i, j))
+        elif c == "`" and rules.backtick:
+            add(Token(QIDENT, i, _scan_quoted(text, i, "`", False)))
+        elif c == "[" and rules.brackets:
+            add(Token(QIDENT, i, _scan_bracket(text, i)))
+        elif c == "$" and rules.dollar_quotes and (m := _DOLLAR.match(text, i)):
+            tag = m.group(0)
+            k = text.find(tag, m.end())
+            add(Token(STRING, i, n if k == -1 else k + len(tag)))
+            i = out[-1].end
+            continue
+        elif c == ";":
+            add(Token(SEMI, i, i + 1))
+            i += 1
+            continue
+        elif c == "(":
+            add(Token(LPAREN, i, i + 1))
+            i += 1
+            continue
+        elif c == ")":
+            add(Token(RPAREN, i, i + 1))
+            i += 1
+            continue
+        elif m := _WORD.match(text, i):
+            add(Token(WORD, i, m.end()))
+        else:
+            add(Token(PUNCT, i, i + 1))
+            i += 1
+            continue
+        i = out[-1].end
+    return out
+
+
+def _scan_block_comment(text: str, i: int, nested: bool) -> int:
+    n, depth, j = len(text), 1, i + 2
+    while j < n:
+        if text.startswith("*/", j):
+            depth -= 1
+            j += 2
+            if depth == 0:
+                return j
+        elif nested and text.startswith("/*", j):
+            depth += 1
+            j += 2
+        else:
+            j += 1
+    return n
+
+
+def _scan_bracket(text: str, i: int) -> int:
+    n, j = len(text), i + 1
+    while j < n:
+        if text[j] == "]":
+            if text[j + 1 : j + 2] == "]":
+                j += 2
+                continue
+            return j + 1
+        j += 1
+    return n
+
+
+def _q_ok(text: str, i: int) -> bool:
+    return i < len(text) and not text[i].isspace()
+
+
+def _scan_q(text: str, i: int) -> int:
+    """q'[ ... ]' style quoting; `i` is on the q."""
+    d = text[i + 2]
+    closing = _Q_CLOSE.get(d, d) + "'"
+    k = text.find(closing, i + 3)
+    return len(text) if k == -1 else k + 2

sqlide/sql/snippets.py

@@ -0,0 +1,44 @@
+"""Small SQL generators for the UI: identifier quoting and "select from table" statements."""
+
+from __future__ import annotations
+
+import re
+
+_SIMPLE = re.compile(r"^[A-Za-z_][A-Za-z0-9_$]*$")
+
+# How an unquoted identifier is case-folded, per dialect. None: case is preserved/ignored.
+_FOLD = {"postgres": str.lower, "oracle": str.upper, "generic": str.upper}
+_QUOTES = {"mysql": ("`", "`"), "clickhouse": ("`", "`"), "mssql": ("[", "]")}
+
+
+def quote_ident(name: str, dialect: str) -> str:
+    """Quote `name` only when leaving it bare would change its meaning."""
+    fold = _FOLD.get(dialect)
+    if _SIMPLE.match(name) and (fold is None or fold(name) == name):
+        return name
+    left, right = _QUOTES.get(dialect, ('"', '"'))
+    return left + name.replace(right, right * 2) + right
+
+
+def qualified_name(parts: list[str], dialect: str) -> str:
+    return ".".join(quote_ident(p, dialect) for p in parts if p)
+
+
+def select_all(table: str, dialect: str, limit: int = 100) -> str:
+    """`table` is already qualified/quoted."""
+    if dialect == "mssql":
+        return f"SELECT TOP {limit} * FROM {table}"
+    if dialect == "oracle":
+        return f"SELECT * FROM {table} FETCH FIRST {limit} ROWS ONLY"
+    return f"SELECT * FROM {table} LIMIT {limit}"
+
+
+_LEADING_NOISE = re.compile(r"^(?:\s+|--[^\n]*(?:\n|$)|/\*.*?\*/)*", re.S)
+_DDL_WORDS = frozenset({"CREATE", "ALTER", "DROP", "TRUNCATE", "RENAME", "COMMENT"})
+
+
+def is_ddl(sql: str) -> bool:
+    """True when the statement changes the schema (so cached metadata is stale)."""
+    rest = _LEADING_NOISE.sub("", sql, count=1)
+    word = re.match(r"[A-Za-z]+", rest)
+    return bool(word) and word.group().upper() in _DDL_WORDS  # type: ignore[union-attr]