diff --git a/.github/workflows/migration-impact.yml b/.github/workflows/migration-impact.yml new file mode 100644 index 00000000000..d37a0915ca3 --- /dev/null +++ b/.github/workflows/migration-impact.yml @@ -0,0 +1,36 @@ +name: Migration Impact Report + +on: + workflow_dispatch: + inputs: + base: + description: Version being upgraded from + required: true + type: string + head: + description: Version being upgraded to + required: true + type: string + +permissions: + contents: read + +jobs: + report: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0 + with: + ref: ${{ github.sha }} + fetch-depth: 0 + persist-credentials: false + - name: Summarize database schema changes + env: + BASE_REF: ${{ inputs.base }} + HEAD_REF: ${{ inputs.head }} + run: | + set -euo pipefail + base_sha=$(git rev-parse --verify --end-of-options "${BASE_REF}^{commit}") + head_sha=$(git rev-parse --verify --end-of-options "${HEAD_REF}^{commit}") + python3 ci_cd/migration_impact.py --base "${base_sha}" --head "${head_sha}" --output "${RUNNER_TEMP}/schema_section.md" + cat "${RUNNER_TEMP}/schema_section.md" >> "${GITHUB_STEP_SUMMARY}" diff --git a/.github/workflows/test-linting.yml b/.github/workflows/test-linting.yml index c3388430589..56b591e64cd 100644 --- a/.github/workflows/test-linting.yml +++ b/.github/workflows/test-linting.yml @@ -541,6 +541,9 @@ jobs: - name: test_workflow_job_name_collisions run: uv run --no-sync pytest -q --noconftest -p no:cacheprovider -c /dev/null tests/code_coverage_tests/test_workflow_job_name_collisions.py + - name: test_migration_impact + run: uv run --no-sync pytest -q --noconftest -p no:cacheprovider -c /dev/null tests/code_coverage_tests/test_migration_impact.py + - name: test_unit_passed_gate run: uv run --no-sync pytest -q --noconftest -p no:cacheprovider -c /dev/null tests/code_coverage_tests/test_unit_passed_gate.py diff --git a/ci_cd/migration_impact.py b/ci_cd/migration_impact.py new file mode 100755 index 00000000000..7cb372c69ae --- /dev/null +++ b/ci_cd/migration_impact.py @@ -0,0 +1,970 @@ +#!/usr/bin/env python3 +"""Report what a version bump does to the proxy's Postgres schema. + +A release does not say what it does to the database. The migrations ship inside the +`litellm-proxy-extras` package (`litellm_proxy_extras/migrations/_/migration.sql`) +and the first pod that boots a new version applies them with `prisma migrate deploy`, while the +generated release notes list commit titles, where a column addition reads as a feature ("add +lifecycle timestamps"). An operator upgrading a multi-replica deployment therefore cannot see, +from the release, which of those migrations the pods still running the previous version survive. + +This script diffs the migration set between two refs, classifies every statement by what it does +to a pod still running the base version, and renders the result as markdown (for the release body) +or JSON. Severities, worst first: + +- `breaking`: the old pods cannot recover on their own. A column they select is dropped, renamed + or changed to a type their client cannot read, or a NOT NULL now rejects the rows they write +- `write-reject`: a new constraint the old pods never enforced. Rows they write that violate it + are rejected; whether any do depends on the data +- `prepared-plan`: the result type of a query the old pods have prepared changes (a whole-row + `SELECT .*` gains a column, or a column widens), so the plans cached on their pooled + connections are rejected with `cached plan must not change result type` until those + connections are recreated +- `lock`: the migration takes a blocking lock, or rewrites rows, on a table already serving traffic +- `info`: no effect on the old pods (new tables, changes to them, columns they do not know) + +The evidence for what the old pods read and write is the base version itself: `schema.prisma` at +`--base` lists every column the old Prisma client selects and inserts, and the source tree at +`--base` holds the raw `SELECT .*` queries. Nothing is hardcoded, so the report keeps +working as the schema and those queries move. + + python3 ci_cd/migration_impact.py --base v1.93.0 --head v1.99.0 + +Standard library only, so it runs on a bare checkout with no `uv sync`. +""" + +from __future__ import annotations + +import argparse +import json +import re +import subprocess +import sys +from collections.abc import Iterable, Mapping, Sequence +from dataclasses import dataclass, field +from pathlib import Path +from types import MappingProxyType +from typing import Final + +MIGRATIONS_DIR: Final = "litellm-proxy-extras/litellm_proxy_extras/migrations" +# git pathspec wildcards cross directory boundaries, so these reach every file under each tree. +SOURCE_GLOBS: Final = ("litellm/*.py", "enterprise/*.py") +TABLE_MARKER: Final = 'FROM "' +# `*` inside a view is expanded when the view is created, so it holds no per-connection plan. +VIEW_MARKER: Final = re.compile(r"\bCREATE\s+(?:OR\s+REPLACE\s+)?(?:MATERIALIZED\s+)?VIEW\b", re.IGNORECASE) + +BREAKING: Final = "breaking" +WRITE_REJECT: Final = "write-reject" +PREPARED_PLAN: Final = "prepared-plan" +LOCK: Final = "lock" +INFO: Final = "info" +SEVERITY_ORDER: Final = (BREAKING, WRITE_REJECT, PREPARED_PLAN, LOCK, INFO) +SEVERITY_LABEL: Final = { + BREAKING: "BREAKING", + WRITE_REJECT: "WRITE-REJECT", + PREPARED_PLAN: "PREPARED-PLAN", + LOCK: "LOCK", + INFO: "INFO", +} +SCHEMA_PATHS: Final = ("schema.prisma", "litellm/proxy/schema.prisma") +PRISMA_SCALARS: Final = frozenset( + {"String", "Int", "BigInt", "Float", "Decimal", "Boolean", "DateTime", "Json", "Bytes"} +) +# Postgres types a column of each Prisma type can become and still be read by the old client. +# Anything else is rated breaking: the plan is rejected once, and the retry cannot map the value. +WIDENING: Final = { + "Int": frozenset({"INT", "INT4", "INTEGER", "BIGINT", "INT8", "NUMERIC", "DECIMAL", "DOUBLE", "REAL", "FLOAT"}), + "BigInt": frozenset({"BIGINT", "INT8", "NUMERIC", "DECIMAL"}), + "Float": frozenset({"DOUBLE", "REAL", "FLOAT", "NUMERIC", "DECIMAL"}), + "Decimal": frozenset({"NUMERIC", "DECIMAL"}), + "String": frozenset({"TEXT", "VARCHAR", "CHARACTER", "CHAR", "CITEXT"}), + "DateTime": frozenset({"TIMESTAMP", "TIMESTAMPTZ"}), + "Json": frozenset({"JSON", "JSONB"}), + "Boolean": frozenset({"BOOLEAN", "BOOL"}), +} + +# Words that can follow a table name where an alias would sit, so they are never read as one. +ALIAS_STOPWORDS: Final = frozenset( + { + "as", + "cross", + "except", + "fetch", + "for", + "full", + "group", + "having", + "inner", + "join", + "left", + "limit", + "intersect", + "natural", + "offset", + "on", + "order", + "outer", + "returning", + "right", + "set", + "tablesample", + "union", + "using", + "values", + "where", + "window", + } +) + +_LINE_COMMENT: Final = re.compile(r"--[^\n]*") +_BLOCK_COMMENT: Final = re.compile(r"/\*.*?\*/", re.DOTALL) +_DOLLAR_QUOTED: Final = re.compile(r"\$(?P[A-Za-z_]*)\$(?P.*?)\$(?P=tag)\$", re.DOTALL) + +_CREATE_TABLE: Final = re.compile(r'\bCREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?"?(?P\w+)"?', re.IGNORECASE) +_ALTER_TABLE: Final = re.compile(r'\bALTER\s+TABLE\s+(?:IF\s+EXISTS\s+)?(?:ONLY\s+)?"?(?P
\w+)"?', re.IGNORECASE) +_DROP_TABLE: Final = re.compile(r'\bDROP\s+TABLE\s+(?:IF\s+EXISTS\s+)?"?(?P
\w+)"?', re.IGNORECASE) +_CREATE_INDEX: Final = re.compile( + r'\bCREATE\s+(?:UNIQUE\s+)?INDEX\s+(?:CONCURRENTLY\s+)?(?:IF\s+NOT\s+EXISTS\s+)?"?\w+"?\s+ON\s+(?:ONLY\s+)?"?(?P
\w+)"?', + re.IGNORECASE, +) +# The `SET` is what separates a backfill from the `ON UPDATE CASCADE` of a foreign key. +_UPDATE: Final = re.compile(r'\bUPDATE\s+(?:ONLY\s+)?"?(?P
\w+)"?\s+SET\b', re.IGNORECASE) +_INSERT: Final = re.compile(r'\bINSERT\s+INTO\s+"?(?P
\w+)"?', re.IGNORECASE) + +_DROP_COLUMN: Final = re.compile(r"\bDROP\s+COLUMN\b", re.IGNORECASE) +_ADD_COLUMN: Final = re.compile(r"\bADD\s+COLUMN\b", re.IGNORECASE) +# One ALTER TABLE carries many comma-separated clauses; split only at a clause keyword so the commas +# inside `NUMERIC(10,2)` or `ARRAY[]::TEXT[]` stay put. +_CLAUSE_SPLIT: Final = re.compile(r",\s*(?=(?:ADD|ALTER|DROP)\s+(?:COLUMN|CONSTRAINT)\b)", re.IGNORECASE) +# Column and table renames only; `ALTER INDEX ... RENAME TO` and `RENAME CONSTRAINT` change nothing a pod reads. +_RENAME: Final = re.compile(r"\bRENAME\s+(?:COLUMN\b|TO\b)", re.IGNORECASE) +_ALTER_TYPE: Final = re.compile(r"\bALTER\s+(?:COLUMN\s+)?\S+\s+(?:SET\s+DATA\s+)?TYPE\b", re.IGNORECASE) +_SET_NOT_NULL: Final = re.compile(r"\bSET\s+NOT\s+NULL\b", re.IGNORECASE) +# `DROP NOT NULL` relaxes a column and `IS NOT NULL` is a predicate; neither adds a constraint. +_NOT_NULL: Final = re.compile(r"(?\w+)"?', re.IGNORECASE) +_RENAME_COLUMN: Final = re.compile(r'\bRENAME\s+COLUMN\s+"?(?P\w+)"?\s+TO\b', re.IGNORECASE) +_RENAME_TABLE: Final = re.compile(r"\bRENAME\s+TO\b", re.IGNORECASE) +_SET_NOT_NULL_COLUMN: Final = re.compile( + r'\bALTER\s+(?:COLUMN\s+)?"?(?P\w+)"?\s+SET\s+NOT\s+NULL', re.IGNORECASE +) +_TYPE_CHANGE: Final = re.compile( + r'\bALTER\s+(?:COLUMN\s+)?"?(?P\w+)"?\s+(?:SET\s+DATA\s+)?TYPE\s+(?P\w+)', re.IGNORECASE +) +_CONSTRAINT_COLUMNS: Final = re.compile( + r"\b(?:FOREIGN\s+KEY|UNIQUE|PRIMARY\s+KEY)\s*\((?P[^)]*)\)", re.IGNORECASE +) +_CHECK_BODY: Final = re.compile(r"\bCHECK\s*\((?P.*)\)", re.IGNORECASE | re.DOTALL) +_INDEX_COLUMNS: Final = re.compile( + r'\bON\s+(?:ONLY\s+)?"?\w+"?\s*(?:USING\s+\w+\s*)?\((?P[^)]*)\)', re.IGNORECASE +) +_DROP_INDEX_NAME: Final = re.compile( + r'\bDROP\s+INDEX\s+(?:CONCURRENTLY\s+)?(?:IF\s+EXISTS\s+)?"?(?P\w+)"?', re.IGNORECASE +) +_QUOTED_IDENTIFIER: Final = re.compile(r'"(?P\w+)"') +_BARE_WORD: Final = re.compile(r"\b(?P[A-Za-z_]\w*)\b") +_ADDED_COLUMN_NAME: Final = re.compile(r'\bADD\s+COLUMN\s+(?:IF\s+NOT\s+EXISTS\s+)?"?(?P\w+)"?', re.IGNORECASE) +_INDEX_NAME: Final = re.compile( + r'\bCREATE\s+(?:UNIQUE\s+)?INDEX\s+(?:CONCURRENTLY\s+)?(?:IF\s+NOT\s+EXISTS\s+)?"?(?P\w+)"?', re.IGNORECASE +) + +_MODEL_BLOCK: Final = re.compile(r"^\s*model\s+(?P\w+)\s*\{(?P.*?)^\s*\}", re.MULTILINE | re.DOTALL) +_ENUM_NAME: Final = re.compile(r"^\s*enum\s+(?P\w+)", re.MULTILINE) +_PRISMA_FIELD: Final = re.compile( + r"^\s*(?P\w+)\s+(?P\w+)(?P\?)?(?P\[\])?(?P[^\n]*)$", re.MULTILINE +) +_FIELD_MAP: Final = re.compile(r'@map\("(?P[^"]+)"\)') +_TABLE_MAP: Final = re.compile(r'@@map\("(?P[^"]+)"\)') + +_SQL_LITERAL: Final = re.compile(r"(?P\"{3}|'{3})(?P.*?)(?P=quote)", re.DOTALL) +_FROM_JOIN: Final = re.compile( + r'\b(?:FROM|JOIN)\s+"(?P
\w+)"(?:\s+AS)?(?:\s+(?P[A-Za-z_]\w*))?', re.IGNORECASE +) +_STAR_ALIAS: Final = re.compile(r"\b(?P[A-Za-z_]\w*)\.\*") +_BARE_STAR: Final = re.compile(r"\bSELECT\s+\*", re.IGNORECASE) +# Release tags an operator could actually be running: 1.99.0, v1.99.0, 1.99.0.post1, v1.99.0-stable. +_STABLE_TAG: Final = re.compile(r"^v?\d+\.\d+\.\d+(?:\.post\d+|-stable(?:\.patch\.\d+)?)?$") + + +@dataclass(frozen=True, slots=True) +class StarRead: + """A query that reads a whole table row, i.e. one whose result type follows the schema.""" + + table: str + alias: str + joined: tuple[str, ...] + location: str + + +@dataclass(frozen=True, slots=True) +class Column: + """One column as the base version's Prisma client knows it.""" + + required: bool + prisma_type: str + + +Schema = Mapping[str, Mapping[str, Column]] + + +@dataclass(frozen=True, slots=True) +class UpgradeContext: + """Everything a statement is rated against: what this upgrade creates, and what the old pods use.""" + + fresh_tables: frozenset[str] + star_reads: tuple[StarRead, ...] + schema: Schema | None + dropped_indexes: frozenset[str] = frozenset() + # (table, column) added by this upgrade with a DEFAULT: the old pods write that default on every insert. + defaulted_columns: frozenset[tuple[str, str]] = frozenset() + # Unique indexes that exist at the base, by name: what a dropped-and-recreated key used to cover. + base_unique_indexes: Mapping[str, tuple[str, tuple[str, ...]]] = field(default_factory=lambda: MappingProxyType({})) + + def column(self, table: str, column: str) -> Column | None: + return None if self.schema is None else self.schema.get(table, {}).get(column) + + def knows_table(self, table: str) -> bool: + return self.schema is None or table in self.schema + + def knows_column(self, table: str, column: str) -> bool: + """Whether the old client selects or writes this column. Without a schema, assume it does.""" + return self.schema is None or self.column(table, column) is not None + + def writes(self, table: str, column: str) -> bool: + """Whether rows the old pods insert carry a value here: a column they know, or a default they get.""" + return self.knows_column(table, column) or (table, column) in self.defaulted_columns + + def replaced_key(self, table: str, columns: Sequence[str]) -> bool: + """Whether a dropped unique index on this table covered a subset of `columns`: the new key then rejects + nothing the old key did not already reject.""" + for name in self.dropped_indexes: + found: Final = self.base_unique_indexes.get(name) + if found is not None and found[0] == table and set(found[1]) <= set(columns): + return True + return False + + +@dataclass(frozen=True, slots=True) +class Finding: + severity: str + migration: str + table: str + statement: str + effect: str + + def as_dict(self) -> dict[str, str]: + return { + "severity": self.severity, + "migration": self.migration, + "table": self.table, + "statement": self.statement, + "effect": self.effect, + } + + +@dataclass(frozen=True, slots=True) +class Report: + base: str + head: str + migrations: tuple[str, ...] + findings: tuple[Finding, ...] + star_reads: tuple[StarRead, ...] + schema_tables: int | None = None + + @property + def worst(self) -> str | None: + for severity in SEVERITY_ORDER: + if any(finding.severity == severity for finding in self.findings): + return severity + return None + + +class GitError(RuntimeError): + """A git command the report depends on could not be run.""" + + +def _git(repo: Path, *args: str) -> str: + result: Final = subprocess.run(("git", "-C", str(repo), *args), check=False, capture_output=True, text=True) + if result.returncode != 0: + raise GitError(f"git {' '.join(args)} failed: {result.stderr.strip()}") + return result.stdout + + +def _git_or_none(repo: Path, *args: str) -> str | None: + try: + return _git(repo, *args) + except GitError: + return None + + +def normalize(statement: str) -> str: + return " ".join(statement.split()).strip() + + +def split_statements(sql: str) -> tuple[str, ...]: + """Split a migration into single-line statements, descending into `DO $$ ... $$` bodies.""" + cleaned: Final = _BLOCK_COMMENT.sub(" ", _LINE_COMMENT.sub(" ", sql)) + bodies: Final = tuple(match.group("body") for match in _DOLLAR_QUOTED.finditer(cleaned)) + outer: Final = _DOLLAR_QUOTED.sub(" ", cleaned) + top_level: Final = tuple(normalize(part) for part in outer.split(";")) + nested: Final = tuple(statement for body in bodies for statement in split_statements(body)) + return tuple(statement for statement in top_level + nested if statement) + + +def statement_table(statement: str) -> str: + for pattern in (_CREATE_TABLE, _ALTER_TABLE, _DROP_TABLE, _CREATE_INDEX, _UPDATE, _INSERT): + match: Final = pattern.search(statement) + if match is not None: + return match.group("table") + return "" + + +def migration_names(repo: Path, ref: str) -> tuple[str, ...]: + """The migration directories at `ref`, skipping `migration_lock.toml` and any stray file.""" + listing: Final = _git(repo, "ls-tree", ref, f"{MIGRATIONS_DIR}/") + # \t + entries: Final = tuple(line.partition("\t") for line in listing.splitlines()) + return tuple(sorted(Path(path).name for meta, _, path in entries if meta.split()[1:2] == ["tree"])) + + +def read_migration(repo: Path, ref: str, name: str) -> str | None: + """The SQL of one migration, or None when the directory has no `migration.sql` (Prisma skips it too).""" + return _git_or_none(repo, "show", f"{ref}:{MIGRATIONS_DIR}/{name}/migration.sql") + + +def tables_created_before(repo: Path, ref: str) -> frozenset[str]: + """Every table some migration at `ref` creates, so a later `CREATE TABLE IF NOT EXISTS` re-declaration + of an existing table is not mistaken for a new one.""" + # Fixed string: `git grep -E` is POSIX ERE, where `\s` is not portable. + listing: Final = _git_or_none( + repo, "grep", "-h", "-i", "--fixed-strings", "CREATE TABLE", ref, "--", f"{MIGRATIONS_DIR}/" + ) + return frozenset(match.group("table") for match in _CREATE_TABLE.finditer(listing or "")) + + +def _model_columns(body: str, enums: frozenset[str]) -> Mapping[str, Column]: + declared: Final = tuple(_PRISMA_FIELD.finditer(body)) + return MappingProxyType( + { + (_FIELD_MAP.search(one.group("rest")) or one).group("name"): Column( + required=one.group("optional") is None, prisma_type=one.group("type") + ) + for one in declared + if one.group("type") in PRISMA_SCALARS or one.group("type") in enums + } + ) + + +def parse_prisma_schema(text: str) -> Schema: + """The tables and columns a Prisma client generated from this schema selects and writes. + + Relation fields are not columns and are skipped; `@map` / `@@map` give the real names. + """ + enums: Final = frozenset(_ENUM_NAME.findall(text)) + return MappingProxyType( + { + (_TABLE_MAP.search(block.group("body")) or block).group( + "name" if _TABLE_MAP.search(block.group("body")) else "model" + ): _model_columns(block.group("body"), enums) + for block in _MODEL_BLOCK.finditer(text) + } + ) + + +def load_base_schema(repo: Path, ref: str) -> Schema | None: + texts: Final = (_git_or_none(repo, "show", f"{ref}:{path}") for path in SCHEMA_PATHS) + return next((parsed for text in texts if text is not None and (parsed := parse_prisma_schema(text))), None) + + +def _identifiers(fragment: str) -> tuple[str, ...]: + """Every name in the fragment, quoted or bare. Bare words include keywords and literals, so callers keep + only the ones that are columns of the table at hand.""" + quoted: Final = tuple(match.group("name") for match in _QUOTED_IDENTIFIER.finditer(fragment)) + unquoted: Final = _QUOTED_IDENTIFIER.sub(" ", re.sub(r"'[^']*'", " ", fragment)) + bare: Final = tuple(match.group("name") for match in _BARE_WORD.finditer(unquoted)) + return tuple(dict.fromkeys(quoted + bare)) + + +def _defaulted_columns(statements: Iterable[str]) -> frozenset[tuple[str, str]]: + """(table, column) pairs these statements add with a DEFAULT.""" + return frozenset( + (statement_table(statement), added.group("column")) + for statement in statements + for clause in _CLAUSE_SPLIT.split(statement) + if (added := _ADDED_COLUMN_NAME.search(clause)) is not None and _DEFAULT.search(clause) is not None + ) + + +def unique_indexes_at(repo: Path, ref: str) -> Mapping[str, tuple[str, tuple[str, ...]]]: + """Every unique index some migration at `ref` creates, by name: its table and columns. + + Read statement by statement, not line by line, because Prisma wraps long index definitions. + """ + listing: Final = _git_or_none( + repo, "grep", "-l", "-i", "--fixed-strings", "CREATE UNIQUE INDEX", ref, "--", f"{MIGRATIONS_DIR}/" + ) + paths: Final = tuple(line.split(":", 1)[1] if ":" in line else line for line in (listing or "").splitlines()) + sources: Final = tuple(text for path in paths if (text := _git_or_none(repo, "show", f"{ref}:{path}")) is not None) + return MappingProxyType( + { + named.group("index"): (statement_table(statement), _index_columns(statement)) + for source in sources + for statement in split_statements(source) + if _UNIQUE_INDEX.search(statement) is not None and (named := _INDEX_NAME.search(statement)) is not None + } + ) + + +def _constraint_columns(statement: str) -> tuple[str, ...]: + """Names a new constraint mentions: the listed columns, and every name inside a CHECK expression.""" + listed: Final = tuple( + name for match in _CONSTRAINT_COLUMNS.finditer(statement) for name in _identifiers(match.group("columns")) + ) + check: Final = _CHECK_BODY.search(statement) + inside: Final = _identifiers(check.group("body")) if check is not None else () + return tuple(dict.fromkeys(listed + inside)) + + +def _index_columns(statement: str) -> tuple[str, ...]: + match: Final = _INDEX_COLUMNS.search(statement) + return _identifiers(match.group("columns")) if match is not None else () + + +def _alias_map(body: str) -> tuple[Mapping[str, str], tuple[str, ...]]: + matches: Final = tuple(_FROM_JOIN.finditer(body)) + tables: Final = tuple(dict.fromkeys(match.group("table") for match in matches)) + aliases: Final = MappingProxyType( + { + match.group("alias"): match.group("table") + for match in matches + if match.group("alias") is not None and match.group("alias").lower() not in ALIAS_STOPWORDS + } + ) + return aliases, tables + + +def _star_reads_in_literal(body: str, location: str) -> tuple[StarRead, ...]: + aliases, tables = _alias_map(body) + starred: Final = tuple( + (aliases[match.group("alias")], match.group("alias")) + for match in _STAR_ALIAS.finditer(body) + if match.group("alias") in aliases + ) + bare: Final = ((tables[0], "*"),) if not starred and _BARE_STAR.search(body) and len(tables) == 1 else () + return tuple( + StarRead(table=table, alias=alias, joined=tuple(other for other in tables if other != table), location=location) + for table, alias in dict.fromkeys(starred + bare) + ) + + +def star_reads_in_source(text: str, path: str) -> tuple[StarRead, ...]: + """Find whole-row reads (`SELECT v.*`, `SELECT *`) in the SQL literals of one source file.""" + return tuple( + read + for literal in _SQL_LITERAL.finditer(text) + if TABLE_MARKER in literal.group("body") + and "SELECT" in literal.group("body").upper() + and VIEW_MARKER.search(literal.group("body")) is None + # `-- Added comma to separate b.* columns` is a comment, not a read. + for read in _star_reads_in_literal( + _LINE_COMMENT.sub(" ", literal.group("body")), f"{path}:{text.count(chr(10), 0, literal.start()) + 1}" + ) + ) + + +def discover_star_reads(repo: Path, ref: str) -> tuple[StarRead, ...]: + listing: Final = _git_or_none(repo, "grep", "-l", "--fixed-strings", TABLE_MARKER, ref, "--", *SOURCE_GLOBS) + paths: Final = tuple(line.split(":", 1)[1] if ":" in line else line for line in (listing or "").splitlines()) + return tuple( + read + for path in paths + if (text := _git_or_none(repo, "show", f"{ref}:{path}")) is not None + for read in star_reads_in_source(text, path) + ) + + +def _shape(read: StarRead) -> str: + return "SELECT *" if read.alias == "*" else f"SELECT {read.alias}.*" + + +def _star_read_for(table: str, star_reads: Sequence[StarRead]) -> StarRead | None: + matches: Final = [read for read in star_reads if read.table == table] + return max(matches, key=lambda read: len(read.joined)) if matches else None + + +def _joined_read_for(table: str, star_reads: Sequence[StarRead]) -> StarRead | None: + return next((read for read in star_reads if table in read.joined), None) + + +@dataclass(frozen=True, slots=True) +class _Site: + """One statement under rating, with what the rules need to know about it.""" + + migration: str + statement: str + table: str + context: UpgradeContext + star: StarRead | None + + @property + def where(self) -> str: + return f" ({_inline_code(self.star.location)})" if self.star is not None else "" + + def rate(self, severity: str, effect: str) -> Finding: + return Finding( + severity=severity, migration=self.migration, table=self.table, statement=self.statement, effect=effect + ) + + def knows(self, column: str) -> bool: + return self.context.knows_column(self.table, column) + + +def _rule_new_table(site: _Site) -> Finding | None: + if _CREATE_TABLE.search(site.statement) is not None: + return site.rate(INFO, "New table. The previous version does not read or write it.") + if site.table and site.table in site.context.fresh_tables: + return site.rate(INFO, "Table is created by this same upgrade, so no old pod reads or writes it yet.") + return None + + +def _rule_drop(site: _Site) -> Finding | None: + if _DROP_TABLE.search(site.statement) is not None: + if site.context.knows_table(site.table): + return site.rate( + BREAKING, "Drops a table the previous version still queries. Old pods keep failing until they are gone." + ) + return site.rate(INFO, "Drops a table the previous version does not know.") + dropped: Final = _DROP_COLUMN_NAME.search(site.statement) + if dropped is None: + return None + column: Final = dropped.group("column") + if site.knows(column): + return site.rate( + BREAKING, + f"Drops {_inline_code(column)}, which the previous version's client selects on every read of this table{site.where}. " + "Old pods keep failing until they are gone; reconnecting does not help.", + ) + return site.rate(INFO, f"Drops {_inline_code(column)}, a column the previous version does not know.") + + +def _rule_rename(site: _Site) -> Finding | None: + renamed: Final = _RENAME_COLUMN.search(site.statement) + if renamed is not None: + old_name: Final = renamed.group("column") + if site.knows(old_name): + return site.rate( + BREAKING, + f"Renames {_inline_code(old_name)}, which the previous version still selects and writes by that name{site.where}. " + "Old pods cannot recover on their own.", + ) + return site.rate(INFO, f"Renames {_inline_code(old_name)}, a column the previous version does not know.") + if _ALTER_TABLE.search(site.statement) is None or _RENAME_TABLE.search(site.statement) is None: + return None + if site.context.knows_table(site.table): + return site.rate(BREAKING, "Renames a table the previous version still queries by its old name.") + return site.rate(INFO, "Renames a table the previous version does not know.") + + +def _rule_not_null(site: _Site) -> Finding | None: + if _ADD_COLUMN.search(site.statement) is not None and _adds_not_null_without_default(site.statement): + return site.rate(BREAKING, "Adds a NOT NULL column with no default, so inserts from the previous version fail.") + required: Final = [match.group("column") for match in _SET_NOT_NULL_COLUMN.finditer(site.statement)] + if required: + unguarded: Final = [ + column + for column in required + if (known := site.context.column(site.table, column)) is None or not known.required + ] + if unguarded or site.context.schema is None: + return site.rate( + BREAKING, + f"Requires {', '.join(_inline_code(column) for column in (unguarded or required))}, which the previous version may write as NULL. " + "Those writes are now rejected.", + ) + return site.rate(INFO, "The previous version already always writes this column, so nothing changes for it.") + return None + + +def _rule_type_change(site: _Site) -> Finding | None: + changes: Final = list(_TYPE_CHANGE.finditer(site.statement)) + if not changes: + return None + narrowing: Final = [ + f"{_inline_code(match.group('column'))} to {match.group('type').upper()}" + for match in changes + if (known := site.context.column(site.table, match.group("column"))) is None + or match.group("type").upper() not in WIDENING.get(known.prisma_type, frozenset()) + ] + if narrowing: + return site.rate( + BREAKING, + f"Changes {', '.join(narrowing)}, which the previous version's client cannot be shown to read. Its " + "prepared plans are rejected once, and the retry may still fail to map the value.", + ) + return site.rate( + PREPARED_PLAN, + "Widens a column's type. Every prepared query on the previous version that returns it is rejected with " + "`cached plan must not change result type` until its connection is recreated, then reads it fine.", + ) + + +def _rule_constraint(site: _Site) -> Finding | None: + if _ADD_CONSTRAINT.search(site.statement) is not None: + if site.context.schema is None: + return site.rate( + WRITE_REJECT, + "Adds a rule the previous version never enforced. Rows it writes that violate the rule are now " + "rejected; whether any do depends on the data.", + ) + checked: Final = [ + column for column in _constraint_columns(site.statement) if site.context.writes(site.table, column) + ] + if checked: + return site.rate( + WRITE_REJECT, + f"Adds a rule on {', '.join(_inline_code(column) for column in checked)} that the previous version never enforced. Rows it writes " + "that violate the rule are now rejected; whether any do depends on the data.", + ) + if _NOT_VALID.search(site.statement) is not None: + return site.rate( + INFO, "Constraint on columns the previous version does not write, with no validation scan." + ) + return site.rate(LOCK, "Validates the constraint against every existing row while holding the table lock.") + if _UNIQUE_INDEX.search(site.statement) is None: + return None + covered: Final = _index_columns(site.statement) + if not covered or not all(site.context.writes(site.table, column) for column in covered): + return None + if site.context.replaced_key(site.table, covered): + return None # the key it replaces already rejected everything this one does + return site.rate( + WRITE_REJECT, + f"Makes {', '.join(_inline_code(column) for column in covered)} unique, which the previous version never enforced. Duplicate rows it " + "writes are now rejected; whether any are depends on the data.", + ) + + +def _rule_whole_row_read(site: _Site) -> Finding | None: + if _ADD_COLUMN.search(site.statement) is None or site.star is None: + return None + return site.rate( + PREPARED_PLAN, + f"Read whole-row by {_inline_code(_shape(site.star))}{site.where}, so the prepared plans cached on the previous " + "version's pooled connections are rejected with `cached plan must not change result type` until those " + "connections are recreated.", + ) + + +def _rule_lock(site: _Site) -> Finding | None: + if _CREATE_INDEX.search(site.statement) is not None and _CONCURRENTLY.search(site.statement) is None: + joined: Final = _joined_read_for(site.table, site.context.star_reads) + read_note: Final = ( + f" The table is joined by {_inline_code(_shape(joined))} ({_inline_code(joined.location)}), so that read waits too." + if joined is not None + else "" + ) + return site.rate( + LOCK, + "Blocks writes to the table (reads continue) until the index is built; the wait scales with the " + f"table's size.{read_note}", + ) + if _UPDATE.search(site.statement) is not None: + return site.rate(LOCK, "Rewrites existing rows, so it holds row locks for as long as the backfill runs.") + return None + + +def _rule_rest(site: _Site) -> Finding: + if _ADD_COLUMN.search(site.statement) is not None: + return site.rate(INFO, "Adds a nullable column to a table the previous version does not read whole-row.") + if _INSERT.search(site.statement) is not None: + return site.rate(INFO, "Inserts rows. The previous version is not affected.") + return site.rate(INFO, "No effect on the previous version.") + + +RULES: Final = ( + _rule_drop, + _rule_rename, + _rule_not_null, + _rule_type_change, + _rule_constraint, + _rule_whole_row_read, + _rule_lock, +) + + +def classify(migration: str, statement: str, context: UpgradeContext) -> Finding: + """Rate one statement by what it does to a pod still running the base version.""" + table: Final = statement_table(statement) + site: Final = _Site(migration, statement, table, context, _star_read_for(table, context.star_reads)) + new_table: Final = _rule_new_table(site) + if new_table is not None: + return new_table + findings: Final = tuple(found for rule in RULES if (found := rule(site)) is not None) + return min(findings, key=lambda finding: SEVERITY_ORDER.index(finding.severity), default=_rule_rest(site)) + + +def _adds_not_null_without_default(statement: str) -> bool: + """True when any `ADD COLUMN` clause of the statement is NOT NULL and has no DEFAULT of its own.""" + return any( + _NOT_NULL.search(clause) is not None and _DEFAULT.search(clause) is None + for clause in _CLAUSE_SPLIT.split(statement) + if _ADD_COLUMN.search(clause) is not None + ) + + +def _context_for( + statements: Sequence[str], + fresh_tables: frozenset[str], + star_reads: tuple[StarRead, ...], + schema: Schema | None, + defaulted: frozenset[tuple[str, str]], + base_unique: Mapping[str, tuple[str, tuple[str, ...]]], +) -> UpgradeContext: + dropped: Final = frozenset( + match.group("index") for statement in statements if (match := _DROP_INDEX_NAME.search(statement)) + ) + return UpgradeContext(fresh_tables, star_reads, schema, dropped, defaulted, base_unique) + + +def build_report(repo: Path, base: str, head: str) -> Report: + base_names: Final = frozenset(migration_names(repo, base)) + new_names: Final = tuple(name for name in migration_names(repo, head) if name not in base_names) + # The plans that break are the ones the old pods hold, so the queries that matter are the base version's. + star_reads: Final = discover_star_reads(repo, base) + + statements_by_migration: Final = MappingProxyType( + {name: split_statements(sql) for name in new_names if (sql := read_migration(repo, head, name)) is not None} + ) + created_here: Final = frozenset( + match.group("table") + for statements in statements_by_migration.values() + for statement in statements + if (match := _CREATE_TABLE.search(statement)) is not None + ) + # A re-declared `CREATE TABLE IF NOT EXISTS` of a table the old pods already use is not a new table. + fresh_tables: Final = created_here - tables_created_before(repo, base) + schema: Final = load_base_schema(repo, base) + defaulted: Final = _defaulted_columns(s for statements in statements_by_migration.values() for s in statements) + base_unique: Final = unique_indexes_at(repo, base) + + findings: Final = tuple( + classify(name, statement, _context_for(statements, fresh_tables, star_reads, schema, defaulted, base_unique)) + for name, statements in statements_by_migration.items() + for statement in statements + ) + ranked: Final = sorted(findings, key=lambda finding: (SEVERITY_ORDER.index(finding.severity), finding.migration)) + return Report( + base=base, + head=head, + migrations=new_names, + findings=tuple(ranked), + star_reads=star_reads, + schema_tables=None if schema is None else len(schema), + ) + + +PROCEDURE: Final = MappingProxyType( + { + BREAKING: ( + "**Do not run the old and new versions side by side.** Take the previous version out of service before " + "the new version applies these migrations, or split the change across two releases." + ), + WRITE_REJECT: ( + "Writes from the previous version that break the new rule are rejected until those pods are gone. Confirm " + "the previous version already satisfies it on your data; if you cannot, do not overlap the two versions." + ), + PREPARED_PLAN: ( + "Expect the queries cited above to fail on pods still running the previous version until their pooled " + "connections are recreated. LiteLLM recreates them on the first such failure as of `1.98.0`; on older " + "versions, or to avoid the failures entirely, set `general_settings.database_disable_prepared_statements: " + "true` before upgrading, or drain the old pods before the new ones migrate." + ), + LOCK: "Apply these migrations in a maintenance window, or during a traffic trough, and watch for lock waits.", + INFO: "Safe to apply during a rolling upgrade.", + } +) + + +def _cited_reads(report: Report) -> tuple[StarRead, ...]: + """The whole-row reads that actually bear on this release, one per table.""" + tables: Final = {finding.table for finding in report.findings if finding.severity != INFO} + representatives: Final = (_star_read_for(table, report.star_reads) for table in sorted(tables)) + return tuple(read for read in representatives if read is not None) + + +def _inline_code(value: str) -> str: + text: Final = " ".join(value.split()).replace("|", "\\|") + fence: Final = "`" * (1 + max((len(run) for run in re.findall(r"`+", text)), default=0)) + padding: Final = " " if "`" in text else "" + return f"{fence}{padding}{text}{padding}{fence}" + + +def _evidence_line(report: Report) -> str: + schema_note: Final = ( + f"no `schema.prisma` at {_inline_code(report.base)}, so drops, renames and constraints are rated as if the previous " + "version used every column" + if report.schema_tables is None + else f"columns the previous version uses: `schema.prisma` at {_inline_code(report.base)} ({report.schema_tables} tables)" + ) + cited: Final = _cited_reads(report) + shapes: Final = ", ".join( + sorted( + { + f"{_inline_code(_shape(read))} on {_inline_code(read.table)} ({_inline_code(read.location)})" + for read in cited + } + ) + ) + reads_note: Final = (f"whole-row reads: {shapes}",) if cited else () + return f"Evidence: {'; '.join((schema_note, *reads_note))}." + + +def render_markdown(report: Report) -> str: + if not report.migrations: + return f"## Database Schema Changes\n\nNo database schema changes since {_inline_code(report.base)}.\n" + + count: Final = len(report.migrations) + notable: Final = tuple(finding for finding in report.findings if finding.severity != INFO) + rows: Final = tuple( + f"| **{SEVERITY_LABEL[finding.severity]}** | {_inline_code(finding.migration)} | {_inline_code(_clip(finding.statement))} | " + f"{finding.effect} |" + for finding in notable[:MAX_ROWS] + ) + overflow: Final = ( + ( + ( + f"| | | | ...and {len(notable) - MAX_ROWS} more, worst first. Run " + f"{_inline_code(f'python3 ci_cd/migration_impact.py --base {report.base} --head {report.head}')} for the full list. |" + ), + ) + if len(notable) > MAX_ROWS + else () + ) + worst: Final = report.worst + quiet: Final = ( + ("| **INFO** | - | - | Nothing in this release affects a pod running the previous version. |",) + if worst is None or worst == INFO + else () + ) + lines: Final = ( + "## Database Schema Changes", + "", + ( + f"This release adds **{count} migration{'' if count == 1 else 's'}** to `litellm-proxy-extras`, applied by " + f"the first pod that boots (`prisma migrate deploy`). Rated against a pod still running {_inline_code(report.base)}:" + ), + "", + "| | Migration | Statement | Effect on pods still on the previous version |", + "|:--:|:--|:--|:--|", + *rows, + *overflow, + *quiet, + "", + PROCEDURE[worst or INFO], + "", + _evidence_line(report), + "", + ) + return "\n".join(lines) + + +_DDL_START: Final = re.compile( + r"\b(?:ALTER\s+TABLE|CREATE\s+(?:UNIQUE\s+)?INDEX|CREATE\s+TABLE|DROP\s+TABLE|DROP\s+INDEX|UPDATE|INSERT\s+INTO)\b", + re.IGNORECASE, +) +MAX_ROWS: Final = 20 + + +def _clip(statement: str, limit: int = 90) -> str: + """Render a statement for the table: the DDL itself, clipped, without its `DO $$` preamble.""" + match: Final = _DDL_START.search(statement) + ddl: Final = statement[match.start() :] if match is not None else statement + clipped: Final = ddl if len(ddl) <= limit else f"{ddl[: limit - 1]}…" + return clipped + + +def render_json(report: Report) -> str: + payload: Final = { + "base": report.base, + "head": report.head, + "worst_severity": report.worst, + "schema_tables": report.schema_tables, + "migrations": list(report.migrations), + "findings": [finding.as_dict() for finding in report.findings], + "star_reads": [ + {"table": read.table, "alias": read.alias, "joined": list(read.joined), "location": read.location} + for read in report.star_reads + ], + } + return json.dumps(payload, indent=2, sort_keys=True) + "\n" + + +def default_base(repo: Path, head: str) -> str: + """The newest stable release reachable from `head`, which is what an operator upgrades from. + + Pre-release tags are skipped: a release cut on top of `v1.102.0-rc.2` still has to tell the + operator what changed since the last version they could have been running. + """ + # Version order, not date order: a backport release branch reaches only its own line's tags, + # and two tags cut in the same second sort arbitrarily by date. + listing: Final = _git_or_none(repo, "tag", "--merged", head, "--sort=-v:refname") + head_sha: Final = (_git_or_none(repo, "rev-parse", head) or "").strip() + for line in (listing or "").splitlines(): + tag = line.strip() + if not _STABLE_TAG.match(tag): + continue + tagged = (_git_or_none(repo, "rev-list", "-n", "1", tag) or "").strip() + if tagged and tagged != head_sha: + return tag + described: Final = _git_or_none(repo, "describe", "--tags", "--abbrev=0", f"{head}^") + if described is None or not described.strip(): + raise GitError(f"found no release tag before {head}; pass --base explicitly (the checkout may lack tags)") + return described.strip() + + +def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace: + parser: Final = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) + parser.add_argument("--base", help="ref of the version being upgraded FROM (default: the tag before --head)") + parser.add_argument("--head", default="HEAD", help="ref of the version being upgraded TO (default: HEAD)") + parser.add_argument("--repo", default=str(Path(__file__).resolve().parents[1]), help="path to the repository") + parser.add_argument("--format", choices=("markdown", "json"), default="markdown") + parser.add_argument("--output", help="write the report here instead of stdout") + parser.add_argument( + "--fail-on", + choices=(BREAKING, WRITE_REJECT, PREPARED_PLAN, LOCK), + help="exit 1 when a finding at this severity or worse is present", + ) + return parser.parse_args(argv) + + +def main(argv: Sequence[str] | None = None) -> int: + args: Final = parse_args(argv) + repo: Final = Path(args.repo) + try: + base: Final = args.base or default_base(repo, args.head) + report: Final = build_report(repo, base, args.head) + except GitError as error: + sys.stderr.write(f"migration impact report skipped: {error}\n") + return 2 + + rendered: Final = render_markdown(report) if args.format == "markdown" else render_json(report) + if args.output: + Path(args.output).write_text(rendered, encoding="utf-8") + else: + sys.stdout.write(rendered) + + worst: Final = report.worst + if args.fail_on and worst is not None and SEVERITY_ORDER.index(worst) <= SEVERITY_ORDER.index(args.fail_on): + sys.stderr.write(f"migration impact: found {worst} changes between {base} and {args.head}\n") + return 1 + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/litellm-proxy-extras/migration_runbook.md b/litellm-proxy-extras/migration_runbook.md index b1e9236e520..788b9fc4428 100644 --- a/litellm-proxy-extras/migration_runbook.md +++ b/litellm-proxy-extras/migration_runbook.md @@ -121,6 +121,38 @@ rm -rf litellm-proxy-extras/litellm_proxy_extras/migrations/[empty_dir] - Never edit existing migration files - Commit schema + migration together +## Upgrade Impact Report + +Migrations in this package are invisible to an operator reading a release: the notes list commit +titles, and the first pod to boot applies the migrations with `prisma migrate deploy` while the +pods running the previous version are still serving traffic. `ci_cd/migration_impact.py` diffs the +migration set between two refs and rates every statement by what it does to those older pods: + +| Severity | Meaning | +|---|---| +| `breaking` | The old pods cannot recover on their own. A column their client selects is dropped, renamed or changed to a type it cannot read, or a NOT NULL now rejects the rows they write | +| `write-reject` | A new constraint (foreign key, check, unique) on columns the old pods write. Rows they write that violate it are rejected; whether any do depends on the data | +| `prepared-plan` | The result type of a query the old pods have prepared changes: a whole-row `SELECT .*` gains a column, or a column widens. The plans cached on their pooled connections are rejected with `cached plan must not change result type` until those connections are recreated ([#36418](https://github.com/BerriAI/litellm/issues/36418)) | +| `lock` | The migration takes a blocking lock, or rewrites rows, on a table already serving traffic | +| `info` | No effect on the old pods: new tables, changes to them, and columns the old pods do not know | + +The evidence is the base version itself, not a hardcoded list. `schema.prisma` at `--base` says +which columns the old Prisma client selects and writes, so dropping a column that schema never +declared is `info`, and dropping one it does declare is `breaking`. The source tree at `--base` +holds the raw `SELECT .*` queries whose plans go stale. The report's footnote names both. + +`create-release.yml` runs this and puts the result at the top of the release body. To see it for +any pair of versions yourself: + +```bash +python3 ci_cd/migration_impact.py --base v1.93.0 --head v1.99.0 +python3 ci_cd/migration_impact.py --base v1.93.0 --head v1.99.0 --format json +``` + +Standard library only, so it needs no `uv sync`. `--fail-on breaking` exits non-zero when a +migration in the range is not safe to apply under a rolling upgrade; `--fail-on write-reject` +also stops on constraints the old pods might violate. + --- **Done with migration?** See [build_and_publish.md](./build_and_publish.md) to publish a new `litellm-proxy-extras` package. diff --git a/tests/code_coverage_tests/test_migration_impact.py b/tests/code_coverage_tests/test_migration_impact.py new file mode 100644 index 00000000000..1e64c32cee6 --- /dev/null +++ b/tests/code_coverage_tests/test_migration_impact.py @@ -0,0 +1,680 @@ +"""Tests for ci_cd/migration_impact.py. + +The fixtures are the real statements from the migrations that caused the rolling-upgrade +failures this report exists to announce: the `key_type` column added to +`LiteLLM_VerificationToken` (issue #36418) and the `api_key_id` -> `target_id` rename hidden +inside a `DO $$` block. +""" + +import importlib.util +import subprocess +import sys +from pathlib import Path +from types import ModuleType +from typing import Final + +import pytest + +ROOT: Final = Path(__file__).resolve().parents[2] +CI_CD: Final = ROOT / "ci_cd" + + +def _load(name: str) -> ModuleType: + spec = importlib.util.spec_from_file_location(name, CI_CD / f"{name}.py") + assert spec is not None and spec.loader is not None + module = importlib.util.module_from_spec(spec) + sys.modules[name] = module + spec.loader.exec_module(module) + return module + + +impact: Final = _load("migration_impact") + +AUTH_QUERY_SOURCE: Final = ''' + sql_query = """ + SELECT + v.*, + t.spend AS team_spend, + -- Added comma to separate b.* columns + b.max_budget AS litellm_budget_table_max_budget + FROM "LiteLLM_VerificationToken" AS v + LEFT JOIN "LiteLLM_TeamTable" AS t ON v.team_id = t.team_id + LEFT JOIN "LiteLLM_BudgetTable" AS b ON v.budget_id = b.budget_id + WHERE v.token = $1 + """ +''' + +VIEW_SOURCE: Final = ''' + await db.execute_raw(""" + CREATE OR REPLACE VIEW "LiteLLM_VerificationTokenView" AS + SELECT v.*, t.spend AS team_spend + FROM "LiteLLM_VerificationToken" v + LEFT JOIN "LiteLLM_TeamTable" t ON v.team_id = t.team_id; + """) +''' + +RENAME_IN_DO_BLOCK: Final = """ +DO $$ +BEGIN + IF EXISTS ( + SELECT 1 FROM information_schema.columns + WHERE table_name = 'LiteLLM_ShadowEvalJob' AND column_name = 'api_key_id' + ) THEN + ALTER TABLE "LiteLLM_ShadowEvalJob" RENAME COLUMN "api_key_id" TO "target_id"; + END IF; +END $$; + +ALTER TABLE "LiteLLM_ShadowEvalJob" ADD COLUMN IF NOT EXISTS "target_type" TEXT NOT NULL DEFAULT 'key'; +""" + + +def _auth_read() -> object: + reads = impact.star_reads_in_source(AUTH_QUERY_SOURCE, "litellm/proxy/utils.py") + assert len(reads) == 1 + return reads[0] + + +BASE_SCHEMA: Final = """ +enum KeyType { + llm_api + management +} + +model LiteLLM_VerificationToken { + token String @id + key_name String? + spend Float @default(0.0) + models String[] + team_id String? + key_type KeyType? + litellm_budget_table LiteLLM_BudgetTable? @relation(fields: [budget_id], references: [budget_id]) + budget_id String? + @@index([team_id]) +} + +model LiteLLM_BudgetTable { + budget_id String @id + max_budget Float? + keys LiteLLM_VerificationToken[] +} + +model LiteLLM_ModelTable { + id Int @id @default(autoincrement()) + model_aliases Json? @map("aliases") + created_at DateTime @default(now()) @map("created_at") +} + +model ClaudeCodePlugin { + id String @id + @@map("LiteLLM_ClaudeCodePluginTable") +} +""" + + +def _context( + fresh: frozenset[str] = frozenset(), + reads: tuple[object, ...] = (), + schema: object = None, + dropped: frozenset[str] = frozenset(), + defaulted: frozenset[tuple[str, str]] = frozenset(), + base_unique: dict[str, tuple[str, tuple[str, ...]]] | None = None, +) -> object: + return impact.UpgradeContext(fresh, reads, schema, dropped, defaulted, base_unique or {}) + + +def _classify( + statement: str, + fresh: frozenset[str] = frozenset(), + reads: tuple[object, ...] = (), + schema: object = None, + dropped: frozenset[str] = frozenset(), + defaulted: frozenset[tuple[str, str]] = frozenset(), + base_unique: dict[str, tuple[str, tuple[str, ...]]] | None = None, +) -> object: + context = _context(fresh, reads, schema, dropped, defaulted, base_unique) + return impact.classify("20260713230852_add_key_type", statement, context) + + +def _base_schema() -> object: + return impact.parse_prisma_schema(BASE_SCHEMA) + + +def test_split_statements_descends_into_dollar_quoted_blocks() -> None: + statements = impact.split_statements(RENAME_IN_DO_BLOCK) + renames = [statement for statement in statements if "RENAME COLUMN" in statement] + assert len(renames) == 1, statements + assert '"api_key_id" TO "target_id"' in renames[0] + + +def test_split_statements_drops_comments() -> None: + statements = impact.split_statements('-- add a column\nALTER TABLE "T" ADD COLUMN "c" TEXT; /* trailing */') + assert statements == ('ALTER TABLE "T" ADD COLUMN "c" TEXT',) + + +def test_star_read_discovery_records_table_alias_and_joins() -> None: + read = _auth_read() + assert read.table == "LiteLLM_VerificationToken" + assert read.alias == "v" + assert set(read.joined) == {"LiteLLM_TeamTable", "LiteLLM_BudgetTable"} + assert read.location.startswith("litellm/proxy/utils.py:") + + +def test_star_read_discovery_ignores_aliases_that_only_appear_in_a_comment() -> None: + # `-- Added comma to separate b.* columns` must not register LiteLLM_BudgetTable as whole-row read. + tables = {read.table for read in impact.star_reads_in_source(AUTH_QUERY_SOURCE, "litellm/proxy/utils.py")} + assert tables == {"LiteLLM_VerificationToken"} + + +def test_star_read_discovery_ignores_view_definitions() -> None: + # A view expands `*` when it is created, so it holds no per-connection prepared plan. + assert impact.star_reads_in_source(VIEW_SOURCE, "litellm/proxy/db/create_views.py") == () + + +def test_add_column_on_a_whole_row_read_table_is_a_prepared_plan_change() -> None: + finding = _classify('ALTER TABLE "LiteLLM_VerificationToken" ADD COLUMN "key_type" TEXT', reads=(_auth_read(),)) + assert finding.severity == impact.PREPARED_PLAN + assert finding.table == "LiteLLM_VerificationToken" + assert "cached plan must not change result type" in finding.effect + assert "litellm/proxy/utils.py" in finding.effect + + +def test_add_column_elsewhere_is_not_reported() -> None: + finding = _classify('ALTER TABLE "LiteLLM_AuditLog" ADD COLUMN "note" TEXT', reads=(_auth_read(),)) + assert finding.severity == impact.INFO + + +def test_drop_column_outranks_the_prepared_plan_rule() -> None: + finding = _classify('ALTER TABLE "LiteLLM_VerificationToken" DROP COLUMN "key_type"', reads=(_auth_read(),)) + assert finding.severity == impact.BREAKING + + +def test_rename_is_breaking() -> None: + finding = _classify('ALTER TABLE "LiteLLM_ShadowEvalJob" RENAME COLUMN "api_key_id" TO "target_id"') + assert finding.severity == impact.BREAKING + + +def test_not_null_column_is_breaking_only_without_a_default() -> None: + without_default = _classify('ALTER TABLE "LiteLLM_SpendLogs" ADD COLUMN "created_at" TIMESTAMP(3) NOT NULL') + with_default = _classify( + 'ALTER TABLE "LiteLLM_SpendLogs" ADD COLUMN "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP' + ) + assert without_default.severity == impact.BREAKING + assert with_default.severity == impact.INFO + + +def test_index_builds_are_rated_by_whether_they_lock() -> None: + blocking = _classify('CREATE INDEX "idx" ON "LiteLLM_SpendLogs"("api_key")') + concurrent = _classify('CREATE INDEX CONCURRENTLY "idx" ON "LiteLLM_SpendLogs"("api_key")') + assert blocking.severity == impact.LOCK + assert concurrent.severity == impact.INFO + + +def test_constraint_on_a_column_the_old_client_writes_can_reject_its_writes() -> None: + # NOT VALID only skips the scan of existing rows; new writes from the old pods are still checked. + schema = _base_schema() + checked = _classify( + 'ALTER TABLE "LiteLLM_VerificationToken" ADD CONSTRAINT "fk" FOREIGN KEY ("budget_id") ' + 'REFERENCES "LiteLLM_BudgetTable"("budget_id") NOT VALID', + schema=schema, + ) + assert checked.severity == impact.WRITE_REJECT + assert "`budget_id`" in checked.effect + + +def test_constraint_on_a_column_the_old_client_does_not_know_is_rated_by_its_scan() -> None: + schema = _base_schema() + validating = _classify( + 'ALTER TABLE "LiteLLM_VerificationToken" ADD CONSTRAINT "fk" FOREIGN KEY ("project_id") ' + 'REFERENCES "LiteLLM_ProjectTable"("project_id")', + schema=schema, + ) + deferred = _classify( + 'ALTER TABLE "LiteLLM_VerificationToken" ADD CONSTRAINT "fk" FOREIGN KEY ("project_id") ' + 'REFERENCES "LiteLLM_ProjectTable"("project_id") NOT VALID', + schema=schema, + ) + assert validating.severity == impact.LOCK + assert deferred.severity == impact.INFO + + +def test_changes_to_a_table_created_by_the_same_upgrade_are_not_reported() -> None: + finding = _classify( + 'CREATE INDEX "idx" ON "LiteLLM_NewTable"("id")', + fresh=frozenset({"LiteLLM_NewTable"}), + ) + assert finding.severity == impact.INFO + assert "created by this same upgrade" in finding.effect + + +def _report(findings: tuple[object, ...], migrations: tuple[str, ...] = ("20260713230852_add_key_type",)) -> object: + return impact.Report( + base="v1.93.0", head="v1.99.0", migrations=migrations, findings=findings, star_reads=(_auth_read(),) + ) + + +def test_markdown_for_an_upgrade_with_no_migrations() -> None: + rendered = impact.render_markdown(_report(findings=(), migrations=())) + assert "No database schema changes since `v1.93.0`." in rendered + assert "|" not in rendered + + +def test_markdown_leads_with_the_worst_finding_and_its_procedure() -> None: + finding = _classify('ALTER TABLE "LiteLLM_VerificationToken" ADD COLUMN "key_type" TEXT', reads=(_auth_read(),)) + rendered = impact.render_markdown(_report(findings=(finding,))) + assert "20260713230852_add_key_type" in rendered + assert "| **PREPARED-PLAN** |" in rendered + assert impact.PROCEDURE[impact.PREPARED_PLAN] in rendered + assert "`SELECT v.*` on `LiteLLM_VerificationToken`" in rendered + + +def test_markdown_caps_the_table_and_says_where_the_rest_is() -> None: + finding = _classify('ALTER TABLE "LiteLLM_VerificationToken" ADD COLUMN "key_type" TEXT', reads=(_auth_read(),)) + rendered = impact.render_markdown(_report(findings=tuple([finding] * (impact.MAX_ROWS + 3)))) + assert rendered.count("| **PREPARED-PLAN** |") == impact.MAX_ROWS + assert "...and 3 more" in rendered + + +def test_worst_severity_ranks_breaking_above_the_rest() -> None: + lock = _classify('CREATE INDEX "idx" ON "LiteLLM_SpendLogs"("api_key")') + breaking = _classify('ALTER TABLE "LiteLLM_VerificationToken" DROP COLUMN "key_type"', reads=(_auth_read(),)) + assert _report(findings=(lock, breaking)).worst == impact.BREAKING + assert _report(findings=(lock,)).worst == impact.LOCK + + +def _git(repo: Path, *args: str) -> None: + subprocess.run(("git", "-C", str(repo), *args), check=True, capture_output=True) + + +def _commit(repo: Path, message: str) -> None: + (repo / "file.txt").write_text(message, encoding="utf-8") + _git(repo, "add", "file.txt") + _git(repo, "commit", "-m", message) + + +def test_default_base_is_the_newest_stable_release_not_the_newest_tag(tmp_path: Path) -> None: + repo = tmp_path / "repo" + repo.mkdir() + _git(repo, "init", "-q", "-b", "main") + _git(repo, "config", "user.email", "test@example.com") + _git(repo, "config", "user.name", "test") + _commit(repo, "first") + _git(repo, "tag", "v1.98.0") + _commit(repo, "second") + _git(repo, "tag", "v1.99.0") + _commit(repo, "third") + _git(repo, "tag", "v1.100.0-rc.1") + _commit(repo, "fourth") + + # The release being cut sits on top of an rc tag; the operator is upgrading from v1.99.0. + assert impact.default_base(repo, "HEAD") == "v1.99.0" + + +def test_default_base_skips_the_tag_that_points_at_the_release_itself(tmp_path: Path) -> None: + repo = tmp_path / "repo" + repo.mkdir() + _git(repo, "init", "-q", "-b", "main") + _git(repo, "config", "user.email", "test@example.com") + _git(repo, "config", "user.name", "test") + _commit(repo, "first") + _git(repo, "tag", "v1.99.0") + _commit(repo, "second") + _git(repo, "tag", "v1.100.0") + + assert impact.default_base(repo, "v1.100.0") == "v1.99.0" + + +def test_foreign_key_on_update_is_not_a_backfill() -> None: + # `ON UPDATE CASCADE` is part of the constraint; only `UPDATE ... SET` rewrites rows. + finding = _classify( + 'ALTER TABLE "LiteLLM_JWTKeyMapping" ADD CONSTRAINT "fk" FOREIGN KEY ("token") ' + 'REFERENCES "LiteLLM_VerificationToken"("token") ON DELETE CASCADE ON UPDATE CASCADE NOT VALID' + ) + assert finding.severity == impact.WRITE_REJECT + assert "backfill" not in finding.effect + backfill = _classify('UPDATE "LiteLLM_SpendLogs" SET "created_at" = "startTime" WHERE "created_at" IS NULL') + assert backfill.severity == impact.LOCK + + +def test_index_rename_is_not_breaking() -> None: + finding = _classify('ALTER INDEX "old_idx" RENAME TO "new_idx"') + assert finding.severity == impact.INFO + + +SPEND_SCHEMA: Final = "model LiteLLM_DailyTagSpend {\n id String @id\n prompt_tokens Int\n}\n" + + +def test_widening_a_type_is_a_prepared_plan_change() -> None: + finding = _classify( + 'ALTER TABLE "LiteLLM_DailyTagSpend" ALTER COLUMN "prompt_tokens" SET DATA TYPE BIGINT', + schema=impact.parse_prisma_schema(SPEND_SCHEMA), + ) + assert finding.severity == impact.PREPARED_PLAN + assert "cached plan must not change result type" in finding.effect + + +def test_a_type_the_old_client_cannot_read_is_breaking() -> None: + finding = _classify( + 'ALTER TABLE "LiteLLM_DailyTagSpend" ALTER COLUMN "prompt_tokens" SET DATA TYPE TEXT', + schema=impact.parse_prisma_schema(SPEND_SCHEMA), + ) + assert finding.severity == impact.BREAKING + assert "`prompt_tokens` to TEXT" in finding.effect + + +def test_type_change_without_a_schema_to_check_against_is_breaking() -> None: + finding = _classify('ALTER TABLE "LiteLLM_DailyTagSpend" ALTER COLUMN "prompt_tokens" SET DATA TYPE BIGINT') + assert finding.severity == impact.BREAKING + + +def test_not_null_is_judged_per_add_column_clause() -> None: + one_default_is_not_enough = _classify( + 'ALTER TABLE "LiteLLM_SpendLogs" ADD COLUMN "a" TEXT NOT NULL DEFAULT \'x\', ADD COLUMN "b" TEXT NOT NULL' + ) + assert one_default_is_not_enough.severity == impact.BREAKING + + +@pytest.mark.parametrize("benign", ['DROP COLUMN "unknown"', 'ALTER COLUMN "token" SET NOT NULL']) +@pytest.mark.parametrize( + "change,severity,effect", + [ + ('ADD COLUMN "required_new" TEXT NOT NULL', impact.BREAKING, "no default"), + ('ALTER COLUMN "token" TYPE INTEGER', impact.BREAKING, "to INTEGER"), + ('ADD COLUMN "optional_new" TEXT', impact.PREPARED_PLAN, "cached plan"), + ], +) +def test_compound_alter_keeps_the_worst_effect(benign: str, change: str, severity: str, effect: str) -> None: + statement: Final = f'ALTER TABLE "LiteLLM_VerificationToken" {benign}, {change}' + finding: Final = _classify(statement, schema=_base_schema(), reads=(_auth_read(),)) + assert finding.severity == severity + assert effect in finding.effect + assert finding.statement == statement + + +def test_drop_not_null_beside_an_add_column_is_not_breaking() -> None: + # 20250707230009_add_mcp_namespaced_tool_name: the `NOT NULL` here belongs to `DROP NOT NULL`. + finding = _classify( + 'ALTER TABLE "LiteLLM_DailyTagSpend" ADD COLUMN IF NOT EXISTS "mcp_namespaced_tool_name" TEXT, ' + 'ALTER COLUMN "model" DROP NOT NULL' + ) + assert finding.severity == impact.INFO + + +def test_insert_is_informational() -> None: + finding = _classify('INSERT INTO "LiteLLM_Config" ("param_name") VALUES (\'x\')') + assert finding.severity == impact.INFO + + +def test_markdown_escapes_pipes_inside_a_statement() -> None: + finding = _classify("UPDATE \"LiteLLM_SpendLogs\" SET \"note\" = 'a' || 'b'") + rendered = impact.render_markdown(_report(findings=(finding,))) + assert "'a' \\|\\| 'b'" in rendered + assert "'a' || 'b'" not in rendered + + +BASE_SOURCE: Final = ''' +SQL = """ + SELECT v.*, t.spend AS team_spend + FROM "LiteLLM_VerificationToken" AS v + LEFT JOIN "LiteLLM_TeamTable" AS t ON v.team_id = t.team_id + WHERE v.token = $1 +""" +''' + +HEAD_SOURCE: Final = ''' +SQL = """ + SELECT v.token, v.key_type, t.spend AS team_spend + FROM "LiteLLM_VerificationToken" AS v + LEFT JOIN "LiteLLM_TeamTable" AS t ON v.team_id = t.team_id + WHERE v.token = $1 +""" +''' + + +def _write_migration(repo: Path, name: str, sql: str) -> None: + directory = repo / impact.MIGRATIONS_DIR / name + directory.mkdir(parents=True) + (directory / "migration.sql").write_text(sql, encoding="utf-8") + + +def _two_version_repo(tmp_path: Path) -> Path: + """A repo whose base tag reads the token table whole-row and whose head no longer does.""" + repo = tmp_path / "repo" + repo.mkdir() + _git(repo, "init", "-q", "-b", "main") + _git(repo, "config", "user.email", "test@example.com") + _git(repo, "config", "user.name", "test") + (repo / "litellm" / "proxy").mkdir(parents=True) + (repo / "litellm" / "proxy" / "utils.py").write_text(BASE_SOURCE, encoding="utf-8") + (repo / "schema.prisma").write_text(BASE_SCHEMA, encoding="utf-8") + _write_migration( + repo, + "20250101000000_baseline", + 'CREATE TABLE "LiteLLM_VerificationToken" ("token" TEXT PRIMARY KEY);\n' + 'CREATE TABLE "LiteLLM_TeamTable" ("team_id" TEXT PRIMARY KEY);\n' + 'CREATE UNIQUE INDEX "LiteLLM_VerificationToken_key_name_key" ON "LiteLLM_VerificationToken"("key_name");\n', + ) + (repo / impact.MIGRATIONS_DIR / "migration_lock.toml").write_text('provider = "postgresql"\n', encoding="utf-8") + _git(repo, "add", ".") + _git(repo, "commit", "-q", "-m", "base") + _git(repo, "tag", "v1.0.0") + + (repo / "litellm" / "proxy" / "utils.py").write_text(HEAD_SOURCE, encoding="utf-8") + _write_migration( + repo, + "20250201000000_add_key_type", + # Re-declaring an existing table must not make it "fresh"; the ADD COLUMN after it is real. + 'CREATE TABLE IF NOT EXISTS "LiteLLM_VerificationToken" ("token" TEXT PRIMARY KEY);\n' + 'ALTER TABLE "LiteLLM_VerificationToken" ADD COLUMN "key_type" TEXT;\n' + 'CREATE TABLE "LiteLLM_NewTable" ("id" TEXT PRIMARY KEY);\n' + 'CREATE INDEX "new_idx" ON "LiteLLM_NewTable"("id");\n' + # A column the base schema never declared: the old client cannot miss it. + 'ALTER TABLE "LiteLLM_TeamTable" DROP COLUMN IF EXISTS "legacy_flag";\n' + # A column it does declare: the old client selects it on every read. + 'ALTER TABLE "LiteLLM_VerificationToken" DROP COLUMN "key_name";\n', + ) + _write_migration( + repo, + "20250202000000_scope_key_name_by_issuer", + # The jwt_issuer pattern: drop the old key, add a defaulted column, recreate the key wider. + 'DROP INDEX IF EXISTS "LiteLLM_VerificationToken_key_name_key";\n' + 'ALTER TABLE "LiteLLM_VerificationToken" ADD COLUMN IF NOT EXISTS "issuer" TEXT NOT NULL DEFAULT \'\';\n' + 'CREATE UNIQUE INDEX "LiteLLM_VerificationToken_issuer_key_name_key" ON "LiteLLM_VerificationToken"' + '("issuer", "key_name");\n', + ) + _git(repo, "add", ".") + _git(repo, "commit", "-q", "-m", "head") + _git(repo, "tag", "v1.1.0") + return repo + + +def test_report_rates_migrations_against_the_queries_the_old_pods_run(tmp_path: Path) -> None: + repo = _two_version_repo(tmp_path) + report = impact.build_report(repo, "v1.0.0", "v1.1.0") + + assert report.migrations == ("20250201000000_add_key_type", "20250202000000_scope_key_name_by_issuer") + # The whole-row read exists only at v1.0.0; that is the version whose plans go stale. + assert [read.table for read in report.star_reads] == ["LiteLLM_VerificationToken"] + assert report.star_reads[0].location.startswith("litellm/proxy/utils.py:") + + by_statement = {finding.statement: finding for finding in report.findings} + add_column = by_statement['ALTER TABLE "LiteLLM_VerificationToken" ADD COLUMN "key_type" TEXT'] + assert add_column.severity == impact.PREPARED_PLAN + new_index = by_statement['CREATE INDEX "new_idx" ON "LiteLLM_NewTable"("id")'] + assert new_index.severity == impact.INFO + unknown_drop = by_statement['ALTER TABLE "LiteLLM_TeamTable" DROP COLUMN IF EXISTS "legacy_flag"'] + assert unknown_drop.severity == impact.INFO + known_drop = by_statement['ALTER TABLE "LiteLLM_VerificationToken" DROP COLUMN "key_name"'] + assert known_drop.severity == impact.BREAKING + widened_key = by_statement[ + 'CREATE UNIQUE INDEX "LiteLLM_VerificationToken_issuer_key_name_key" ON "LiteLLM_VerificationToken"' + '("issuer", "key_name")' + ] + assert widened_key.severity == impact.LOCK # widens the key it drops, so nothing new is rejected + assert report.schema_tables == 4 + assert report.worst == impact.BREAKING + + +def test_report_for_the_same_ref_twice_has_nothing_to_say(tmp_path: Path) -> None: + repo = _two_version_repo(tmp_path) + report = impact.build_report(repo, "v1.1.0", "v1.1.0") + assert report.migrations == () + assert report.findings == () + assert "No database schema changes since `v1.1.0`." in impact.render_markdown(report) + + +def test_schema_parser_reads_columns_maps_and_enums_and_skips_relations() -> None: + schema = _base_schema() + token = schema["LiteLLM_VerificationToken"] + assert token["token"] == impact.Column(required=True, prisma_type="String") + assert token["key_name"] == impact.Column(required=False, prisma_type="String") + assert token["models"].required # a list column is NOT NULL + assert token["key_type"].prisma_type == "KeyType" # enum-typed column + assert "litellm_budget_table" not in token # relation field, not a column + assert "aliases" in schema["LiteLLM_ModelTable"] # @map renames the column + assert "model_aliases" not in schema["LiteLLM_ModelTable"] + assert "LiteLLM_ClaudeCodePluginTable" in schema # @@map renames the table + assert "ClaudeCodePlugin" not in schema + + +def test_dropping_a_column_the_old_client_never_selects_is_not_breaking() -> None: + schema = _base_schema() + known = _classify('ALTER TABLE "LiteLLM_VerificationToken" DROP COLUMN "key_name"', schema=schema) + unknown = _classify('ALTER TABLE "LiteLLM_VerificationToken" DROP COLUMN "settings_updated_at"', schema=schema) + assert known.severity == impact.BREAKING + assert "`key_name`" in known.effect + assert unknown.severity == impact.INFO + + +def test_renaming_a_column_is_rated_by_whether_the_old_client_uses_it() -> None: + schema = _base_schema() + known = _classify('ALTER TABLE "LiteLLM_VerificationToken" RENAME COLUMN "team_id" TO "owner_team"', schema=schema) + unknown = _classify('ALTER TABLE "LiteLLM_VerificationToken" RENAME COLUMN "tmp" TO "final"', schema=schema) + assert known.severity == impact.BREAKING + assert unknown.severity == impact.INFO + + +def test_set_not_null_is_breaking_only_where_the_old_client_may_write_null() -> None: + schema = _base_schema() + optional_at_base = _classify( + 'ALTER TABLE "LiteLLM_VerificationToken" ALTER COLUMN "key_name" SET NOT NULL', schema=schema + ) + required_at_base = _classify( + 'ALTER TABLE "LiteLLM_VerificationToken" ALTER COLUMN "spend" SET NOT NULL', schema=schema + ) + assert optional_at_base.severity == impact.BREAKING + assert required_at_base.severity == impact.INFO + + +def test_dropping_a_table_the_old_client_does_not_know_is_informational() -> None: + schema = _base_schema() + known = _classify('DROP TABLE "LiteLLM_BudgetTable"', schema=schema) + unknown = _classify('DROP TABLE "LiteLLM_TmpTable"', schema=schema) + assert known.severity == impact.BREAKING + assert unknown.severity == impact.INFO + + +def test_unique_index_on_columns_the_old_client_writes_can_reject_duplicates() -> None: + finding = _classify( + 'CREATE UNIQUE INDEX "LiteLLM_VerificationToken_key_name_key" ON "LiteLLM_VerificationToken"("key_name")', + schema=_base_schema(), + ) + assert finding.severity == impact.WRITE_REJECT + + +TOKEN_KEY_NAME_KEY: Final = {"LiteLLM_VerificationToken_key_name_key": ("LiteLLM_VerificationToken", ("key_name",))} + + +def test_unique_index_that_widens_a_dropped_key_is_only_a_lock() -> None: + # The Daily*Spend migrations drop the old unique key and create a wider one in the same file: every + # duplicate the new key rejects, the old key already rejected. + finding = _classify( + 'CREATE UNIQUE INDEX "LiteLLM_VerificationToken_key_name_team_id_key" ON "LiteLLM_VerificationToken"' + '("key_name", "team_id")', + schema=_base_schema(), + dropped=frozenset({"LiteLLM_VerificationToken_key_name_key"}), + base_unique=TOKEN_KEY_NAME_KEY, + ) + assert finding.severity == impact.LOCK + + +def test_unique_index_that_narrows_a_dropped_key_can_reject_writes() -> None: + # Dropping (key_name, team_id) for (key_name) is stricter: rows that only differed by team now collide. + finding = _classify( + 'CREATE UNIQUE INDEX "LiteLLM_VerificationToken_key_name_key" ON "LiteLLM_VerificationToken"("key_name")', + schema=_base_schema(), + dropped=frozenset({"LiteLLM_VerificationToken_key_name_team_id_key"}), + base_unique={ + "LiteLLM_VerificationToken_key_name_team_id_key": ("LiteLLM_VerificationToken", ("key_name", "team_id")) + }, + ) + assert finding.severity == impact.WRITE_REJECT + + +def test_unique_index_over_a_new_defaulted_column_still_binds_the_old_pods() -> None: + # Old pods insert the default, so the new column does not make their rows distinct. + finding = _classify( + 'CREATE UNIQUE INDEX "idx" ON "LiteLLM_VerificationToken"("key_name", "jwt_issuer")', + schema=_base_schema(), + defaulted=frozenset({("LiteLLM_VerificationToken", "jwt_issuer")}), + ) + assert finding.severity == impact.WRITE_REJECT + + +def test_check_constraint_with_unquoted_columns_is_matched_against_the_schema() -> None: + finding = _classify( + 'ALTER TABLE "LiteLLM_VerificationToken" ADD CONSTRAINT "chk" CHECK (key_name <> \'active\') NOT VALID', + schema=_base_schema(), + ) + assert finding.severity == impact.WRITE_REJECT + assert "`key_name`" in finding.effect + assert "active" not in finding.effect # a string literal is not a column + + +def test_constraint_without_a_schema_to_check_against_is_write_reject() -> None: + finding = _classify('ALTER TABLE "LiteLLM_VerificationToken" ADD CONSTRAINT "chk" CHECK (status = \'active\')') + assert finding.severity == impact.WRITE_REJECT + + +def test_defaulted_columns_are_collected_per_clause() -> None: + statements = [ + 'ALTER TABLE "T" ADD COLUMN "a" TEXT NOT NULL DEFAULT \'\', ADD COLUMN "b" TEXT', + 'ALTER TABLE "U" ADD COLUMN IF NOT EXISTS "c" INT DEFAULT 0', + ] + assert impact._defaulted_columns(statements) == frozenset({("T", "a"), ("U", "c")}) + + +def test_unique_index_on_a_new_column_is_only_a_lock() -> None: + finding = _classify( + 'CREATE UNIQUE INDEX "idx" ON "LiteLLM_VerificationToken"("settings_updated_at")', schema=_base_schema() + ) + assert finding.severity == impact.LOCK + + +def test_markdown_names_the_schema_it_used_as_evidence() -> None: + report = impact.Report( + base="v1.93.0", head="v1.99.0", migrations=("m",), findings=(), star_reads=(), schema_tables=65 + ) + assert "`schema.prisma` at `v1.93.0` (65 tables)" in impact.render_markdown(report) + blind = impact.Report(base="v1.93.0", head="v1.99.0", migrations=("m",), findings=(), star_reads=()) + assert "no `schema.prisma` at `v1.93.0`" in impact.render_markdown(blind) + + +def test_markdown_keeps_repository_text_inside_code_spans() -> None: + from dataclasses import replace + + from markdown_it import MarkdownIt + + payload: Final = "`[click](https://example.test)\n| injected" + finding: Final = replace( + _classify(f'DROP TABLE "x"; -- {payload}'), + migration=payload, + ) + report: Final = replace(_report(findings=(finding,)), base=payload, head=payload) + rendered: Final = impact.render_markdown(report) + html: Final = MarkdownIt("commonmark").enable("table").render(rendered) + + assert "