Environment:BerriAI Litellm PostgreSQL Database

Knowledge Sources	BerriAI/litellm Prisma Schema
Domains	Infrastructure, Database
Last Updated	2026-02-15 16:00 GMT

Overview

PostgreSQL 16 database environment with Prisma ORM for the LiteLLM proxy server's persistent state (API keys, teams, spend logs, model configs).

Description

This environment provides the relational database backend required by the LiteLLM proxy server. The Prisma ORM manages schema migrations and provides both sync and async query interfaces. The database stores API keys, user/team/organization management data, spend logs, model configurations, guardrail settings, and cron job lease tracking. The schema includes 20+ tables supporting multi-tenant operations.

Usage

Use this environment when deploying the LiteLLM Proxy Server with persistent storage. Without a database, the proxy operates in a stateless mode without key management, spend tracking, or team-based access control. Required for any production proxy deployment.

System Requirements

Category	Requirement	Notes
Software	PostgreSQL >= 14	PostgreSQL 16 recommended (used in docker-compose.yml)
Disk	>= 10GB SSD	For spend logs and audit trails; grows with usage
Network	TCP port 5432 (default)	Or custom port in DATABASE_URL
Runtime	Node.js >= 18	Required by Prisma binary engine

Dependencies

System Packages

`postgresql` >= 14 (server)
`nodejs` >= 18 (for Prisma engine binary)

Python Packages

`prisma` == 0.11.0
`nodejs-wheel-binaries` == 24.12.0 (bundles Node.js for Prisma)
`litellm-proxy-extras` == 0.4.39 (migration scripts)

Credentials

`DATABASE_URL`: Full PostgreSQL connection string (e.g., `postgresql://user:pass@host:5432/litellm`). Supports `os.environ/` prefix syntax in YAML config.

Quick Install

# Install proxy with database support
pip install 'litellm[proxy,extra_proxy]'

# Start PostgreSQL locally (Docker)
docker run -d --name postgres -p 5432:5432 \
  -e POSTGRES_USER=llmproxy \
  -e POSTGRES_PASSWORD=dbpassword \
  -e POSTGRES_DB=litellm \
  postgres:16

# Set DATABASE_URL
export DATABASE_URL="postgresql://llmproxy:dbpassword@localhost:5432/litellm"

# Run migrations
prisma migrate deploy

Code Evidence

Prisma schema provider from `litellm/proxy/schema.prisma`:

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

generator client {
  provider             = "prisma-client-py"
  binaryTargets = ["native", "debian-openssl-1.1.x", "debian-openssl-3.0.x",
                   "linux-musl", "linux-musl-openssl-3.0.x"]
}

Migration execution from `litellm/proxy/prisma_migration.py:1-28`:

import subprocess
subprocess.run(["prisma", "migrate", "deploy"])

Docker Compose database service from `docker-compose.yml`:

db:
  image: postgres:16
  environment:
    POSTGRES_DB: litellm
    POSTGRES_USER: llmproxy
    POSTGRES_PASSWORD: dbpassword16
  healthcheck:
    test: ["CMD-SHELL", "pg_isready -d litellm -U llmproxy"]

Common Errors

Error Message	Cause	Solution
`prisma.errors.EngineConnectionError`	Database unreachable	Verify PostgreSQL is running and `DATABASE_URL` is correct
`Can't reach database server`	Network/firewall issue	Check network connectivity and PostgreSQL listen address
`P1001: Can't reach database`	Invalid DATABASE_URL	Ensure URL format is `postgresql://user:pass@host:port/db`
`Migration failed`	Schema conflict	Run `prisma migrate reset` (development only) or check migration history

Compatibility Notes

SQLite: While Prisma supports SQLite, LiteLLM proxy is designed for PostgreSQL. SQLite may work for testing but is not recommended for production.
Prisma Binary Targets: The schema declares targets for Debian (OpenSSL 1.1.x and 3.0.x) and Alpine Linux (musl). Other platforms may need additional binary targets.
Non-Root Docker: The hardened Dockerfile uses read-only filesystem with tmpfs mounts at `/app/cache` (128MB) and `/app/migrations` (64MB) for Prisma operations.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment