valv

Let agents query your database. Just not all of it.

valv gives an agent structured tools to read your database — and, opt-in, to write to it. The model emits a structured query (or insert/update/delete) — never a native database command — and valv validates it against your schema, scopes it to the current user with policies you write in code, compiles it for your database, and runs it.

The model's query is treated as fully untrusted. It can't read a column you hid, a row the user isn't allowed to see, call a function you didn't allow, write a column you didn't permit, or escape its tenant on a write. Valv rebuilds and checks the query on the server before it reaches the database adapter.

const valv = await createValv(client, { schema: "introspect", defaultPolicy: "deny-all" })

valv.policy("orders", (ctx) => ({
  read:   { tenant_id: ctx.tenant.id },   // every read is scoped to this tenant
  fields: { deny: ["internal_notes"] },   // this column never reaches the model
}))

const tools = await valv.tools.aisdk(ctx)  // hand to your agent — it queries safely

Two ways to use it

• In your app. Configure valv in code, write policies against your request context, and hand the tools to your agent — Vercel AI SDK, Anthropic, OpenAI, or Gemini. Or expose those same tools over MCP with @valv/mcp-sdk, scoped per request.
• With a coding agent. Point @valv/mcp at a database and a tool like Claude Code queries it safely — no code required.

Quick start

Install an adapter for your database (it pulls in @valv/core):

npm i @valv/clickhouse @clickhouse/client     # ClickHouse
# or
npm i @valv/prisma @prisma/client             # Postgres / MySQL / SQLite
# or
npm i @valv/mongodb mongodb                    # MongoDB

Wire it up — connect, write a policy, hand the tools to an agent:

import { createValv } from "@valv/clickhouse"
import { generateText, stepCountIs } from "ai"

// 1. Connect — introspect the live schema (or pass a hand-defined one).
const valv = await createValv(client, { schema: "introspect", defaultPolicy: "deny-all" })

// 2. Policy — what this caller may read, resolved from your context.
valv.policy("orders", (ctx) => ({ read: { tenant_id: ctx.tenant.id } }))

// 3. Tools — bound to the request's context, formatted for your provider.
const ctx = { user: { id: "u1", role: "analyst" }, tenant: { id: "acme" } }
const { text } = await generateText({
  model,
  system: await valv.instructions(ctx),  // how to drive the tools + the caller's resources
  tools: await valv.tools.aisdk(ctx),
  stopWhen: stepCountIs(6),
  prompt: "What's our revenue per order status this month?",
})

The agent gets four tools — list_resources, search_resources, describe_resource, and query — discovers your schema, and runs a query. valv scopes it to acme, compiles it to ClickHouse SQL, runs it, and hands back rows.

What the agent can express

One query tool covers the whole read surface. The grammar is Prisma-idiomatic — a shape models already know cold — and desugars server-side into a checked query:

{
  "from": "orders",
  "select": {
    "status": true,                       // a plain column
    "orders": { "count": true },          // count(*) — the key names the output
    "revenue": { "sum": "total" }         // an aggregate
  },
  "where": { "created_at": { "gte": "2026-06-01" } },
  "groupBy": ["status"],
  "orderBy": { "revenue": "desc" },
  "take": 10
}

That's enough for real analytics — filters ({ field: value } equality, operator objects like { gte, lt, in, contains }, and AND/OR/NOT trees), aggregates, time-series (bucket with a function and group by the alias), top-N (order by an aggregate), and conditional aggregation (countIf, sumIf). ClickHouse adds dialect functions like quantileTiming and toStartOfInterval; every function is type-checked and its literals parameterized.

Joins

To read a related resource, reference its column with a dotted path from the root. The model can only follow relations declared in your schema; valv derives the joins, picks the keys, and composes the policy of every table it touches — each joined table is scoped by its own policy and field allowlist, so a join can never reach a hidden column or another tenant's rows.

{
  "from": "orders",
  "select": {
    "customer_name": { "col": "customer.name" },        // one hop: orders → customer
    "region": { "col": "customer.region.name" },        // multi-hop: → customer → region
    "revenue": { "sum": "total" }
  },
  "groupBy": ["customer.name"]
}

belongsTo and hasMany relations are supported; join depth, table count, and fan-out are capped, and every query runs under a statement timeout. Relations are auto-introspected on Prisma and declared in the schema on ClickHouse.

Usage

Connect

createValv is async — it loads the schema on construction, so the instance is ready to use. Call it once at startup.

// ClickHouse — introspect, or hand-define a schema
const valv = await createValv(clickhouseClient, { schema: "introspect", database: "analytics" })

// Prisma (Postgres / MySQL / SQLite / Cockroach) — schema comes from your .prisma file
import { createValv } from "@valv/prisma"
const valv = await createValv(prismaClient)

// MongoDB — merge collection validators with sampled document fields
import { createValv } from "@valv/mongodb"
const valv = await createValv(mongoClient.db("analytics"), { schema: "introspect" })

defaultPolicy: "deny-all" (recommended) makes a resource invisible until you write a policy for it.

Policy

A policy is a function of your context. It decides what the caller may read, per resource:

valv.policy("orders", (ctx) => ({
  read:   { tenant_id: ctx.tenant.id },   // row filter — AND-injected into every query
  fields: { deny: ["internal_notes"] },   // hide columns
}))

valv.policy("users", (ctx) => ({
  read:   { tenant_id: ctx.tenant.id },
  fields: ctx.user.role === "support" ? { deny: ["email"] } : undefined,
}))

The model can't widen or override the row filter. Valv injects it after parsing the model's query and before handing the query to the database adapter. Fields are denied two ways: fields.deny (a blacklist) or fields.allow (a whitelist). Denied and unknown columns fail with the same message, so the model can't probe for hidden columns. Use "*" as the resource name for a default policy.

The same policy object carries the write axes — create, update, delete (and write as a shorthand for create+update) — which default to denied. See Writes.

Tools

valv.tools.<format>(ctx, options) returns provider-ready tools, bound to that context. Discovery is policy-filtered — list/search/describe only surface what the caller may read.

valv.tools.anthropic(ctx)                              // Anthropic Messages API
valv.tools.openai(ctx)                                 // OpenAI / compatible
valv.tools.gemini(ctx)                                 // Google Gemini
await valv.tools.aisdk(ctx)                            // Vercel AI SDK (async; needs `ai`)
valv.tools.neutral(ctx)                                // raw, framework-agnostic

valv.tools.anthropic(ctx, { list: false, search: false })  // drop discovery tools individually

The aisdk format returns self-executing tools (the SDK runs them). The provider formats (anthropic/openai/gemini) return tool definitions for the API request; you dispatch a tool call with runTool:

const result = await valv.runTool(call.name, call.input, ctx)

The discovery tools (list/search/describe) are on by default; the write tools (create/update/delete) are off by default — turn them on per call:

valv.tools.aisdk(ctx, { search: false, create: true, update: true })

System prompt

await valv.instructions(ctx) returns a drop-in system-prompt block: how to drive the tools (discover → describe → query, filters are scoped server-side) plus the resources this caller may read — so the model can skip the opening list_resources round-trip. Put it in your system prompt alongside the tools. The static text is also exported as AGENT_INSTRUCTIONS if you'd rather compose the resource list yourself.

const system = await valv.instructions(ctx)

You answer questions by querying a set of resources through the provided tools. Access is
enforced server-side: every query is scoped to what the current caller may read, so you never
need to add tenant/owner/permission filters yourself — a query returns only permitted rows.