Database Schema and Migrations
Relevant source files
The following files were used as context for generating this wiki page:
LiteLLM utilizes a database-backed architecture to manage persistence for the proxy server, including configurations, API keys, teams, and advanced features like Skills storage. The system relies on the Prisma ORM to provide a unified interface across supported databases, primarily PostgreSQL and SQLite.
The migration system is designed to handle schema updates across multiple environments while ensuring consistency between the core library and the specialized litellm-proxy-extras package. This setup allows LiteLLM to support complex features such as local skills storage, enabling tool-calling and system prompt injection across diverse LLM providers.
Sources: GEMINI.md, litellm/llms/litellm_proxy/skills/README.md
Core Database Architecture
The database layer is managed through Prisma, which provides type-safe access and handles the translation between high-level models and the underlying SQL. The system is architected to run migrations automatically during the proxy server boot process.
The diagram above illustrates the automated migration flow during the proxy server initialization.
Sources: AGENTS.md, docker/README.md
Supported Database Providers
LiteLLM is tested and compatible with multiple database backends:
- PostgreSQL: The recommended choice for production environments and high-concurrency scenarios.
- SQLite: Often used for local testing or lightweight deployments.
- Neon: An embedded or default cloud option utilized in certain package configurations.
Sources: GEMINI.md, docker/README.md
Schema Management and Synchronization
A critical requirement for LiteLLM development is maintaining synchronization between different copies of the schema.prisma file across the repository.
Critical Schema Locations
| File Path | Purpose |
|---|---|
schema.prisma (root) | The source of truth for the entire project. |
litellm/proxy/schema.prisma | Specifically used by the proxy server. |
litellm-proxy-extras/litellm_proxy_extras/schema.prisma | Used for generating migrations in the extras package. |
The synchronization process involves using diff to ensure all files match before any migration generation begins.
Sources: litellm-proxy-extras/migration_runbook.md:7-13
Migration Workflow
Migrations in LiteLLM are managed using Prisma's migration engine. For engineers, a specific "Runbook" defines the steps to create and apply schema changes.
The flowchart describes the engineering workflow for generating new database migrations.
Sources: litellm-proxy-extras/migration_runbook.md:43-48
Generating Migrations
To generate a new migration, developers typically use the run_migration.py script provided in the CI/CD directory. This process requires a local PostgreSQL installation (version 14 is recommended).
# Example migration generation command
python ci_cd/run_migration.py "your_migration_name"
Sources: litellm-proxy-extras/migration_runbook.md:31-40
Specialized Data Models: LiteLLM Skills
One of the prominent uses of the database is the LiteLLM_SkillsTable. This enables skills to be stored locally and used with non-Anthropic providers via tool conversion and system prompt injection.
Skill Table Schema Details
| Field | Type | Description |
|---|---|---|
skill_id | String | Primary Key (UUID) |
display_title | String | Human-readable title of the skill |
file_content | Bytes | Binary content of the skill ZIP file |
instructions | String | Guidelines for LLM usage |
created_at | DateTime | Timestamp of creation |
Sources: litellm/llms/litellm_proxy/skills/README.md
Containerized Migration Environment
In Docker environments, LiteLLM is hardened to support read-only filesystems. This requires Prisma engines and migrations to be "baked" into the image.
Hardened Docker Configuration
When running in restricted or offline environments:
- Prisma Engines: Baked into the image at
/app/cache. - Migration Workspace: Directed to a writable tmpfs mount at
/app/migrationsvia theLITELLM_MIGRATION_DIRenvironment variable. - Offline Verification: Verified by running Prisma commands with
--network none.
Sources: docker/README.md
Summary
The Database Schema and Migration system in LiteLLM is a robust framework centered around Prisma. It ensures that schema changes are synchronized across multiple repository locations, automated during deployment, and hardened for secure containerized environments. By maintaining a strict "source of truth" in the root schema.prisma, LiteLLM provides a consistent state across its proxy, extras, and SDK components.