mirror of
https://github.com/BerriAI/litellm.git
synced 2026-11-16 09:22:22 +00:00
Merge 795bc606b3 into 6be98d8c75
This commit is contained in:
commit
ebafd1128a
5 changed files with 1721 additions and 0 deletions
36
.github/workflows/migration-impact.yml
vendored
Normal file
36
.github/workflows/migration-impact.yml
vendored
Normal file
|
|
@ -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}"
|
||||
3
.github/workflows/test-linting.yml
vendored
3
.github/workflows/test-linting.yml
vendored
|
|
@ -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
|
||||
|
||||
|
|
|
|||
970
ci_cd/migration_impact.py
Executable file
970
ci_cd/migration_impact.py
Executable file
|
|
@ -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/<timestamp>_<name>/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 <alias>.*` 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 <alias>.*` 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<tag>[A-Za-z_]*)\$(?P<body>.*?)\$(?P=tag)\$", re.DOTALL)
|
||||
|
||||
_CREATE_TABLE: Final = re.compile(r'\bCREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?"?(?P<table>\w+)"?', re.IGNORECASE)
|
||||
_ALTER_TABLE: Final = re.compile(r'\bALTER\s+TABLE\s+(?:IF\s+EXISTS\s+)?(?:ONLY\s+)?"?(?P<table>\w+)"?', re.IGNORECASE)
|
||||
_DROP_TABLE: Final = re.compile(r'\bDROP\s+TABLE\s+(?:IF\s+EXISTS\s+)?"?(?P<table>\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<table>\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<table>\w+)"?\s+SET\b', re.IGNORECASE)
|
||||
_INSERT: Final = re.compile(r'\bINSERT\s+INTO\s+"?(?P<table>\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"(?<!DROP )(?<!IS )\bNOT\s+NULL\b", re.IGNORECASE)
|
||||
_DEFAULT: Final = re.compile(r"\bDEFAULT\b", re.IGNORECASE)
|
||||
_CONCURRENTLY: Final = re.compile(r"\bCONCURRENTLY\b", re.IGNORECASE)
|
||||
_ADD_CONSTRAINT: Final = re.compile(r"\bADD\s+CONSTRAINT\b", re.IGNORECASE)
|
||||
_NOT_VALID: Final = re.compile(r"\bNOT\s+VALID\b", re.IGNORECASE)
|
||||
_UNIQUE_INDEX: Final = re.compile(r"\bCREATE\s+UNIQUE\s+INDEX\b", re.IGNORECASE)
|
||||
|
||||
_DROP_COLUMN_NAME: Final = re.compile(r'\bDROP\s+COLUMN\s+(?:IF\s+EXISTS\s+)?"?(?P<column>\w+)"?', re.IGNORECASE)
|
||||
_RENAME_COLUMN: Final = re.compile(r'\bRENAME\s+COLUMN\s+"?(?P<column>\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<column>\w+)"?\s+SET\s+NOT\s+NULL', re.IGNORECASE
|
||||
)
|
||||
_TYPE_CHANGE: Final = re.compile(
|
||||
r'\bALTER\s+(?:COLUMN\s+)?"?(?P<column>\w+)"?\s+(?:SET\s+DATA\s+)?TYPE\s+(?P<type>\w+)', re.IGNORECASE
|
||||
)
|
||||
_CONSTRAINT_COLUMNS: Final = re.compile(
|
||||
r"\b(?:FOREIGN\s+KEY|UNIQUE|PRIMARY\s+KEY)\s*\((?P<columns>[^)]*)\)", re.IGNORECASE
|
||||
)
|
||||
_CHECK_BODY: Final = re.compile(r"\bCHECK\s*\((?P<body>.*)\)", re.IGNORECASE | re.DOTALL)
|
||||
_INDEX_COLUMNS: Final = re.compile(
|
||||
r'\bON\s+(?:ONLY\s+)?"?\w+"?\s*(?:USING\s+\w+\s*)?\((?P<columns>[^)]*)\)', re.IGNORECASE
|
||||
)
|
||||
_DROP_INDEX_NAME: Final = re.compile(
|
||||
r'\bDROP\s+INDEX\s+(?:CONCURRENTLY\s+)?(?:IF\s+EXISTS\s+)?"?(?P<index>\w+)"?', re.IGNORECASE
|
||||
)
|
||||
_QUOTED_IDENTIFIER: Final = re.compile(r'"(?P<name>\w+)"')
|
||||
_BARE_WORD: Final = re.compile(r"\b(?P<name>[A-Za-z_]\w*)\b")
|
||||
_ADDED_COLUMN_NAME: Final = re.compile(r'\bADD\s+COLUMN\s+(?:IF\s+NOT\s+EXISTS\s+)?"?(?P<column>\w+)"?', re.IGNORECASE)
|
||||
_INDEX_NAME: Final = re.compile(
|
||||
r'\bCREATE\s+(?:UNIQUE\s+)?INDEX\s+(?:CONCURRENTLY\s+)?(?:IF\s+NOT\s+EXISTS\s+)?"?(?P<index>\w+)"?', re.IGNORECASE
|
||||
)
|
||||
|
||||
_MODEL_BLOCK: Final = re.compile(r"^\s*model\s+(?P<model>\w+)\s*\{(?P<body>.*?)^\s*\}", re.MULTILINE | re.DOTALL)
|
||||
_ENUM_NAME: Final = re.compile(r"^\s*enum\s+(?P<name>\w+)", re.MULTILINE)
|
||||
_PRISMA_FIELD: Final = re.compile(
|
||||
r"^\s*(?P<name>\w+)\s+(?P<type>\w+)(?P<optional>\?)?(?P<array>\[\])?(?P<rest>[^\n]*)$", re.MULTILINE
|
||||
)
|
||||
_FIELD_MAP: Final = re.compile(r'@map\("(?P<name>[^"]+)"\)')
|
||||
_TABLE_MAP: Final = re.compile(r'@@map\("(?P<name>[^"]+)"\)')
|
||||
|
||||
_SQL_LITERAL: Final = re.compile(r"(?P<quote>\"{3}|'{3})(?P<body>.*?)(?P=quote)", re.DOTALL)
|
||||
_FROM_JOIN: Final = re.compile(
|
||||
r'\b(?:FROM|JOIN)\s+"(?P<table>\w+)"(?:\s+AS)?(?:\s+(?P<alias>[A-Za-z_]\w*))?', re.IGNORECASE
|
||||
)
|
||||
_STAR_ALIAS: Final = re.compile(r"\b(?P<alias>[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}/")
|
||||
# <mode> <type> <object>\t<path>
|
||||
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"<sub>Evidence: {'; '.join((schema_note, *reads_note))}.</sub>"
|
||||
|
||||
|
||||
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())
|
||||
|
|
@ -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 <alias>.*` 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 <alias>.*` 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.
|
||||
|
|
|
|||
680
tests/code_coverage_tests/test_migration_impact.py
Normal file
680
tests/code_coverage_tests/test_migration_impact.py
Normal file
|
|
@ -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)<img src=x>\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 "<a href=" not in html
|
||||
assert "<img " not in html
|
||||
assert html.count("<td ") == 4
|
||||
assert "<img src=x>" in html
|
||||
assert "[click](https://example.test)" in html
|
||||
Loading…
Add table
Reference in a new issue