---
title: Client API
description: Query and mutate data with full type safety — all operations inferred from your schema, no code generation required
icon: terminal
---

## Creating a Client

```ts
import { createClient } from "viborm/pg";
import { user, post } from "./schema";

export const createDatabase = () => createClient({
  schema: { user, post },
  databaseUrl: process.env.DATABASE_URL,
});

export const client = createDatabase();
```

For a package that defines cyclic models, the supported declaration pattern is
to construct the client in that package and export the inferred client or
factory, as above. Consumers import that export without annotating relation
getters or client results. Rebuilding a client downstream from separately
emitted raw models or a raw schema can lose cyclic relation types; that
declaration boundary remains lossy.

### Declaration emit has a size limit

Emitting declarations (`declaration` or `composite`) for a package that
exports a client works for small schemas only. The emitted client type grows
with the schema, and TypeScript refuses to write it past a fixed length with
`TS7056: The inferred type of this node exceeds the maximum length the compiler
will serialize`. Measured on schemas of about 15 fields per model, with
relations to two hub models and a JSON field:

| Package exports | TypeScript 5.9 | TypeScript 7.0 |
|---|---|---|
| The client only | 20 models emit; 30 fail | 50 models emit; 70 fail |
| The models and the client | 8 models fail | 8 models emit; 12 fail |

Past the limit, do not emit declarations for the package that builds the
client: let its consumers type-check it from source, for example a workspace
package whose `exports` name its `.ts` files.

## Operations

The client uses a Prisma-inspired API. See [Compatibility](/docs/client/compatibility)
and the [driver guides](/docs/drivers) for operation and provider limits.

### Queries

| Operation | Description | Returns |
|-----------|-------------|---------|
| [`findMany`](/docs/client/find-many) | Find multiple records | `T[]` |
| [`findFirst`](/docs/client/find-first) | Find first matching record | `T \| null` |
| [`findUnique`](/docs/client/find-unique) | Find by unique identifier | `T \| null` |
| [`exist`](/docs/client/exist) | Check if any record matches | `boolean` |
| [`count`](/docs/client/count) | Count records | `number` |
| [`aggregate`](/docs/client/aggregate) | Compute min/max/sum/avg/count | `{ _count, _avg, ... }` |
| [`groupBy`](/docs/client/group-by) | Group records and aggregate per group | grouped rows |

`findFirstOrThrow` and `findUniqueOrThrow` throw `NotFoundError` instead of returning `null` — documented on their base operation's page.

### Mutations

| Operation | Description | Returns |
|-----------|-------------|---------|
| [`create`](/docs/client/create) | Create a record, with relations | `T` |
| [`createMany`](/docs/client/create-many) | Create multiple records | `{ count }`, or `T[]` with `select` |
| [`update`](/docs/client/update) | Update a record | `T` |
| [`updateMany`](/docs/client/update-many) | Update every match | `{ count }`, or `T[]` with `select` |
| [`upsert`](/docs/client/upsert) | Create or update | `T` |
| [`delete`](/docs/client/delete) | Delete a record | `T` |
| [`deleteMany`](/docs/client/delete-many) | Delete every match | `{ count }`, or `T[]` with `select` |
| [Nested writes](/docs/client/nested-writes) | Write related records in one call | — |

`createMany`, `updateMany`, and `deleteMany` return the affected rows instead of a count when the call carries a `select` — there are no separate `createManyAndReturn` / `updateManyAndReturn` methods, and `deleteMany` gains a returning form Prisma does not have. See each operation's page.

## Quick Examples

```ts
// Find many with filters
const users = await client.user.findMany({
  where: { role: "ADMIN" },
  orderBy: { createdAt: "desc" },
  take: 10,
});

// Find unique by ID
const user = await client.user.findUnique({
  where: { id: "user_123" },
});

// Create a record
const newUser = await client.user.create({
  data: {
    email: "alice@example.com",
    name: "Alice",
  },
});

// Update with relations
const updated = await client.user.update({
  where: { id: "user_123" },
  data: {
    name: "Alice Smith",
    posts: {
      create: { title: "New Post" },
    },
  },
  include: { posts: true },
});

// Count with filters
const count = await client.user.count({
  where: { role: "ADMIN" },
});
```

## Type Safety

Every operation is fully typed:

```ts
// ✅ TypeScript knows the exact return type
const user = await client.user.findUnique({
  where: { id: "user_123" },
  select: { id: true, email: true },
});
// Type: { id: string; email: string } | null

// ❌ TypeScript catches invalid fields
await client.user.create({
  data: {
    email: "bob@example.com",
    invalidField: "value",  // Error!
  },
});

// ❌ TypeScript catches missing required fields
await client.user.create({
  data: {
    name: "Bob",
    // Error: 'email' is required
  },
});
```

## Sections

**[Types and JSON Schema](/docs/client/types-and-json-schema)**

Derive a nested DB type, validate inputs, and export JSON Schema

**[Client Extensions](/docs/extensions)**

Compose request, query, statement, observation, client, and model capabilities

**[Omitting Fields](/docs/client/omit)**

Model exclusions, defaultOmit, and per-query projection

**[Transactions](/docs/client/transactions)**

Atomic operations with transactions and batching

**[Compatibility](/docs/client/compatibility)**

Supported operations and intentional Prisma differences

**[Filtering](/docs/client/filtering)**

Filter operators by scalar type

**[Relation Filters](/docs/client/filtering/relations)**

Query and filter on relations

**[Selecting](/docs/client/selecting)**

Select and include fields

**[Sorting](/docs/client/sorting)**

Order results

**[Pagination](/docs/client/pagination)**

Offset and cursor pagination
