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/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 <host> -U <user> -d <db> -F c -f backup_$(date +%Y%m%d).dump
+```
+
+### 3. Upgrade the package
+
+```bash
+pip install 'litellm[proxy]==<version>'
+```
+
+### 4. Regenerate the Prisma client
+
+```bash
+prisma generate --schema <venv>/lib/python<version>/site-packages/litellm_proxy_extras/schema.prisma
+```
+
+Replace `<venv>` with your virtual environment path and `<version>` 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 <venv>/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 <venv>/bin/activate
+```
+
+Then run the migration with the explicit schema path:
+
+```bash
+prisma migrate deploy --schema <venv>/lib/python<version>/site-packages/litellm_proxy_extras/schema.prisma
+```
+
+Replace `<venv>` with your virtual environment path and `<version>` 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:** `<schema-path>` = `<venv>/lib/python<version>/site-packages/litellm_proxy_extras/schema.prisma`
+
+### Before applying migrations: Preview what will change
+
+Run `pip install 'litellm[proxy]==<version>'` first (Step 3) so the new `schema.prisma` is available.
+
+```bash
+prisma migrate diff \
+  --from-url $DATABASE_URL \
+  --to-schema-datamodel <schema-path> \
+  --script
+```
+
+### After applying migrations: Check status
+
+```bash
+prisma migrate status --schema <schema-path>
+```
+
+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).

docs/my-website/sidebars.js

@@ -1158,6 +1158,7 @@ const sidebars = {
             "troubleshoot/prisma_migrations",
           ],
         },
+        "troubleshoot/pip_venv_upgrade",
         "troubleshoot/rollback",
         "troubleshoot",
       ],