Prisma

Status: Active
Last Updated: 2026-08-26
Category: Databases / ORM
Prerequisites: prisma.md (research), prisma-connections.md
Tags: prisma, database, pooling, data-proxy, migrations

Summary

Prisma splits guidance between raw connection settings (Prisma Client), migrations, and connection pooling / Data Proxy layers for high-concurrency workloads. For agentic workloads, pooling and separate credentials are essential.

Context / Why This Matters

Every agent session that touches the database should share the same environment (DATABASE_URL), migration scripts, and secret pipeline. Without pooling, long-running agent workloads exhaust connections; without separate read/write credentials, security boundaries collapse.

Implementation / Core Content

Connection Basics

• Store DATABASE_URL or PRISMA_ANY inside Dotenvx (.env / .env.production).
• connectTimeout and poolTimeout are configured in the datasource block of schema.prisma.
• Migration scripts (prisma migrate) must run inside the same environment agents use so they share credentials and drift detection.

Pooling Strategies

• Long-running (agentic) workloads should use either the Data Proxy or an external pooler (PgBouncer, Neon) to avoid connection exhaustion.
• Data Proxy enforces connection reuse automatically and hides the connection string, reducing credential sprawl.
• Monitor query latency, pool saturation, and retries via Prisma’s logging/tracing; agents can correlate incidents with specific workloads before escalation.

Security & Instrumentation

• Split read-only and write credentials inside Dotenvx; rotate through Forgejo Actions that update encrypted .env.production and log audit events.
• Prisma CLI still needs API keys stored inside Dotenvx or a vault.
• Monitor pool saturation telemetry to detect connection exhaustion before it impacts agent tasks.

Practical Examples

// schema.prisma
// Configure datasource for pooling
datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
  directUrl = env("DIRECT_URL") // for migrations / pooling
}

# Migration in agent environment (same secrets)
dotenvx run --env-file=.env.production -- npx prisma migrate deploy

# Monitor pool status
# (use Prisma logging + external telemetry to surface saturation events)

Common Pitfalls & Troubleshooting

Pitfall	Fix
Connection exhaustion in agent loops	Use Data Proxy or PgBouncer; set poolTimeout appropriately
Migrations fail due to missing env	Ensure .env / .env.production is loaded in CI and locally
Read/write boundary crossed accidentally	Split credentials; enforce read-only roles for query agents
Pool saturation not visible	Add Prisma logging metrics and surface in telemetry dashboard

Next Steps / Ops Actions

1. Document credential split and rotation cadence in databases/prisma-connections.md.
2. Link pool saturation telemetry to the GitOps issue log for quick forensics.
3. Keep Dotenvx instructions updated so migrations share the same secret pipeline.

Sources & Related Articles

• Prisma connection management docs.
• Prisma connection pooling overview (Data Proxy, PgBouncer).
• Prisma migrations guide.
• Related KB: databases/prisma.md, prisma-connections.md

Change Log

2026-08-26

• Expanded from 2.2KB research log to production-quality article with format, examples, pitfalls, and operational links.