Prisma Schema Reference

Auto-documented from prisma/schema.prisma — All 20 models with their fields, types, relations, constraints, and indexes. Grouped by domain.

Table of Contents

• Schema Overview

• Entity Relationship Diagram

• Auth Domain

  • User
  • Session
  • Account
  • Verification
  • ApiKey
  • TwoFactor

• Content Domain

  • FilterSource
  • FilterListVersion
  • CompiledOutput
  • CompilationEvent

• Health Monitoring Domain

  • SourceHealthSnapshot
  • SourceChangeEvent

• Agent Sessions Domain

  • AgentSession
  • AgentInvocation
  • AgentAuditLog

• Deployment Domain

  • DeploymentHistory
  • DeploymentCounter

• Legacy / Compatibility Domain

  • StorageEntry
  • FilterCache
  • CompilationMetadata

• Generator & Datasource Configuration

• Naming Conventions

Schema Overview

Model Ownership

Entity Relationship Diagram

Auth Domain

User

The central identity model. Used by Better Auth for session-based authentication and by Clerk webhooks for user sync (deprecated).

Table name: users Relations: apiKeys → ApiKey[], sessions → Session[], accounts → Account[], twoFactor → TwoFactor?, agentSessions → AgentSession[] Unique constraints: email, clerkUserId

Note: The Clerk-specific fields (clerkUserId, firstName, lastName, imageUrl, lastSignInAt) will be removed after the Clerk → Better Auth migration completes. Better Auth uses displayName and reads tier/role directly from the database.

Session

Tracks active user sessions. Created by Better Auth on sign-in.

Table name: sessions Relations: user → User (via userId, cascade delete) Indexes: userId Unique constraints: token, tokenHash

Note: tokenHash is nullable — Better Auth sessions use token directly. The tokenHash column exists for backward compatibility with Clerk sessions and will be removed after migration.

Account

OAuth / credential accounts linked to a user. Managed by Better Auth.

Table name: account Relations: user → User (via userId, cascade delete)

Verification

Email verification and password reset tokens. Managed by Better Auth.

Table name: verification

ApiKey

API keys for programmatic access. Managed by the auth middleware — not by Better Auth.

Table name: api_keys Relations: user → User (via userId, cascade delete) Indexes: userId Unique constraints: keyHash

TwoFactor

Stores TOTP secrets and backup codes per user. Managed by the Better Auth twoFactor plugin.

Table name: two_factor Relations: user → User (via userId, cascade delete) Unique constraints: userId

Content Domain

FilterSource

Represents a remote filter list URL (e.g., EasyList). The system periodically fetches these sources and stores versioned snapshots.

Table name: filter_sources Relations: versions → FilterListVersion[], healthSnapshots → SourceHealthSnapshot[], changeEvents → SourceChangeEvent[] Indexes: status Unique constraints: url

FilterListVersion

A point-in-time snapshot of a filter source's content. The actual content is stored in R2 (referenced by r2Key); the database stores metadata and the content hash.

Table name: filter_list_versions Relations: source → FilterSource (via sourceId, cascade delete) Indexes: (sourceId, isCurrent), contentHash

CREATE UNIQUE INDEX idx_filter_list_versions_current
    ON filter_list_versions(source_id) WHERE is_current = true;

CompiledOutput

A compiled filter list output. Contains the compilation configuration snapshot and points to the compiled content in R2.

Table name: compiled_outputs Relations: events → CompilationEvent[] Indexes: configName, createdAt DESC, ownerUserId Unique constraints: configHash

CompilationEvent

Append-only telemetry for compilation requests. Used for analytics, billing, and debugging.

Table name: compilation_events Relations: compiledOutput → CompiledOutput? (via compiledOutputId, set null on delete) Indexes: createdAt DESC, userId

Health Monitoring Domain

SourceHealthSnapshot

Periodic health snapshots for filter sources. Used by the source health dashboard.

Table name: source_health_snapshots Relations: source → FilterSource (via sourceId, cascade delete) Indexes: sourceId, recordedAt DESC

SourceChangeEvent

Records when a filter source's content changes between versions.

Table name: source_change_events Relations: source → FilterSource (via sourceId, cascade delete) Indexes: sourceId, detectedAt DESC

Agent Sessions Domain

AgentSession

Tracks active and historical Cloudflare Agents connections over WebSocket or SSE.

Table name: agent_sessions Relations: user → User? (via userId, set null on delete), invocations → AgentInvocation[] Indexes: userId, clerkUserId, agentSlug, startedAt, (userId, endedAt) (active sessions per user)

AgentInvocation

Tracks individual tool calls / actions within an agent session.

Table name: agent_invocations Relations: session → AgentSession (via sessionId, cascade delete) Indexes: sessionId, toolName, invokedAt

AgentAuditLog

Append-only audit log for agent-related security events (ZTA telemetry).

Table name: agent_audit_logs Indexes: actorUserId, agentSlug, action, createdAt

Append-only: Never update or delete rows from this table. It feeds ZTA security dashboards and SIEM pipelines via AnalyticsService.trackSecurityEvent().

Deployment Domain

DeploymentHistory

Tracks worker deployments. Migrated from the legacy D1 deployment_history table.

Table name: deployment_history Unique constraints: fullVersion, (version, buildNumber) Indexes: version, buildNumber, deployedAt DESC, status, gitCommit

DeploymentCounter

Tracks the last build number per version to support monotonically incrementing builds.

Table name: deployment_counter

Legacy / Compatibility Domain

⚠️ These models are retained for backward compatibility with the HyperdriveStorageAdapter and D1StorageAdapter. New code should use the Content domain models (CompiledOutput, CompilationEvent, etc.) instead.

StorageEntry

Generic key-value storage. Used by IStorageAdapter.set() / .get().

Table name: storage_entries Indexes: key, expiresAt ID strategy: cuid() (not UUID — legacy)

FilterCache

Cached filter list content. Used by IStorageAdapter.cacheFilterList().

Table name: filter_cache Indexes: source, expiresAt ID strategy: cuid() (not UUID — legacy)

CompilationMetadata

Legacy compilation metadata. Used by IStorageAdapter.storeCompilationMetadata().

Table name: compilation_metadata Indexes: configName, timestamp ID strategy: cuid() (not UUID — legacy)

TODO (Phase 2): Migrate callers to use CompiledOutput + CompilationEvent instead. See the comment in prisma/schema.prisma.

Generator & Datasource Configuration

generator client {
  provider = "prisma-client"
  output   = "./generated"
  runtime  = "cloudflare"
  // "cloudflare" runtime uses @prisma/adapter-pg code path — no runtime WASM.
  // Required for Cloudflare Workers which block WebAssembly.Module() at runtime.
}

datasource db {
  provider = "postgresql"
  // Connection URL is configured in prisma.config.ts (Prisma 7+)
}

⚠️ Always use deno task db:generate instead of npx prisma generate to ensure the import fixer runs.

Naming Conventions

PostgreSQL-Specific Types

Further Reading

• Neon Setup — Production database configuration
• Database Architecture — Design decisions and trade-offs
• Prisma + Deno Compatibility — Deno-specific setup
• Local Dev Guide — Docker PostgreSQL for development
• Prisma Schema Documentation