LiteLLM upgrades and database migrations

The main risk in a LiteLLM upgrade is not that a migration fails but that it blocks writes while it runs. By default, each LiteLLM proxy pod runs prisma migrate deploy at startup. One pod performs the migration under a database lock while the other pods wait for it to finish. A rolling restart or a scale-out event can therefore stall for as long as the migration takes, and the stall is largest when the migration touches a large table. Plan the upgrade window around the slowest pod start, not the average one.

The table that usually matters is LiteLLM_SpendLogs, which grows with every request the gateway handles. Creating an index on it, or rewriting the table, holds a lock for the full duration of that operation. LiteLLM's upgrade guide cites measured and estimated times: a plain index build on LiteLLM_SpendLogs takes about 4 to 8 seconds at 10 GB and an estimated 1.5 to 3.5 hours at 10 TB. Table rewrites range from about 1 minute to about 1 day. These figures come from LiteLLM's upgrade guide, and your own table will differ in row width, indexes, PostgreSQL version and hardware, so treat them as reference points rather than a forecast for your system.

The proxy does not wait indefinitely. It stops prisma migrate deploy after LITELLM_PRISMA_MIGRATE_DEPLOY_TIMEOUT seconds, which defaults to 600, and then retries. A migration that needs longer than the timeout will be interrupted and retried, which wastes time and can leave the reader guessing about the state of the schema. Before a large upgrade, decide whether the timeout must be raised for that run, set it deliberately in the deployment configuration, and confirm that the value is applied to every pod that will start during the window.

Estimate the window from evidence, not from the figures above. Copy the production database to a staging environment that matches production in PostgreSQL version and hardware, check the size of LiteLLM_SpendLogs and the row count, identify which migrations the target release contains between your current and target versions, and run those migrations against the copy while timing them. Use the measured duration, add margin for the production load, and compare it with the timeout. Ask your DBA or platform team to confirm that the lock behavior in staging matches production before you schedule the change.

LiteLLM maintains support for the four most recent stable minor versions, and it applies that window to both open source and Enterprise deployments. The practical consequence is that a gateway further behind than that window cannot jump straight to the newest release and expect a supported path. The team has to move in steps that stay within a supported line, and at each step it reads the release notes for every version it passes through. Before planning any step, the operator should confirm the current support status of each candidate version in LiteLLM's vendor documentation, because the window moves as new minor versions ship.

Choosing the target release is a decision the platform owner should make deliberately. The usual choice is the newest stable minor version that the team can test fully against its own configuration, including virtual keys, budgets, router settings, callbacks and any custom providers. Once the version is chosen, pin the exact image tag in the deployment manifest. Avoid floating tags such as main-latest, because a floating tag can change under a running cluster between a test run and a production rollout, and then the version under test is no longer the version in production. The pinned tag should be recorded in change management so that the rollback target is known in advance.

A jump across many minor versions multiplies the work. Every intermediate release adds release notes to read, configuration changes to check and database migrations to test, and the migrations run forward only. If a deployment must cross several lines, each stop becomes its own test cycle with its own backup point, so the team should plan the number of stops before scheduling the change window. Enterprise deployments follow the same support window according to LiteLLM's enterprise documentation, so a licensed gateway gains no extra room to skip versions. Teams should confirm that point in the Enterprise documentation for their contract.

The output of this planning step is a written upgrade path: the current version, the ordered list of pinned target tags, the release notes reviewed for each stop, the support status confirmed for each line and the test environment used for each step. An illustrative example would be a gateway that must pass through three intermediate tags before reaching its target, with a backup and a migration test before each one. Ask the vendor or check the LiteLLM releases page for the latest stable tag and its publication date before the plan is final. At the time of research, the releases page listed v1.105.1, published October 14, 2026, but the current line must be confirmed at planning time.

The test plan for a LiteLLM upgrade should prove that the gateway still behaves the way your teams and budgets depend on, and the rollback plan should be written before the first pod restarts. Treat the upgrade as a change to a running control point, not only a version bump. Run the same test suite against a staging copy of production data, on the exact image tag you intend to deploy, and compare the results with the outcome recorded before the upgrade. Start with smoke tests against each provider route in use. If your gateway sends traffic to OpenAI, Anthropic, Gemini, Bedrock, Azure or a private model, send a short request through every route and every model alias that real applications call. Check the response shape, the streamed output, token counts and the model name written to the logs. A route that quietly stops working after an upgrade often fails only for one provider, so do not sample a single model and assume the rest are healthy.

Next, test authentication and limits with the keys your teams actually hold. Confirm that existing virtual keys still authenticate, and that each key still reports its per-key, per-user and per-team budgets, TPM and RPM limits, temporary budget increases and model restrictions. Send requests that should be refused: a key outside its allowed models, a key past its budget, and a key over its RPM limit. Refusal behavior is the control most likely to change silently, and it is the one your finance and security teams will ask about first. Then test router behavior under failure. Simulate an unavailable deployment and confirm that retries, cooldowns and priority-based failover happen in the order your configuration defines, and that the cooldown ends when the deployment recovers. Also check the admin UI login through your SSO provider, and confirm that log delivery reaches each destination with the fields your retention and privacy rules require. Record every result in a sheet with the image tag, so a later difference can be traced to a specific release.

Rollback has two cases, and they need different plans. If the upgrade fails before the database migration completes, the previous image may be able to run against the unchanged schema. Confirm this in rehearsal, because it depends on whether the new release changed the schema before the failure point. If the migration completes and the new release then fails, the schema has moved forward, and only a verified backup restore returns it to the earlier state. The upgrade guide states that migrations only move forward, so an older image cannot undo a completed migration on its own. Before the window, rehearse the restore on a copy of production and record the exact restore time you observe, including the time to restore the database, start the older image and run the smoke tests again. Use that measured figure, not an estimate, to set the point after which rolling back is no longer practical. Agree in advance who has the authority to call a rollback during the window, who is on the bridge, and what evidence triggers the decision. Ask whether your release changes the schema before the migration step, and confirm the rollback behavior for your specific release in its release notes.