vf-hive-dbparse 0.6.0__py3-none-any.whl

hivedbparse/emit.py

@@ -0,0 +1,304 @@
+"""Render `Table`/`PlsqlObject` models into OKF `dbobject` markdown cards.
+
+One card per object (design spec Sec. 4): a `table_card` (columns + PK/FK/
+index/sequence/trigger sections) and a `plsql_card` (signature + full body).
+Everything sourced from `COMMENT ON ...`/DDL text (comments, types, bodies) is
+rendered **verbatim** -- this module never fabricates or normalizes it. The
+two correctness hazards called out in the design are handled explicitly:
+
+- A comment containing `|` would otherwise break a markdown table row, so
+  `|` is escaped to `\\|` when a comment is placed in the Columns table.
+- Frontmatter is emitted with `yaml.safe_dump` (the same library hive-serve's
+  loader uses to parse it back with `yaml.safe_load`), so a comment containing
+  a `:` or other YAML-special character is always quoted/escaped correctly
+  instead of hand-rolled and risking invalid YAML.
+"""
+
+from __future__ import annotations
+
+import yaml
+
+from hivedbparse.model import Column, PlsqlObject, Table
+
+# Canonical dialect order for `platform:` frontmatter and derived source paths.
+_DIALECT_ORDER = ("oracle", "db2")
+_DIALECT_DIR = {"oracle": "Oracle", "db2": "DB2"}
+
+_MISSING_TYPE = "n/a"  # column absent from that dialect
+
+
+DEFAULT_PRODUCT = "db"
+
+
+def card_id(obj: Table | PlsqlObject, product: str = DEFAULT_PRODUCT) -> str:
+    """`<product>/db/tables/<NAME>` for a `Table`, `<product>/db/plsql/<NAME>` otherwise.
+
+    The product names the corpus this schema belongs to. It is a run-level constant, so it
+    is passed rather than inferred: a schema does not know which product it implements.
+    """
+    if isinstance(obj, Table):
+        return f"{product}/db/tables/{obj.name}"
+    if isinstance(obj, PlsqlObject):
+        return f"{product}/db/plsql/{obj.name}"
+    raise TypeError(f"hivedbparse: card_id: unsupported object type {type(obj)!r}")
+
+
+def _platform(dialects: set[str]) -> list[str]:
+    return [d for d in _DIALECT_ORDER if d in dialects]
+
+
+def _frontmatter(fields: dict) -> str:
+    dumped = yaml.safe_dump(fields, sort_keys=False, default_flow_style=False, allow_unicode=True)
+    return f"---\n{dumped}---\n"
+
+
+def _esc_cell(text: str) -> str:
+    """Escape `|` so a comment can't be mistaken for a markdown table column break."""
+    return text.replace("|", "\\|")
+
+
+# ---------------------------------------------------------------------------
+# Table cards
+# ---------------------------------------------------------------------------
+
+
+def _table_title(t: Table) -> str:
+    return f"{t.name}: {t.comment}" if t.comment else t.name
+
+
+def _table_tags(t: Table) -> list[str]:
+    return ["table", t.module]
+
+
+def _table_sources(t: Table) -> list[str]:
+    """The real file(s) `t` was read from, when the runner set them; else a
+    synthesized `<module>.sql` path (correct for tables, since a module's
+    `.sql` file *is* named after the module -- see `_plsql_sources` for why
+    PL/SQL cards can't use the same synthesis)."""
+    if t.source_files:
+        return list(t.source_files)
+    return [
+        f"{_DIALECT_DIR[d]}/DBScripts/Product/{t.module}.sql"
+        for d in _DIALECT_ORDER
+        if d in t.dialects
+    ]
+
+
+def _table_related(t: Table, product: str) -> list[str]:
+    related: list[str] = []
+    for _col, ref_table, _ref_col in t.fks:
+        rid = f"{product}/db/tables/{ref_table}"
+        if rid not in related:
+            related.append(rid)
+    return related
+
+
+def _table_frontmatter(t: Table, product: str) -> dict:
+    return {
+        "type": "dbobject",
+        "kind": "table",
+        "title": _table_title(t),
+        "description": t.comment,
+        "product": product,
+        "module": t.module,
+        "platform": _platform(t.dialects),
+        "tags": _table_tags(t),
+        "related": _table_related(t, product),
+        "sources": _table_sources(t),
+    }
+
+
+def _type_cell(type_text: str | None) -> str:
+    return type_text if type_text else _MISSING_TYPE
+
+
+def _column_row(c: Column, pk: list[str]) -> str:
+    null = "NOT NULL" if c.not_null else ""
+    key = "PK" if c.name in pk else ""
+    return (
+        f"| {c.name} | {_type_cell(c.type_oracle)} | {_type_cell(c.type_db2)} | "
+        f"{null} | {key} | {_esc_cell(c.comment)} |"
+    )
+
+
+def _columns_table(t: Table) -> str:
+    lines = [
+        "| Column | Oracle type | DB2 type | Null | Key | Description |",
+        "|---|---|---|---|---|---|",
+    ]
+    lines.extend(_column_row(c, t.pk) for c in t.columns)
+    return "\n".join(lines)
+
+
+def _pk_section(t: Table) -> str:
+    return ", ".join(t.pk) if t.pk else "none"
+
+
+def _fks_section(t: Table, product: str) -> str:
+    if not t.fks:
+        return "none"
+    return "\n".join(
+        f"{col} → {ref_table}({ref_col})   → {product}/db/tables/{ref_table}"
+        for col, ref_table, ref_col in t.fks
+    )
+
+
+def _indexes_section(t: Table) -> str:
+    if not t.indexes:
+        return "none"
+    lines = []
+    for name, cols, unique in t.indexes:
+        suffix = " [UNIQUE]" if unique else ""
+        lines.append(f"{name} ({', '.join(cols)}){suffix}")
+    return "\n".join(lines)
+
+
+def _sequences_section(t: Table) -> str:
+    return "\n".join(t.sequences) if t.sequences else "none"
+
+
+def _triggers_section(t: Table, product: str) -> str:
+    if not t.triggers:
+        return "none"
+    return "\n".join(f"{name} → {product}/db/plsql/{name}" for name in t.triggers)
+
+
+def table_card(t: Table, product: str = DEFAULT_PRODUCT) -> str:
+    """Render `t` as an OKF `dbobject`/`table` markdown card (design Sec. 4.1)."""
+    body_lines = [f"# {t.name}  (table · module {t.module})", ""]
+    if t.comment:
+        body_lines.append(t.comment)
+        body_lines.append("")
+    body_lines += [
+        "## Columns",
+        _columns_table(t),
+        "",
+        "## Primary key",
+        _pk_section(t),
+        "",
+        "## Foreign keys",
+        _fks_section(t, product),
+        "",
+        "## Indexes",
+        _indexes_section(t),
+        "",
+        "## Sequences",
+        _sequences_section(t),
+        "",
+        "## Triggers",
+        _triggers_section(t, product),
+        "",
+    ]
+    return _frontmatter(_table_frontmatter(t, product)) + "\n" + "\n".join(body_lines)
+
+
+# ---------------------------------------------------------------------------
+# PL/SQL cards
+# ---------------------------------------------------------------------------
+
+
+def _plsql_header_text(o: PlsqlObject) -> str:
+    """The unit's header comment verbatim, or `""` when it has none.
+
+    Never falls back to the raw signature/CREATE text: `title`/`description`
+    are `find_db_objects` search fields, so the DDL statement text would be
+    noise there (the full signature and body already live in the card body).
+    """
+    return o.comment
+
+
+def _plsql_title(o: PlsqlObject) -> str:
+    """`NAME: <comment>` when a header comment exists, else `NAME (<kind>)`.
+    Never embeds the raw signature/DDL text (search-field hygiene)."""
+    if o.comment:
+        return f"{o.name}: {o.comment}"
+    return f"{o.name} ({o.kind})"
+
+
+def _plsql_tags(o: PlsqlObject) -> list[str]:
+    return ["plsql", o.kind, o.module]
+
+
+def _plsql_sources(o: PlsqlObject) -> list[str]:
+    """The real file(s) `o` was read from, when the runner set them. A
+    PL/SQL unit's real file lives at `PLSQL_Objects/<file>.sql`, named per
+    *file* (not necessarily per object) -- unlike a table's module file, this
+    can't be reliably synthesized from `o.name`/`o.module` alone, so the
+    fallback below is a best-effort guess only used when `source_files` is
+    unset (e.g. in unit tests that build a `PlsqlObject` directly)."""
+    if o.source_files:
+        return list(o.source_files)
+    return [
+        f"{_DIALECT_DIR[d]}/DBScripts/Product/PLSQL_Objects/{o.name}.sql"
+        for d in _DIALECT_ORDER
+        if d in o.dialects
+    ]
+
+
+def _plsql_frontmatter(o: PlsqlObject, product: str) -> dict:
+    return {
+        "type": "dbobject",
+        "kind": o.kind,
+        "title": _plsql_title(o),
+        "description": _plsql_header_text(o),
+        "product": product,
+        "module": o.module,
+        "platform": _platform(o.dialects),
+        "tags": _plsql_tags(o),
+        "sources": _plsql_sources(o),
+    }
+
+
+def plsql_card(o: PlsqlObject, product: str = DEFAULT_PRODUCT) -> str:
+    """Render `o` as an OKF `dbobject`/`<kind>` markdown card (design Sec. 4.2)."""
+    body_lines = [
+        f"# {o.name}  ({o.kind} · module {o.module})",
+        "",
+        "## Signature / spec",
+        "```sql",
+        o.signature,
+        "```",
+        "",
+        "## Source (Oracle)",
+        "```sql",
+        o.body_oracle,
+        "```",
+        "",
+        "## Source (DB2)",
+    ]
+    if o.body_db2:
+        body_lines += ["```sql", o.body_db2, "```"]
+    else:
+        body_lines.append("Identical to Oracle.")
+    body_lines.append("")
+    return _frontmatter(_plsql_frontmatter(o, product)) + "\n" + "\n".join(body_lines)
+
+
+# ---------------------------------------------------------------------------
+# Manifest
+# ---------------------------------------------------------------------------
+
+
+def manifest_line(obj: Table | PlsqlObject, product: str = DEFAULT_PRODUCT) -> dict:
+    """`{id, kind, module, product, title, description, tags}` for the manifest index."""
+    if isinstance(obj, Table):
+        return {
+            "id": card_id(obj, product),
+            "kind": "table",
+            "module": obj.module,
+            "product": product,
+            "title": _table_title(obj),
+            "description": obj.comment,
+            "tags": _table_tags(obj),
+        }
+    if isinstance(obj, PlsqlObject):
+        return {
+            "id": card_id(obj, product),
+            "kind": obj.kind,
+            "module": obj.module,
+            "product": product,
+            "title": _plsql_title(obj),
+            "description": _plsql_header_text(obj),
+            "tags": _plsql_tags(obj),
+        }
+    raise TypeError(f"hivedbparse: manifest_line: unsupported object type {type(obj)!r}")

hivedbparse/model.py

@@ -0,0 +1,43 @@
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Column:
+    name: str
+    type_oracle: str | None = None
+    type_db2: str | None = None
+    not_null: bool = False
+    comment: str = ""  # from COMMENT ON COLUMN, verbatim
+
+
+@dataclass
+class Table:
+    name: str
+    module: str
+    comment: str = ""  # from COMMENT ON TABLE, verbatim
+    columns: list[Column] = field(default_factory=list)
+    pk: list[str] = field(default_factory=list)
+    fks: list[tuple[str, str, str]] = field(default_factory=list)  # (col, ref_table, ref_col)
+    indexes: list[tuple[str, list[str], bool]] = field(
+        default_factory=list
+    )  # (name, cols, unique)
+    sequences: list[str] = field(default_factory=list)
+    triggers: list[str] = field(default_factory=list)
+    dialects: set[str] = field(default_factory=set)  # {"oracle","db2"}
+    # Repo-relative path(s) this object was actually read from (set by the
+    # runner, which knows the real file -- see hivedbparse.run). Empty by
+    # default so `emit` can fall back to its module-synthesized path.
+    source_files: list[str] = field(default_factory=list)
+
+
+@dataclass
+class PlsqlObject:
+    name: str
+    module: str
+    kind: str  # package|procedure|function|view|trigger
+    signature: str = ""
+    body_oracle: str = ""  # full source, verbatim
+    body_db2: str = ""
+    comment: str = ""
+    dialects: set[str] = field(default_factory=set)
+    source_files: list[str] = field(default_factory=list)

hivedbparse/parse_aux.py

@@ -0,0 +1,335 @@
+"""Attach comments, FKs, indexes and sequences to `Table` objects built by `parse_tables`.
+
+Uses sqlglot's AST exclusively (tokenizer + parser) -- never regex -- to walk
+`COMMENT ON TABLE/COLUMN`, `ALTER TABLE ... ADD ... FOREIGN KEY`,
+`CREATE [UNIQUE] INDEX` and `CREATE SEQUENCE` statements and mutate the
+already-parsed `Table`/`Column` objects in place. Statements that reference a
+table not present in `tables` (and statements sqlglot cannot parse at all) are
+skipped and logged -- never allowed to crash the run.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+
+import sqlglot
+from sqlglot import exp
+
+from hivedbparse.model import Table
+from hivedbparse.parse_tables import (
+    _extract_create_table_fragment,
+    _split_statements,
+    _sqlglot_dialect,
+    _strip_constraint_state,
+    _strip_using_index_clause,
+)
+
+# Hard failures -- DDL we should have understood but couldn't. The runner
+# captures this logger into the verification gate: an aux statement that
+# reaches `_apply_node` carrying attachable content and fails to parse is a
+# SILENT DROP (a lost index/sequence/FK/comment), so it must fail the run.
+logger = logging.getLogger(__name__)
+
+# Soft, non-fatal misses -- the statement parsed fine, but its target isn't in
+# the carded corpus (a comment/FK/index on a table we don't walk) or no owning
+# table could be resolved (an orphan sequence). These are a consequence of
+# corpus SCOPE, not a parser gap, so they're reported (`unattached.log`) rather
+# than gated. Deliberately a SIBLING logger of `logger`, not a child: a handler
+# on `hivedbparse.parse_aux` would otherwise capture these too via propagation.
+unattached_logger = logging.getLogger("hivedbparse.aux_unattached")
+
+# The statement kinds `_apply_node` actually attaches. Narrow ON PURPOSE: every
+# statement passing this filter carries content we attach, so a parse failure on
+# one is a real drop the gate can fail honestly. Everything else (CREATE TABLE,
+# PL/SQL bodies, INSERT seed data, `ALTER TABLE ... MOVE TABLESPACE`, ...) is
+# skipped without a parse attempt -- crucial over the Seed catalogs, whose
+# hundreds of thousands of PL/SQL-body fragments would otherwise each be parsed.
+_AUX_HEAD = re.compile(
+    r"\s*(?:--[^\n]*\n\s*|/\*.*?\*/\s*)*"
+    r"(COMMENT\b|ALTER\s+TABLE\b|CREATE\s+(?:UNIQUE\s+|BITMAP\s+)?INDEX\b)",
+    re.IGNORECASE | re.DOTALL,
+)
+
+# Every `CREATE [OR REPLACE] SEQUENCE <name>` in the text, with its name.
+# Sequences are attached by name (owner lookup), never parsed or split into
+# statements: Oracle `CREATE SEQUENCE` parses fine, but DB2 `CREATE OR REPLACE
+# SEQUENCE x ... NO ORDER!` degrades to `Command`, and its files use `!`
+# terminators that must NOT be split on (see `_split_statements`). Scanning the
+# whole text with `findall` sidesteps both -- a sequence carries no columns/keys
+# we model, so the name is all `_sequence_owner` needs.
+_SEQUENCE_DECL = re.compile(
+    r"\bCREATE\s+(?:OR\s+REPLACE\s+)?SEQUENCE\s+\"?([A-Za-z0-9_$]+)\"?", re.IGNORECASE
+)
+# Only an ADD of a foreign key carries columns + references we attach. DB2's
+# `ALTER TABLE t ALTER FOREIGN KEY fk NOT ENFORCED` merely toggles an existing
+# FK's enforcement -- no definition to attach, so it must NOT reach the gate.
+_ADD_FOREIGN_KEY = re.compile(r"\bADD\b[^;]*?\bFOREIGN\s+KEY\b", re.IGNORECASE | re.DOTALL)
+
+# sqlglot's Oracle grammar rejects a schema-qualified INDEX NAME
+# (`CREATE INDEX session.idx1 ON session.t (...)` degrades to Command), though
+# an unqualified index name on a schema-qualified TABLE parses fine. The index's
+# own schema is cosmetic here (we attach by table, and don't model index schema),
+# so drop just the `<schema>.` before the index name, leaving the ON-table ref.
+_INDEX_NAME_SCHEMA = re.compile(
+    r"(\bINDEX\s+)(?:\"?[\w$]+\"?\s*\.\s*)(\"?[\w$]+\"?\s+ON\b)", re.IGNORECASE
+)
+
+
+def _is_aux_statement(stmt_text: str) -> bool:
+    """True only for statements `_apply_node` can attach (see `_AUX_HEAD`).
+
+    An `ALTER TABLE` only qualifies when it adds a FOREIGN KEY -- every other
+    alter (`MOVE TABLESPACE`, `ADD PARTITION`, `ENABLE CONSTRAINT`, ...) carries
+    nothing this module models, so admitting it would make the gate fail on
+    statements that were never a drop.
+    """
+    m = _AUX_HEAD.match(stmt_text)
+    if m is None:
+        return False
+    if m.group(1).upper().startswith("ALTER"):
+        return _ADD_FOREIGN_KEY.search(stmt_text) is not None
+    return True
+
+
+def _parse_aux_statement(stmt_text: str, sqlglot_dialect: str | None) -> exp.Expression | None:
+    """Parse one aux statement, trimming a physical-storage tail if needed.
+
+    Real Oracle DDL trails `CREATE INDEX x ON t (cols)` with storage clauses
+    (`TABLESPACE ... PCTFREE ... INITRANS ...`) that sqlglot can't model, so it
+    degrades the WHOLE statement to `exp.Command` -- and `_apply_node` then
+    skips it, silently losing the index. This retries against the bare
+    `CREATE ... (...)` fragment (the same token-level paren-slice trick
+    `parse_tables` uses for `CREATE TABLE`). Returns `None` when the statement
+    is genuinely unparseable.
+    """
+    # Same physical-noise cleaners `parse_tables` runs: a trailing constraint
+    # state (`... FOREIGN KEY (A) REFERENCES P (B) ENABLE NOVALIDATE;`) or a
+    # `USING INDEX TABLESPACE ...` clause degrades the whole ALTER/CREATE to an
+    # opaque `Command`; stripping them lets the FK/index parse cleanly.
+    stmt_text = _strip_using_index_clause(
+        _strip_constraint_state(stmt_text, sqlglot_dialect), sqlglot_dialect
+    )
+    stmt_text = _INDEX_NAME_SCHEMA.sub(r"\1\2", stmt_text)
+    try:
+        node = sqlglot.parse_one(stmt_text, read=sqlglot_dialect)
+    except Exception:  # noqa: BLE001 -- fall through to the fragment retry
+        node = None
+
+    if node is not None and not isinstance(node, exp.Command):
+        return node
+
+    fragment = _extract_create_table_fragment(stmt_text, sqlglot_dialect)
+    if fragment is not None:
+        try:
+            retry = sqlglot.parse_one(fragment, read=sqlglot_dialect)
+        except Exception:  # noqa: BLE001
+            retry = None
+        if retry is not None and not isinstance(retry, exp.Command):
+            return retry
+    return node
+
+# Suffixes/prefixes DDL authors commonly hang off a sequence name that derives
+# from its owning table's name (e.g. `ORDER_LINE_SEQ`, `SEQ_ORDER_LINE`).
+_SEQUENCE_AFFIXES = ("_SEQUENCE", "_SEQ", "SEQUENCE_", "SEQ_")
+
+
+def _strip_sequence_affixes(name: str) -> str:
+    stem = name.upper()
+    for affix in _SEQUENCE_AFFIXES:
+        if affix.endswith("_") and stem.startswith(affix):
+            stem = stem[len(affix) :]
+            break
+        if affix.startswith("_") and stem.endswith(affix):
+            stem = stem[: -len(affix)]
+            break
+    return stem.strip("_")
+
+
+def _sequence_owner(tables: dict[str, Table], seq_name: str) -> Table | None:
+    """Find the table that owns `seq_name` by a name-prefix heuristic.
+
+    Strips common sequence affixes (`_SEQ`, `SEQ_`, ...) from the sequence name,
+    then resolves the owner in strict precedence:
+
+    1. An **exact** table match (`table == stem`) is the unambiguous owner and
+       wins outright. This is the important part: a bare `longest match` let an
+       exact owner lose to any longer table that merely *starts* with the stem
+       (e.g. `ROUTE_SEQ` was grabbed by `ROUTE_PLAN_LEG_SET` instead of the
+       `ROUTE` table).
+    2. Otherwise, the longest table that is a prefix of the stem, or that the
+       stem is a prefix of -- a weak plural/abbreviation fallback.
+
+    Returns `None` (an orphan sequence) when no table matches.
+    """
+    stem = _strip_sequence_affixes(seq_name)
+    if not stem:
+        return None
+
+    best_table: Table | None = None
+    best_len = -1
+    for table_name, table in tables.items():
+        upper = table_name.upper()
+        if upper == stem:
+            return table  # exact match -> unambiguous owner, beats any prefix match
+        if (stem.startswith(upper + "_") or upper.startswith(stem)) and len(upper) > best_len:
+            best_table = table
+            best_len = len(upper)
+    return best_table
+
+
+def _comment_text(node: exp.Comment) -> str:
+    expression = node.expression
+    return expression.this if isinstance(expression, exp.Literal) else str(expression)
+
+
+def _apply_comment(tables: dict[str, Table], node: exp.Comment) -> None:
+    kind = (node.args.get("kind") or "").lower()
+    text = _comment_text(node)
+    target = node.this
+
+    if kind == "table":
+        table_name = target.name
+        table = tables.get(table_name)
+        if table is None:
+            unattached_logger.warning("hivedbparse: COMMENT ON TABLE references unknown table %s", table_name)
+            return
+        table.comment = text
+    elif kind == "column":
+        table_name = target.table
+        column_name = target.name
+        table = tables.get(table_name)
+        if table is None:
+            unattached_logger.warning("hivedbparse: COMMENT ON COLUMN references unknown table %s", table_name)
+            return
+        column = next((c for c in table.columns if c.name == column_name), None)
+        if column is None:
+            unattached_logger.warning(
+                "hivedbparse: COMMENT ON COLUMN references unknown column %s.%s",
+                table_name,
+                column_name,
+            )
+            return
+        column.comment = text
+    else:
+        logger.warning("hivedbparse: unrecognized COMMENT kind %r", kind)
+
+
+def _apply_alter_table(tables: dict[str, Table], node: exp.Alter) -> None:
+    if (node.args.get("kind") or "").upper() != "TABLE":
+        return
+
+    table_name = node.this.name
+    table = tables.get(table_name)
+
+    for fk in node.find_all(exp.ForeignKey):
+        reference = fk.args.get("reference")
+        if reference is None:
+            continue
+        ref_table_name = reference.this.this.name
+        ref_columns = reference.this.expressions
+
+        if table is None:
+            unattached_logger.warning(
+                "hivedbparse: ALTER TABLE ADD FOREIGN KEY references unknown table %s", table_name
+            )
+            continue
+
+        for col, ref_col in zip(fk.expressions, ref_columns):
+            table.fks.append((col.name, ref_table_name, ref_col.name))
+
+
+def _apply_create_index(tables: dict[str, Table], node: exp.Create) -> None:
+    index = node.this
+    table_name = index.args["table"].name
+    table = tables.get(table_name)
+    if table is None:
+        unattached_logger.warning("hivedbparse: CREATE INDEX references unknown table %s", table_name)
+        return
+
+    index_name = index.this.name
+    params = index.args.get("params")
+    columns: list[str] = []
+    if params is not None:
+        for col_expr in params.args.get("columns") or []:
+            column = col_expr.this if isinstance(col_expr, exp.Ordered) else col_expr
+            columns.append(column.name)
+
+    unique = bool(node.args.get("unique"))
+    table.indexes.append((index_name, columns, unique))
+
+
+def _attach_sequence(tables: dict[str, Table], seq_name: str) -> None:
+    """Attach one sequence to its owning table by name (see `_sequence_owner`).
+    Sequences are resolved by name, not by parsing -- so this works for a DB2
+    `CREATE OR REPLACE SEQUENCE` that sqlglot can only degrade to `Command`."""
+    owner = _sequence_owner(tables, seq_name)
+    if owner is None:
+        unattached_logger.warning(
+            "hivedbparse: CREATE SEQUENCE %s has no clear owning table", seq_name
+        )
+        return
+    if seq_name not in owner.sequences:
+        owner.sequences.append(seq_name)
+
+
+def attach_sequences(tables: dict[str, Table], sql: str) -> None:
+    """Attach every `CREATE [OR REPLACE] SEQUENCE` in `sql` to its owning table.
+
+    Run by the runner AFTER reconcile, against the MERGED table set -- not
+    per-dialect inside `apply_aux`. A sequence's owner is found by name, and DB2
+    sequence owners exist only in the merged set: the DB2 dialect barely parses
+    (its files use `!` terminators sqlglot can't split on, so `db2_tables` is
+    nearly empty), while the merged set carries every table name from the Oracle
+    side. Scanning the whole text with `_SEQUENCE_DECL` also handles DB2 sequence
+    files that never split into statements.
+    """
+    for seq_name in _SEQUENCE_DECL.findall(sql):
+        _attach_sequence(tables, seq_name)
+
+
+def _apply_node(tables: dict[str, Table], node: exp.Expression) -> None:
+    if isinstance(node, exp.Comment):
+        _apply_comment(tables, node)
+    elif isinstance(node, exp.Alter):
+        _apply_alter_table(tables, node)
+    elif isinstance(node, exp.Create):
+        # SEQUENCEs are handled before parsing (by name) in `apply_aux`, so a
+        # Create reaching here is only ever an INDEX.
+        if (node.args.get("kind") or "").upper() == "INDEX":
+            _apply_create_index(tables, node)
+    elif isinstance(node, exp.Command):
+        logger.warning("hivedbparse: aux statement degraded to Command, skipping: %.80s", node.sql())
+    # else: statement type we don't attach (e.g. GRANT, CREATE TABLE) -- ignore
+
+
+def apply_aux(tables: dict[str, Table], sql: str, dialect: str) -> None:
+    """Attach comments/FKs/indexes/sequences parsed from `sql` onto `tables`, in place.
+
+    `dialect` is the logical `"oracle"`/`"db2"` label from `parse_tables`; it is
+    mapped to the sqlglot dialect via the shared `_sqlglot_dialect` helper
+    (sqlglot has no native "db2" dialect). Statements are split on top-level
+    semicolons with the dialect's own tokenizer (reusing `_split_statements`
+    from `parse_tables`) and parsed one at a time so that one unparseable or
+    unrelated statement never aborts the rest of the file.
+    """
+    sqlglot_dialect = _sqlglot_dialect(dialect)
+
+    # NB: sequences are NOT handled here -- they're attached post-reconcile
+    # against the merged table set (see `attach_sequences`), because a DB2
+    # sequence's owning table exists only in the merged set. This loop handles
+    # comments, FKs and indexes, which attach to the dialect's own tables.
+    for stmt_text in _split_statements(sql, sqlglot_dialect):
+        if not _is_aux_statement(stmt_text):
+            continue
+        node = _parse_aux_statement(stmt_text, sqlglot_dialect)
+        # Everything reaching here carries content we attach (`_is_aux_statement`
+        # is narrow by design), so failing to parse it -- or only getting an
+        # opaque `Command` back even after the storage-tail retry -- means we are
+        # DROPPING a real index/sequence/FK/comment. That is exactly the silent
+        # loss the verification gate exists to catch, so warn on `logger` (which
+        # the runner routes into the gate) rather than skipping quietly.
+        if node is None or isinstance(node, exp.Command):
+            logger.warning("hivedbparse: could not parse aux statement: %.80s", stmt_text.strip())
+            continue
+        _apply_node(tables, node)