Client API
Query and mutate data with full type safety — all operations inferred from your schema, no code generation required
Creating a Client
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 and the driver guides for operation and provider limits.
Queries
| Operation | Description | Returns |
|---|---|---|
findMany |
Find multiple records | T[] |
findFirst |
Find first matching record | T | null |
findUnique |
Find by unique identifier | T | null |
exist |
Check if any record matches | boolean |
count |
Count records | number |
aggregate |
Compute min/max/sum/avg/count | { _count, _avg, ... } |
groupBy |
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 |
Create a record, with relations | T |
createMany |
Create multiple records | { count }, or T[] with select |
update |
Update a record | T |
updateMany |
Update every match | { count }, or T[] with select |
upsert |
Create or update | T |
delete |
Delete a record | T |
deleteMany |
Delete every match | { count }, or T[] with select |
| 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
// 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:
// ✅ 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
Derive a nested DB type, validate inputs, and export JSON Schema
Client Extensions
Compose request, query, statement, observation, client, and model capabilities
Omitting Fields
Model exclusions, defaultOmit, and per-query projection
Transactions
Atomic operations with transactions and batching
Compatibility
Supported operations and intentional Prisma differences
Filtering
Filter operators by scalar type
Relation Filters
Query and filter on relations
Selecting
Select and include fields
Sorting
Order results
Pagination
Offset and cursor pagination