Compatibility

What's supported, and how VibORM intentionally differs from Prisma

Compatibility

VibORM’s API is Prisma-inspired, but it is not a drop-in replacement. This page lists what’s supported, the operations that intentionally differ, and the handful of behaviors that vary by database.

Everything in the API works the same on every database unless noted under Database differences.

Operations

Unique selectors

findUnique, findUniqueOrThrow, update, delete and upsert take Prisma ≥ 4.5’s extended unique where: at least one unique discriminator (a unique scalar, or a complete compound constraint) plus any non-unique filters — scalar and relation — and AND / OR / NOT. Full semantics, per operation, are in Narrowing a Unique Lookup.

Nested update / upsert / delete targets take the extended where too — a superset of Prisma, which is unique-only in those three positions.

One deliberate divergence, and it covers only the LINK selectors:

Relation filters

Nested writes

Nested writes are supported inside create, update, and both branches of upsert. What you can nest depends on the context — you can’t update or delete a related record inside a create, because there’s nothing to update yet.

createMany, updateMany, and deleteMany apply to to-many relations only. For a to-one relation use create, update, and delete: true.

On a many-to-many relation, createMany inserts each row and links it to the parent. skipDuplicates there skips the child ROW’s insert — the join row is a different row and is still written, so a skipped item leaves the existing target untouched and links it. It is refused (typed, before any write) when the target’s primary key is database-generated: a skipped insert produces no identity for its join row. Supply the key, or drop skipDuplicates.

Shapes:

Behavior:

• A nested update or delete with a specific target throws if that record isn’t found (or belongs to another parent).
• A to-one update: { where, data } throws the same not-found error when the connected record fails the filter; the whole operation rolls back. The two spellings are told apart structurally — an object with a data key whose value is an object is the envelope. On a related model owning a field named data that shape means two different things (set the row’s fields, or store the document), so VibORM refuses it instead of picking one as Prisma does: spell the envelope out, update: { where: {}, data: { … } }.
• Nested updateMany and deleteMany may match zero rows without throwing.
• A nested upsert creates only when nothing matches where; if the match belongs to another parent, it’s rejected rather than stolen or duplicated.
• You can’t disconnect, empty-set, or otherwise orphan records on a required relation.
• createMany with skipDuplicates rejects a row containing only database-owned defaults before any parent or child write.

Planned superset — nested upsert under create: Prisma has no upsert in a create input, and the current engine rejects it. VibORM’s input surface accepts it as a deliberate superset with global-lookup, adopt-and-update semantics — the target is located by its own unique where, an existing row is adopted (reparented) and updated, and a missing row is created under the new parent. This completes the adopt family that connect/connectOrCreate already provide under create. It becomes executable only when the create tree routes to the query-engine-v2 path; until then it still rejects, so there is no mid-migration behavior change.

No engine depth limit — deep write subtrees at any depth (the depth lift, finished in X1b): a nested create under a located target (inside an update, or inside an upsert update branch) is a create SUBTREE that folds recursively to any depth, and a relation-carrying fresh child now runs the full create-root machinery at every level — for example post.update({ where, data: { author: { update: { posts: { create: { title, comments: { create: { body, … } } } } } } } }). Every fresh row becomes the parent of its own nested writes, and every mechanism the top-level create supports is available at any depth: a database-generated or compound primary key on a fresh child (its produced id threads to its own grandchildren), a parent-held to-one written before its fresh holder, the fresh-parent adopt family (connect / connectOrCreate / upsert), a createMany with skipDuplicates, and many-to-many through the junction. These execute natively, byte-identically on transaction and batch substrates. Semantic rules are unchanged at every depth: a create-then-connectOrCreate on the same key still rejects with “Split these operations into separate queries”, and validation still rejects unknown keys, wherever they appear in the tree.

The only depth ceiling is the TypeScript compiler’s, not the engine’s. Inferring a deeply-nested literal payload is a type-instantiation cost: a rich per-level literal (a children.create plus a parent-held create plus an M2M create at each level) type-checks to ~31 levels and then raises TS2321 “Excessive stack depth comparing types”. That is a DX limit on the client input inference, far past any hand-written payload; the runtime carries no depth counter and folds deeper. If you ever build a payload past that ceiling, construct it programmatically (a plain object, widened to the input type) so the compiler never infers the deep literal — the engine executes it unchanged (a 40-level chain is exercised in the test estate). One shape is still one level short at a located target and routes as a typed refusal (a distinct upcoming mechanism, the located-update projection of child-SET folding — not a depth limit): a deeper parent-held to-one, or a non-primary-key / compound reference, of an existing row being updated.

Database differences

The API is provider-agnostic. Remaining differences are limited to features whose underlying data model is not shared by every database:

Portable string mode: "insensitive" folds ASCII A-Z only on every database. Non-ASCII code points remain exact, so behavior does not depend on a database’s locale or ICU installation.

JSON filter paths use one portable grammar. Segments containing " or \ reject before SQL generation on every database; they never degrade to an empty result on one provider.

New MySQL 8 tables use the binary, no-pad utf8mb4_0900_bin collation so string keys preserve case, accents, and trailing spaces like PostgreSQL and SQLite. Existing tables require the explicit collation migration described in the MySQL migration driver guide; upgrading the package does not rewrite deployed tables.

Decimals on SQLite

Storage, reads, and equality filters (equals, not, in, notIn) are exact on every database, as are count, distinct, groupBy on the column, and set. What SQLite cannot do exactly, it refuses:

The orderBy refusal covers every spelling of an ordering, not just the bare one: take / skip / cursor windows, findFirst, ordering through a to-one relation, ordering inside a nested read, and groupBy’s orderBy. _count is never refused — counting rows needs no ordering.

A gt that silently skips a row differing in the 20th digit is worse than an error, so it is an error, and the error names the field, the reason, and the two workarounds (s.float() for approximate ordering, scaled integers in an s.bigInt() for exact ordered money). Full detail, including the column-type migration, is in the Decimal scalar page.

Errors and Prisma error codes

VibORM throws typed error classes with a stable V#### code on error.code. Each class declares the exact code it carries, so if (error.code === "V3001") narrows to UniqueConstraintError with compiler support and a switch over a union of error types can be checked for exhaustiveness — see the errors page for the full taxonomy and the narrowing rules. For code written against Prisma, every error also carries error.prismaCode — the Prisma code with the same meaning, or undefined when VibORM claims none. Porting a handler is a one-token edit:

try {
  await client.user.create({ data });
} catch (error) {
  if (error.prismaCode === "P2002") {
    // unique constraint — the same branch a Prisma app already has
  }
}

The table is deliberately partial. Transaction failures, nested-write failures, cache, migration and pending-operation errors report prismaCode: undefined rather than a near-neighbour code — an unclaimed code is honest, a wrong one silently mis-routes your catch. For retry decisions use error.isRetryable(), which covers deadlocks, serialization failures, and timeouts on every database.

error.toJSON() includes prismaCode when one is claimed and omits the key entirely otherwise.

ValueTooLongError is PostgreSQL and MySQL only. SQLite does not enforce declared column lengths — an over-long value is stored, not rejected — so no P2000 can be raised there. Prisma behaves the same way.

Type and API differences