Skip to content

Upgrades and migrations

Record the current and target versions and review compatibility changes. When skipping releases, apply every pending migration, not just the final release’s new SQL.

  1. Back up the database and confirm a recovery path.
  2. Plan maintenance mode according to migration requirements and wait for in-flight work.
  3. Apply pending migrations for the selected database in numeric order.
  4. Roll matching Proxy, Admin and migration-tool versions.
  5. Verify health, sign-in, real calls, logs and quota changes before ending maintenance.

A particular release may require a stricter cutover. This summary is not a substitute for its production migration instructions.

From 2.19.0 apply 0036 first. It adds the application directory, client registration and authorization request tables for the built-in OAuth authorization server, plus nullable columns on OAuth access tokens. Migrate before updating the Proxy, Admin and migrate images to the same version; older Proxy and Admin versions keep working against the migrated database. Apply the schema change even if you will not enable the built-in server yet.

  • 0036: built-in OAuth authorization server
  • New MCP_OAUTH_ISSUER and optional MCP_OAUTH_CONSENT_URL; with MCP_OAUTH_ISSUER empty, behavior is unchanged. Admin adds an optional runtime variable GATEWAY_PROXY_URL for the default Proxy address used by REST docs, Simulator and MCP connection guides.
  • Integration keys that call /api/admin/oauth/* need oauth.read, oauth.write or oauth.consent.
  • Invocations are now part of Request logs; the old /gateway/tools/invocations address redirects there with its filters.
  • New catalog entries (such as gemini-4-hydrogen, gemini-4-carbon, qwen4-max-preview and minimax-h3-image) must be imported and routed manually.
  • Switching to the built-in authorization server is done per deployment region; see MCP OAuth authorization. See the v2.20.0 release notes for the full list.

Upgrading from 2.18.0 to 2.19.0 adds no database migration and no new or renamed environment variables or system_config keys. Update the Proxy, Admin and migrate images to the same version and perform a rolling restart. When upgrading from an earlier release, still apply every migration that has not yet run.

  • Maintenance mode now lives in the Maintenance mode section of System → Config, and the old address redirects. Integration Keys moved into the System group.
  • New catalog entries (such as claude-fable-5-2, glm-5v-turbo, hy4 and gpt-image-2.6-flare) must be imported and routed manually; already imported models are not overwritten.
  • From 2026-12-01 Google automatically reroutes gemini-2.5-pro and gemini-2.5-flash. Review related routes beforehand.
  • After upgrading, spot-check routes, request logs, Playground and Simulator to confirm filters and navigation behave as expected in the new UI. See the v2.19.0 release notes for the full list.

From 2.17.0 apply 0034 and 0035 first. They support sticky binding user details and separate OAuth access tokens with request-log attribution. Apply schema changes even when OAuth will not yet be enabled.

Earlier upgrades also involve dual quota pools, model configuration and MCP. See the migration index for all transitions.

  • Verify existing protocols, model IDs, route groups and user keys.
  • Configure new features deliberately; catalog updates should not overwrite deployed prices or provider credentials.
  • Check accounting, quotas, failover and tool calls.
  • Review maintenance status after a database cutover, which may also copy the maintenance setting.

Historical notes keep their original version semantics. Use Updates for release changes and this guide to organize the upgrade.