diff --git a/AGENTS.md b/AGENTS.md index f4b1de57807..c973aeb8f75 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -86,7 +86,7 @@ Do not put names of customers or customer company names in code, PR descriptions CI supply-chain safety: Never pipe a remote script into a shell (`curl ... | bash`, `wget ... | sh`). Download the artifact to a file, verify its SHA-256 checksum, then install. Pin every external tool to a specific version with a full URL (not `latest` or `stable`). Verify checksums for all downloaded binaries, using the provider's official `.sha256` / `.sha256sum` sidecar when available. These rules apply to every download in CI -Prisma migrations apply synchronously at proxy boot, before it serves traffic, so a migration must only change schema, never rewrite rows. No `UPDATE`, `DELETE` or `MERGE`, and no `INSERT ... SELECT`: on a spend-log-sized table any of those is minutes of downtime plus a doubled heap that plain autovacuum won't give back. `tests/code_coverage_tests/check_migrations_no_data_rewrites.py` enforces this. When a rewrite is genuinely bounded and has to ship inside the migration, mark the statement `-- data-migration-ok: ` +Prisma migrations apply synchronously at proxy boot, before it serves traffic, so a migration must only change schema, never rewrite rows. No `UPDATE`, `DELETE` or `MERGE`, and no `INSERT ... SELECT`: on a spend-log-sized table any of those is minutes of downtime plus a doubled heap that plain autovacuum won't give back. `tests/code_coverage_tests/check_migrations_no_data_rewrites.py` enforces this. A migration whose SQL mentions `LiteLLM_SpendLogs` goes in `litellm-proxy-extras/litellm_proxy_extras/spend_logs/migrations/`, every other one in `litellm-proxy-extras/litellm_proxy_extras/migrations/` (`check_spend_logs_folder.py` enforces this, and the proxy merges both at boot) When a rewrite is genuinely bounded and has to ship inside the migration, mark the statement `-- data-migration-ok: ` Follow these coding conventions for new/updated code (a three-line fix in a legacy file shouldn't trigger huge drive-by refactors): diff --git a/docker/Dockerfile.non_root b/docker/Dockerfile.non_root index 90bcc523d9e..99b5629fd6f 100644 --- a/docker/Dockerfile.non_root +++ b/docker/Dockerfile.non_root @@ -184,8 +184,8 @@ RUN mkdir -p /nonexistent /app/.cache /var/lib/litellm/assets /var/lib/litellm/u chown -R nobody:nogroup /app /var/lib/litellm/ui /var/lib/litellm/assets /nonexistent && \ PRISMA_PATH=$(python -c "import os, prisma; print(os.path.dirname(prisma.__file__))") && \ chown -R nobody:nogroup "$PRISMA_PATH" && \ - LITELLM_PKG_MIGRATIONS_PATH="$(python -c 'import os, litellm_proxy_extras; print(os.path.dirname(litellm_proxy_extras.__file__))' 2>/dev/null || echo '')/migrations" && \ - [ -n "$LITELLM_PKG_MIGRATIONS_PATH" ] && chown -R nobody:nogroup "$LITELLM_PKG_MIGRATIONS_PATH" || true && \ + LITELLM_PKG_PATH="$(python -c 'import os, litellm_proxy_extras; print(os.path.dirname(litellm_proxy_extras.__file__))' 2>/dev/null || echo '')" && \ + [ -n "$LITELLM_PKG_PATH" ] && chown -R nobody:nogroup "$LITELLM_PKG_PATH/migrations" "$LITELLM_PKG_PATH/spend_logs/migrations" || true && \ LITELLM_PROXY_EXTRAS_PATH=$(python -c "import os, litellm_proxy_extras; print(os.path.dirname(litellm_proxy_extras.__file__))" 2>/dev/null || echo "") && \ chgrp -R 0 "$PRISMA_PATH" /var/lib/litellm/ui /var/lib/litellm/assets && \ [ -n "$LITELLM_PROXY_EXTRAS_PATH" ] && chgrp -R 0 "$LITELLM_PROXY_EXTRAS_PATH" || true && \ diff --git a/litellm-proxy-extras/migration_runbook.md b/litellm-proxy-extras/migration_runbook.md index b1e9236e520..9ab6db74cde 100644 --- a/litellm-proxy-extras/migration_runbook.md +++ b/litellm-proxy-extras/migration_runbook.md @@ -124,3 +124,12 @@ rm -rf litellm-proxy-extras/litellm_proxy_extras/migrations/[empty_dir] --- **Done with migration?** See [build_and_publish.md](./build_and_publish.md) to publish a new `litellm-proxy-extras` package. + +## Where a migration lives + +Migrations are split across two source folders that the proxy merges into one flat Prisma `migrations/` directory at boot (`litellm_proxy_extras/migration_sources.py`): + +- `litellm_proxy_extras/migrations/` for every table except `LiteLLM_SpendLogs` +- `litellm_proxy_extras/spend_logs/migrations/` for any migration whose SQL mentions `LiteLLM_SpendLogs`, next to `spend_logs/LiteLLM_SpendLogs.prisma` (a copy of the model block in `schema.prisma`) and `spend_logs/request_log_indexes.py` + +The split exists so `spend_logs/` can carry its own `.github/CODEOWNERS` entry. `ci_cd/run_migration.py` picks the folder from the generated SQL, and `tests/code_coverage_tests/check_spend_logs_folder.py` (part of the required `lint passed` check) fails a migration outside `spend_logs/` that mentions the table, or a `LiteLLM_SpendLogs.prisma` copy that drifted from `schema.prisma`. Directory names and apply order are unchanged by the split, so `_prisma_migrations` rows keep matching. diff --git a/tests/code_coverage_tests/check_migrations_no_data_rewrites.py b/tests/code_coverage_tests/check_migrations_no_data_rewrites.py index b16c7aac166..9e3ab501f6f 100644 --- a/tests/code_coverage_tests/check_migrations_no_data_rewrites.py +++ b/tests/code_coverage_tests/check_migrations_no_data_rewrites.py @@ -1054,8 +1054,8 @@ def stale_grandfathers(found: Mapping[str, tuple[Violation, ...]]) -> tuple[str, return tuple(sorted((*clean, *missing))) -def shipped_migrations(migration_sources: tuple[Path, ...] = MIGRATION_SOURCES) -> tuple[Path, ...]: - candidates = chain.from_iterable(source.iterdir() for source in migration_sources) +def shipped_migrations() -> tuple[Path, ...]: + candidates = chain.from_iterable(source.iterdir() for source in MIGRATION_SOURCES) return tuple(sorted((path for path in candidates if (path / "migration.sql").is_file()), key=lambda p: p.name)) diff --git a/tests/unit/test_check_migrations_no_data_rewrites.py b/tests/unit/test_check_migrations_no_data_rewrites.py index b970b56bbc9..1ab3c02057a 100644 --- a/tests/unit/test_check_migrations_no_data_rewrites.py +++ b/tests/unit/test_check_migrations_no_data_rewrites.py @@ -293,7 +293,7 @@ class TestIndexesOnLogTables: ("20260823000000_add_spend_logs_api_key_starttime_index", "20260831120001_spend_logs_litellm_call_id_index"), ) def test_the_inert_index_migrations_scan_clean_without_a_grandfather(self, name): - assert checker.scan_migration(checker.MIGRATIONS_DIR / name) == () + assert checker.scan_migration(checker.MIGRATION_SOURCES[1] / name) == () assert name not in checker.GRANDFATHERED diff --git a/tests/unit/test_check_spend_logs_folder.py b/tests/unit/test_check_spend_logs_folder.py new file mode 100644 index 00000000000..a686a86b0b7 --- /dev/null +++ b/tests/unit/test_check_spend_logs_folder.py @@ -0,0 +1,84 @@ +import importlib.util +import sys +from pathlib import Path +from typing import Final + +import pytest + +_SCRIPT: Final = ( + Path(__file__).resolve().parents[2] / "tests" / "code_coverage_tests" / "check_spend_logs_folder.py" +) +_SPEC: Final = importlib.util.spec_from_file_location("check_spend_logs_folder", _SCRIPT) +assert _SPEC is not None and _SPEC.loader is not None +checker: Final = importlib.util.module_from_spec(_SPEC) +sys.modules["check_spend_logs_folder"] = checker +_SPEC.loader.exec_module(checker) + +MODEL: Final = '''model LiteLLM_SpendLogs { + request_id String @id + api_key String @default("") + + @@index([api_key]) +} +''' +SCHEMA: Final = f"model LiteLLM_Other {{\n id String @id\n}}\n\n{MODEL}\nmodel LiteLLM_Later {{\n id String @id\n}}\n" + + +def _migration(root: Path, name: str, sql: str) -> None: + (root / name).mkdir(parents=True) + (root / name / "migration.sql").write_text(sql, encoding="utf-8") + + +class TestMisplacedMigrations: + def test_a_shared_migration_that_mentions_the_table_is_reported(self, tmp_path): + _migration(tmp_path, "20260101000000_idx", 'CREATE INDEX "x" ON "LiteLLM_SpendLogs"("api_key");') + found: Final = checker.misplaced_migrations(tmp_path) + assert len(found) == 1 + assert "20260101000000_idx/migration.sql" in found[0] + assert "spend_logs/migrations/" in found[0] + + def test_the_match_ignores_case_but_not_longer_identifiers(self, tmp_path): + _migration(tmp_path, "20260101000000_lower", 'ALTER TABLE "litellm_spendlogs" ADD COLUMN "a" TEXT;') + _migration(tmp_path, "20260101000001_other", 'ALTER TABLE "LiteLLM_SpendLogsArchive" ADD COLUMN "a" TEXT;') + found: Final = checker.misplaced_migrations(tmp_path) + assert [v.split("/")[0] for v in found] == ["20260101000000_lower"] + + def test_a_shared_migration_on_another_table_passes(self, tmp_path): + _migration(tmp_path, "20260101000000_other", 'ALTER TABLE "LiteLLM_VerificationToken" ADD COLUMN "a" TEXT;') + assert checker.misplaced_migrations(tmp_path) == () + + +class TestSchemaCopy: + def test_an_exact_copy_of_the_model_block_passes(self, tmp_path): + (tmp_path / "schema.prisma").write_text(SCHEMA, encoding="utf-8") + (tmp_path / "spend_logs").mkdir() + (tmp_path / "spend_logs" / "LiteLLM_SpendLogs.prisma").write_text(MODEL, encoding="utf-8") + assert checker.schema_copy_drift(tmp_path / "schema.prisma", tmp_path / "spend_logs") == () + + @pytest.mark.parametrize("copy", [MODEL.replace("@@index([api_key])", "@@index([api_key, request_id])"), "", None]) + def test_a_drifted_or_missing_copy_is_reported(self, tmp_path, copy): + (tmp_path / "schema.prisma").write_text(SCHEMA, encoding="utf-8") + (tmp_path / "spend_logs").mkdir() + if copy is not None: + (tmp_path / "spend_logs" / "LiteLLM_SpendLogs.prisma").write_text(copy, encoding="utf-8") + found: Final = checker.schema_copy_drift(tmp_path / "schema.prisma", tmp_path / "spend_logs") + assert len(found) == 1 + assert "LiteLLM_SpendLogs.prisma" in found[0] + + def test_a_schema_without_the_model_is_reported(self, tmp_path): + (tmp_path / "schema.prisma").write_text("model LiteLLM_Other {\n id String @id\n}\n", encoding="utf-8") + (tmp_path / "spend_logs").mkdir() + found: Final = checker.schema_copy_drift(tmp_path / "schema.prisma", tmp_path / "spend_logs") + assert found == ("schema.prisma has no `model LiteLLM_SpendLogs` block",) or "no `model LiteLLM_SpendLogs`" in found[0] + + +class TestExitCode: + def test_the_checked_in_tree_passes(self, capsys): + assert checker.main() == 0 + assert "Every LiteLLM_SpendLogs change lives in" in capsys.readouterr().out + + def test_a_violation_fails_and_is_printed(self, tmp_path, monkeypatch, capsys): + _migration(tmp_path, "20260101000000_idx", 'CREATE INDEX "x" ON "LiteLLM_SpendLogs"("api_key");') + monkeypatch.setattr(checker, "SHARED_MIGRATIONS", tmp_path) + assert checker.main() == 1 + assert "20260101000000_idx/migration.sql" in capsys.readouterr().out