Environment:Langfuse Langfuse PostgreSQL 17

Knowledge Sources	Langfuse PostgreSQL 17
Domains	Infrastructure, Database
Last Updated	2026-02-14 06:00 GMT

Overview

PostgreSQL 17 primary database with Prisma 6.17.1 ORM and Kysely 0.27.4 query builder for relational data storage including users, organizations, projects, prompts, evaluations, and configuration.

Description

PostgreSQL serves as the primary relational database for Langfuse, storing all configuration, authentication, and metadata entities. Access is through Prisma ORM (for schema management and typed queries) extended with Kysely (for complex raw SQL generation). The database version is configurable via the POSTGRES_VERSION environment variable, defaulting to 17. Foreign key relationships may not be fully enforced in the schema to allow unordered ingestion of events.

Usage

Use this environment for all Langfuse deployments. PostgreSQL is mandatory for storing users, organizations, projects, prompts, evaluation configurations, API keys, and other relational data. It works alongside ClickHouse which handles high-volume analytics data.

System Requirements

Category	Requirement	Notes
Database	PostgreSQL 17	Configurable via `POSTGRES_VERSION` env var
Disk	10GB+ SSD	Size depends on number of projects and configurations
Network	TCP port 5432	Default PostgreSQL port

Dependencies

System Packages

postgresql = 17 (via Docker: postgres:17)
golang-migrate v4.19.1 (for additional migrations beyond Prisma)

Node.js Packages

@prisma/client = 6.17.1
prisma = 6.17.1 (CLI, globally installed in Docker)
kysely = 0.27.4
pg = 8.13.0 (PostgreSQL client driver)

Credentials

The following environment variables must be set:

DATABASE_URL: (Required) PostgreSQL connection string (e.g., postgresql://user:password@host:5432/dbname)
DIRECT_URL: Direct Prisma connection URL bypassing connection pooling (optional, web only)
SALT: (Required) Salt for API key hashing (used for bcrypt operations)
ENCRYPTION_KEY: 64 hex character AES-256-GCM encryption key for sensitive data (optional)

Quick Install

# Start PostgreSQL via Docker Compose
pnpm run infra:dev:up

# Run Prisma migrations
cd packages/shared
pnpm run db:migrate

# Seed with example data
pnpm run db:seed

# Reset database (development only)
pnpm run db:reset

Code Evidence

Docker Compose service definition from docker-compose.dev.yml:

postgres:
  image: postgres:${POSTGRES_VERSION:-17}
  restart: on-failure:3
  environment:
    - POSTGRES_USER=postgres
    - POSTGRES_PASSWORD=postgres
    - POSTGRES_DB=postgres
    - TZ=UTC
  ports:
    - 127.0.0.1:5432:5432

Prisma client initialization from packages/shared/src/db.ts:

import { PrismaClient } from "@prisma/client";
import { kyselyExtension } from "prisma-extension-kysely";

const prisma = new PrismaClient().$extends(kyselyExtension({ ... }));

Common Errors

Error Message	Cause	Solution
`P1001: Can't reach database server`	PostgreSQL not running	Run `pnpm run infra:dev:up`
`P2002: Unique constraint violation`	Duplicate key insert	Check for existing records before insert
`SALT is required`	Missing SALT env var	Set `SALT` in `.env` file

Compatibility Notes

Version: Default is PostgreSQL 17; configurable via POSTGRES_VERSION environment variable.
Timezone: Configured to UTC via TZ=UTC.
Connection Pooling: Use DATABASE_URL for pooled connections and DIRECT_URL for direct connections (useful for migrations).
Foreign Keys: Not fully enforced to support unordered event ingestion.

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment