From 9100e167765179c8561eb28c9c9cc27314b623a5 Mon Sep 17 00:00:00 2001 From: milan-berri Date: Tue, 10 Mar 2026 22:53:54 +0200 Subject: [PATCH] docs: pip venv upgrade workflow (#23290) * docs: add pip/venv upgrade workflow guide - Add comprehensive guide for upgrading LiteLLM proxy via pip - Covers Prisma client regeneration and DB migration steps - Includes verification commands and troubleshooting tips - Links to existing Prisma migration troubleshooting doc * docs: clarify Python version in prisma generate command - Update example to show multiple Python versions (3.11, 3.12, 3.13) - Make it clear LiteLLM supports multiple Python versions, not just 3.11 * docs: emphasize venv activation before running commands - Add info box at top reminding users to activate venv - Include venv activation step before starting proxy (both options) - Add Windows activation command for cross-platform clarity - Make it clear all commands assume activated venv * docs: add pip_venv_upgrade to sidebar navigation - Add new page to Troubleshooting section in sidebars.js - Positioned after Performance/Latency category and before rollback - Makes the upgrade guide discoverable through docs navigation * docs: show explicit --schema flag in prisma migrate deploy - Add explicit --schema path to Option B migration command - Remove ambiguous instruction about running from litellm_proxy_extras - Include path variable guidance for clarity - Makes the command immediately runnable without directory navigation * Update docs/my-website/docs/troubleshoot/pip_venv_upgrade.md Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> * Update docs/my-website/docs/troubleshoot/pip_venv_upgrade.md Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> * fix: close code block and add missing section in pip_venv_upgrade.md * docs: define schema-path placeholder in verification section --------- Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> --- .../docs/troubleshoot/pip_venv_upgrade.md | 121 ++++++++++++++++++ docs/my-website/sidebars.js | 1 + 2 files changed, 122 insertions(+) create mode 100644 docs/my-website/docs/troubleshoot/pip_venv_upgrade.md diff --git a/docs/my-website/docs/troubleshoot/pip_venv_upgrade.md b/docs/my-website/docs/troubleshoot/pip_venv_upgrade.md new file mode 100644 index 00000000000..6f5699e3fb0 --- /dev/null +++ b/docs/my-website/docs/troubleshoot/pip_venv_upgrade.md @@ -0,0 +1,121 @@ +# Upgrading LiteLLM Proxy (pip/venv) + +Guide for upgrading LiteLLM Proxy when installed via pip in a virtual environment. + +:::info Important +Always activate your virtual environment before running any `litellm` or `prisma` commands. All commands in this guide assume you're working inside an activated venv. +::: + +## How pip/venv Upgrades Work + +There are two pieces that need to stay in sync: + +1. **Prisma client** - Generated Python code that talks to the DB +2. **DB schema** - Tables/columns in PostgreSQL + +When you upgrade via pip, the `litellm-proxy-extras` package ships with a new `schema.prisma` and a `migrations/` directory. But unlike the Docker image, pip install does NOT automatically regenerate the Prisma client or run migrations. You have to do both manually. + +## Upgrade Workflow (pip/venv) + +### 1. Stop the proxy + +Stop your running LiteLLM proxy instance. + +### 2. (Optional) Back up your DB + +```bash +pg_dump -h -U -d -F c -f backup_$(date +%Y%m%d).dump +``` + +### 3. Upgrade the package + +```bash +pip install 'litellm[proxy]==' +``` + +### 4. Regenerate the Prisma client + +```bash +prisma generate --schema /lib/python/site-packages/litellm_proxy_extras/schema.prisma +``` + +Replace `` with your virtual environment path and `` with your Python version (e.g., `python3.11`, `python3.12`, `python3.13`). + +### 5. Apply DB migrations + +You have two options: + +**Option A: Just start the proxy** (simplest) + +The proxy automatically runs `prisma migrate deploy` on startup, which applies any new migrations. + +First, activate your virtual environment: + +```bash +source /bin/activate +``` + +Then start the proxy: + +```bash +litellm --config your_config.yaml --port 4000 +``` + +**Option B: Run manually before starting** + +Activate your virtual environment first: + +```bash +source /bin/activate +``` + +Then run the migration with the explicit schema path: + +```bash +prisma migrate deploy --schema /lib/python/site-packages/litellm_proxy_extras/schema.prisma +``` + +Replace `` with your virtual environment path and `` with your Python version (e.g., `python3.11`, `python3.12`, `python3.13`). + +### 6. Start the proxy + +If you used Option B above, now start the proxy (with venv still activated): + +```bash +litellm --config your_config.yaml --port 4000 +``` + +## How to Verify Migrations + +> **Note:** `` = `/lib/python/site-packages/litellm_proxy_extras/schema.prisma` + +### Before applying migrations: Preview what will change + +Run `pip install 'litellm[proxy]=='` first (Step 3) so the new `schema.prisma` is available. + +```bash +prisma migrate diff \ + --from-url $DATABASE_URL \ + --to-schema-datamodel \ + --script +``` + +### After applying migrations: Check status + +```bash +prisma migrate status --schema +``` + +All migrations should have a `finished_at` timestamp and no `rolled_back_at`. + +## Key Things to Know + +- **`DISABLE_SCHEMA_UPDATE=true`** env var prevents auto-migration on startup - useful if you want full manual control + +- **`prisma db push`** is the nuclear option: force-syncs the DB to match the schema, bypassing migration history. Safe when all changes are additive (new columns/tables), but always have a backup. + +- **The `schema.prisma` inside `litellm_proxy_extras` is the source of truth** - always use that one, not one from a different version or from the git repo + +## Troubleshooting + +If you encounter migration errors, see the [Prisma Migration Troubleshooting Guide](./prisma_migrations). diff --git a/docs/my-website/sidebars.js b/docs/my-website/sidebars.js index 83a9b0d9648..c36c0cd167e 100644 --- a/docs/my-website/sidebars.js +++ b/docs/my-website/sidebars.js @@ -1158,6 +1158,7 @@ const sidebars = { "troubleshoot/prisma_migrations", ], }, + "troubleshoot/pip_venv_upgrade", "troubleshoot/rollback", "troubleshoot", ],