@vistal/prisma

@vistal/prisma

Row-level security and access control for AI agents — Prisma adapter.

Reads your Prisma schema, generates typed LLM tools, and enforces row-level security and field-level access control server-side on every query — in code, not prompts.

Installation

npm install @vistal/prisma @vistal/core
npm install --save-dev prisma

Requires Prisma 5+ and @prisma/client as peer dependencies.

Setup

import { PrismaClient } from "@prisma/client"
import { createVistal } from "@vistal/prisma"

const prisma = new PrismaClient()

const vistal = createVistal(prisma, { defaultPolicy: "deny-all" })

createVistal infers resource names from your Prisma client type — policy keys are type-checked, so a typo is a compile error. Prisma model names are converted to snake_case resource names (OrderItem → order_item).

If your schema isn't at ./prisma/schema.prisma, pass schemaPath:

const vistal = createVistal(prisma, {
  defaultPolicy: "deny-all",
  schemaPath: "./db/schema.prisma",
})

Schema annotations

Use /// doc comments to give the LLM better context and mark fields that should never leave the server:

/// @vistal:description "A customer purchase order"
model Order {
  id        String      @id @default(uuid())
  tenant_id String
  status    OrderStatus
  total     Decimal

  /// @vistal:description "Order total in cents"
  total     Decimal

  /// @vistal:sensitive
  internal_notes String?
}

Annotation	Effect
@vistal:description "..."	Added to the tool description so the LLM understands the resource or field
@vistal:sensitive	Field is stripped at introspection — never appears in tool schemas, arguments, or results

@vistal:sensitive is enforced before policy runs. The field doesn't exist as far as the LLM is concerned.

Policies

vistal.policy("order", (ctx) => ({
  read:   { tenant_id: ctx.tenant.id },   // row filter — AND-ed into every read
  write:  { tenant_id: ctx.tenant.id },   // force-injected on INSERT, AND-ed into UPDATE WHERE
  delete: false,                           // delete_order tool never generated
  fields:    { deny: ctx.user.role === "support" ? ["internal_notes"] : [] },
  relations: { items: true, customer: ctx.user.role === "admin" },
}))

// Wildcard fallback for resources without an explicit policy()
vistal.policy("*", (ctx) => ({
  read:   { tenant_id: ctx.tenant.id },
  write:  false,
  delete: false,
}))

read, write, and delete accept:

Value	Meaning
true	allow
false	deny — no tool generated for this operation
{ field: value }	row filter (read/delete) or force-injected field (write)

Connecting to your LLM provider

// Vercel AI SDK (requires the `ai` package)
const tools = await vistal.tools.vercel(ctx)
const { text } = await generateText({ model, tools, maxSteps: 8, prompt })

// Anthropic
const tools = await vistal.tools.anthropic(ctx)
await anthropic.messages.create({ tools: tools.map(t => t.definition) })
const result = await tools.find(t => t.name === block.name)!.execute(block.input)

// OpenAI
const tools = await vistal.tools.openai(ctx)

// Gemini
const tools = await vistal.tools.gemini(ctx)

How Prisma model names map to resource names

Prisma model names (PascalCase) are converted to snake_case resource names:

Prisma model	vistal resource
Order	order
OrderItem	order_item
UserProfile	user_profile

These are the strings you pass to policy() and that appear in generated tool names (query_order_item, create_order_item, …).

Security properties

Property	How Prisma enforces it
Row filters on read	where clause passed to findMany / findFirst
Write scoping	write: { tenant_id } is injected into create data and AND-ed into updateMany / deleteMany WHERE — cross-tenant records won't match
update / delete use Many	Ensures the full policy where (id + forced filter) is applied — a mismatched tenant gets { count: 0 }, not an error that leaks existence
belongsTo relation filters	Enforced post-fetch in memory (Prisma doesn't support where on to-one includes)
Sensitive fields	Stripped at introspection via @vistal:sensitive — never passed to Prisma in select, data, or returned in results

Live views with LISTEN/NOTIFY

Live views poll by default. On Postgres you can replace polling with native change notifications (requires the optional peer dependency pg):

import { createVistal, installLiveTriggers } from "@vistal/prisma"

// Once per database — e.g. in a migration step. Table names are the actual
// Postgres table names (the Prisma model name unless @@map is used).
await installLiveTriggers(prisma, ["Order", "User"])

const vistal = createVistal(prisma, {
  live: {
    connectionString: process.env.DATABASE_URL!,
    channel: "vistal_changes",   // default
    debounceMs: 250,             // coalesce notification bursts (default)
    onError: (e) => logger.warn("live updates unavailable", e),
  },
})

How it works: statement-level triggers pg_notify the table name only on one channel; a single dedicated pg connection LISTENs and routes notifications to the views watching that table (including tables of eager-loaded relations). On a notification the view re-executes through the full policy pipeline — notifications never carry data, so they can never bypass policy. The LISTEN connection starts lazily with the first subscription and closes with the last. If the connection can't be established (e.g. pg missing), onError fires and affected views go stale — monitor it, or omit live to stay on polling.

liveTriggersSQL(tables, channel?) returns the raw SQL if you prefer to manage triggers in your own migrations.

Exports

Export	Purpose
createVistal(prisma, config?)	Main entry point — creates a Vistal instance with the Prisma adapter wired up and resource types inferred
PrismaAdapter	The adapter class if you need to instantiate it separately
translateFilter	Converts a vistal FilterNode to a Prisma where object — useful when building a custom adapter on top of Prisma
installLiveTriggers / liveTriggersSQL	Install (or emit) the LISTEN/NOTIFY triggers for live views
PgNotifyListener	The LISTEN connection manager, if you need to wire it manually

Other adapters

For ClickHouse, use @vistal/clickhouse instead — same policy API, no relations, schema annotations via column COMMENTs.

License

MIT