{"record":{"id":"f9a404b4e2d6ce7f","repo":"BerriAI/litellm","slug":"database-not-connected-connect-a-database-to-your","errorCode":null,"errorMessage":"Database not connected. Connect a database to your proxy - https://docs.litellm.ai/docs/simple_proxy#managing-auth---virtual-keys","messagePattern":"Database not connected\\. Connect a database to your proxy - https://docs\\.litellm\\.ai/docs/simple_proxy#managing-auth---virtual-keys","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"litellm/integrations/cloudzero/database.py","lineNumber":35,"sourceCode":"# CHANGELOG: 2025-01-19 - Initial database module for LiteLLM data extraction (erik.peterson)\n\n\"\"\"Database connection and data extraction for LiteLLM.\"\"\"\n\nfrom datetime import datetime\nfrom typing import Any, Final\n\nimport polars as pl\n\n\nclass LiteLLMDatabase:\n    \"\"\"Handle LiteLLM PostgreSQL database connections and queries.\"\"\"\n\n    def _ensure_prisma_client(self):\n        from litellm.proxy.proxy_server import prisma_client\n\n        \"\"\"Ensure prisma client is available.\"\"\"\n        if prisma_client is None:\n            raise Exception(\n                \"Database not connected. Connect a database to your proxy - https://docs.litellm.ai/docs/simple_proxy#managing-auth---virtual-keys\"\n            )\n        return prisma_client\n\n    async def get_usage_data(\n        self,\n        limit: int | None = None,\n        start_time_utc: datetime | None = None,\n        end_time_utc: datetime | None = None,\n    ) -> pl.DataFrame:\n        \"\"\"Retrieve usage data from LiteLLM daily user spend table.\"\"\"\n        client: Final = self._ensure_prisma_client()\n\n        # Query to get user spend data with team information. Use parameter binding to\n        # avoid SQL injection from user-supplied timestamps or limits.\n        query = \"\"\"\n        SELECT\n            dus.id,","sourceCodeStart":17,"sourceCodeEnd":53,"githubUrl":"https://github.com/BerriAI/litellm/blob/6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d/litellm/integrations/cloudzero/database.py#L17-L53","documentation":"Exception raised by LiteLLMDatabase._ensure_prisma_client when the proxy's global prisma_client is None — i.e. DATABASE_URL/database config was not provided, so the proxy is running without a Postgres database. The CloudZero export needs the spend analytics tables (daily user spend), which only exist when LiteLLM's database is connected and populated.","triggerScenarios":"Running the LiteLLM proxy with no database (config.yaml lacks database: url / DATABASE_URL unset) while the cloudzero export job or another consumer of LiteLLMDatabase tries to query usage data; or checking the endpoint before proxy startup completed the Prisma connection.","commonSituations":"Trying CloudZero cost exports on a lightweight local proxy setup that stores spend in a JSON file instead of Postgres; misconfigured DATABASE_URL in Kubernetes so the proxy silently started in no-DB mode.","solutions":["Connect a Postgres database: set DATABASE_URL (or database.url in config.yaml) and restart the proxy so prisma_client initializes","Verify the proxy logs show successful Prisma connection at startup","Ensure the proxy has run long enough for spend rows to accumulate before exporting","If you intentionally run without a database, disable the CloudZero export schedule"],"exampleFix":"# before\n# config.yaml with cloudzero export but no database\nlitellm_settings:\n  callbacks: [cloudzero]\n\n# after\nlitellm_settings:\n  callbacks: [cloudzero]\ndatabase_url: os.environ/DATABASE_URL  # Postgres backing the spend tables","handlingStrategy":"validation","validationCode":"def database_connected() -> bool:\n    from litellm.proxy.proxy_server import prisma_client\n    return prisma_client is not None\n\nif not database_connected():\n    raise RuntimeError(\"CloudZero export requires a connected Postgres database (set DATABASE_URL)\")","typeGuard":"def has_prisma_client() -> bool:\n    \"\"\"True when the proxy initialized its Prisma connection.\"\"\"\n    from litellm.proxy.proxy_server import prisma_client\n    return prisma_client is not None","tryCatchPattern":"try:\n    df = await db.get_usage_data(limit=1000)\nexcept Exception as e:\n    if \"Database not connected\" in str(e):\n        skip_export_until_db_configured()\n    else:\n        raise","preventionTips":["Run CloudZero exports only on proxies with DATABASE_URL configured","Add a readiness check that asserts prisma_client is not None before scheduling exports","Verify Prisma connects at startup from proxy logs"],"tags":["cloudzero","database","prisma","postgres"],"backgroundTag":null,"analyzedSha":"6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d","analyzedAt":"2026-08-15T07:12:03.035Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}