> ## Documentation Index
> Fetch the complete documentation index at: https://docs.litigationlabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Langfuse & Neon Setup

> Guide for setting up Langfuse with a Neon PostgreSQL database for observability and tracing.

## Overview

Langfuse uses **PostgreSQL for transactional data** and only uses the **`public` schema**. To keep Langfuse separate from the app's Payload data, use a **dedicated database** in the same Neon project.

## Option 1: New Database (Recommended)

Create a second database in your Neon project (e.g. `langfuse`). Langfuse will use that database and its `public` schema.

### 1. Create the Database

**Neon Console (easiest)**

1. Open [Neon Console](https://console.neon.tech/) and select your project.
2. Go to **Branches** -> select your branch -> **Databases**.
3. Click **Create** and name it `langfuse`.

**SQL Editor**

```sql theme={null}
CREATE DATABASE langfuse;
```

**CLI**

```bash theme={null}
neon databases create --name langfuse
```

### 2. Connection String

Use the same host and credentials as your existing Neon URL, and only change the database name:

* Current (app): `postgresql://USER:PASSWORD@ep-XXX-pooler.REGION.aws.neon.tech/neondb?sslmode=require`
* Langfuse: `postgresql://USER:PASSWORD@ep-XXX-pooler.REGION.aws.neon.tech/langfuse?sslmode=require`

### 3. Environment Variables

When self-hosting Langfuse, set:

* `DATABASE_URL` -- Connection string above (pooled URL is fine).
* `DIRECT_URL` -- Same URL or a direct (non-pooled) URL for migrations.

### 4. Use from this Repo (`.env.local`)

This project keeps Langfuse URLs in `.env.local`:

* **`LANGFUSE_DATABASE_URL`** -- Pooled URL (use as `DATABASE_URL` in Langfuse)
* **`LANGFUSE_DIRECT_URL`** -- Direct/unpooled URL (use as `DIRECT_URL` for migrations)

```bash theme={null}
DATABASE_URL=$LANGFUSE_DATABASE_URL
DIRECT_URL=$LANGFUSE_DIRECT_URL
```

### 5. Optional: Script

```bash theme={null}
pnpm tsx scripts/create-langfuse-database.ts
```

## Option 2: Same Database (`neondb`)

You can run Langfuse against your existing `neondb` database. Langfuse will use the `public` schema. Your app uses `PAYLOAD_DB_SCHEMA=payloadcms`, so tables won't conflict.

* **Pros:** One database, no new DB to create.
* **Cons:** Langfuse and app share the same DB; backups and scaling are shared.

## Summary

| Approach                 | Where Langfuse Lives          | What You Do                                             |
| ------------------------ | ----------------------------- | ------------------------------------------------------- |
| **New DB (recommended)** | New DB `langfuse` -> `public` | Create DB in Neon, set `DATABASE_URL` with `/langfuse`. |
| **Same DB**              | Existing `neondb` -> `public` | Set Langfuse `DATABASE_URL` to your current Neon URL.   |