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 to-many update, upsert, and delete targets take the extended unique where too — a superset of Prisma in those positions. A nested to-one update instead accepts an ordinary non-unique precondition on the one current member; to-one upsert and boolean delete have no selector.

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. They are also supported inside the two root bulk writes: a createMany row takes the create matrix below and updateMany.data takes the update matrix, since each is compiled as an ordinary record write. Support also depends on where the relation is stored:

• Parent-held to-one: the current record holds the foreign key.
• Child-held to-one: the related record holds the foreign key and the edge is singular.
• Child-held to-many: the related records hold the foreign key.
• Junction: a many-to-many join table holds membership.

Inside create

This matrix also applies to the create branch of a top-level upsert.

Create-time nested upsert is a VibORM extension. It performs a global unique lookup. A found row is adopted into the new relation and updated; a missing row is created and related. Prisma has no nested upsert in a create input.

Inside update

This matrix also applies to the update branch of a top-level upsert.

An empty slot and a clearable membership are different facts. For an owning to-one they normally coincide. A non-owning singular slot is derived nullable — the membership lives on the other row and may simply be missing — so deleting its child is valid; disconnecting must preserve that child and therefore still requires nullable child-side storage.

Direct polymorphic fields follow the parent-held to-one availability above, with a required type in target-specific payloads. Polymorphic inverse slots — singular s.toOne and plural s.toMany — follow the corresponding child-held column. Their membership is the exact stored (type, identity) pair. See the polymorphic relation reference for their payload shapes.

Ordinary and polymorphic child-held to-many set accept required membership. They may retain existing members and adopt new ones, but reject when any current exact member would depart. disconnect requires clearable membership and its key is absent otherwise.

On a many-to-many relation, scalar-only createMany starts with row-local routing; homogeneous leaf and adopt runs stay grouped. Each member is classified in input order, so one nameable row and one unnameable sibling can take different routes. skipDuplicates for that member depends on whether one complete unique selector can name the row that conflicted:

• it can — the skipped item links the existing target. The child insert is skipped and the distinct join row is still written, so the parent ends up connected to the row that was already there;
• it cannot — the target key is database-generated and the row spells two independent uniques, or the conflict would fire on an index no where can spell, or the only unique is compound with a null member — and that member is suppressed instead: the target is not written, its join row is not written, every sibling row still lands, and the row that was already there is neither rewritten nor linked. viborm does not guess which existing row to adopt.

Later members observe targets and descendants earlier members created. This left-to-right visibility also applies when relation-bearing members require dynamic planning.

When a createMany member itself carries relations, it uses the record-series contract, where a skipped member suppresses its complete subtree including the join. Interactive drivers use a member savepoint. A batch-only driver isolates the skippable root as one atomic segment, observes normalized row count, and does not dispatch descendants after a skip. This is safe when no write or nested series precedes that root. A member that needs such a prior effect refuses before dispatch, because the effect would survive a later root skip.

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.
• Required membership omits disconnect. A to-many set remains valid, but it must retain every current member.
• createMany with skipDuplicates rejects a row containing only database-owned defaults before any parent or child write.

Structural restrictions

The matrices show operation support. These restrictions are independent:

• A required membership cannot be cleared while preserving the related record. disconnect is absent; set rejects only when it would create a departing member.
• To-one disconnect and delete use their boolean form. Selector arrays and set are to-many operations.
• To-one create payloads name at most one active operation. A to-one update payload is read as one composition — an optional vacate, one supplier, an optional update of the supplied row — on BOTH directions. The five spellable replacement pairs are disconnect + connectOrCreate, disconnect + connect, disconnect + create, delete + connect, and delete + create; delete beside connectOrCreate is excluded deliberately. Any supplier may also carry an update, with or without a vacate ahead of it, and the modify always applies to the supplied row after the supplier has run — so a relative update counts from the supplied value, and the update may itself carry relations, nested bulk, or another composition. On the child-held direction a create supplier, or a connectOrCreate that creates, is located after the fact by the membership it just established: that costs one extra round trip and needs a driver with either interactive transactions or native atomic batch, and a driver with neither declines before the supplier writes. On the parent-held direction create or connectOrCreate beside an update remains refused at the type boundary. Two further spellable compositions are declined before any write by the own-write analyzer, because delete: true names a row whose identity is unknown at analysis and may be the one a sibling reads: parent-held delete + connect, and child-held delete plus a connect plus an update. The vacate always runs before the supplier, whatever order it is spelled in, and a parent-held vacate plus supplier folds to one foreign-key value with no transient NULL. Literal false is inactive. Other combinations fail at the validation and type boundary. Direct polymorphic payloads contain exactly one typed intent. To-many payloads may combine operation kinds. See Combining operations on one to-one relation.
• Nested createMany rows and nested updateMany.data may contain ordinary or direct polymorphic relation writes. Scalar-only shapes stay grouped. A relation-bearing shape becomes an ordered record series at that exact position in the parent tree. Any no-transaction driver with native atomic batch executes nested relation-bearing createMany and updateMany when VibORM can verify the complete parent and, where needed, membership in every later write batch. A nested dynamic shape without that exact guard is refused before its containing member writes. If reached inside a progressive root bulk call, earlier root members can already be committed and are reported.
• Relation-link selectors (connect, disconnect, set, and connectOrCreate.where) require unique discriminators; they do not accept the extra filters allowed by nested update and upsert targets.
• Many-to-many relations support scalar and compound primary keys on either side. .source("owner") and .target("target") remain scalar tokens: for a compound side they expand to owner_1, owner_2, … and target_1, target_2, … in declared primary-key order. Reads, writes, cascades, and generated key publication consume the complete tuple.
• A create-then-connectOrCreate conflict on the same target in one payload is rejected as an OwnWrite conflict instead of depending on sibling visibility.

There is no runtime nested-write depth counter. Deep fresh and selected-record subtrees use the same record compilers at each level. TypeScript can still hit its own instantiation limit for an extremely deep literal; constructing and widening such a payload programmatically avoids that editor-only limit.

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.

Generated keys and the execution substrate

A key the database assigns is readable back by the same call that created the row, and the rows underneath it can use it:

// `id` is s.int().id().increment() — the child's FK gets the value the INSERT made
await client.org.create({
  data: { name: "Acme", members: { create: [{ name: "Ada" }] } },
});

A primary key may have more than one generated member where the database allows it, and upsert can create through it:

const twin = s
  .model({ a: s.int().increment(), b: s.int().increment(), label: s.string() })
  .id(["a", "b"]);

await client.twin.upsert({
  where: { a_b: { a: 10, b: 20 } },
  create: { label: "created" },
  update: { label: "updated" },
});

On PostgreSQL the create arm returns both members from its own INSERT and addresses the new row by the complete key. Every member is read exactly; none is inferred from the position of another or from sequence adjacency. MySQL and SQLite cannot declare this shape — one AUTO_INCREMENT column and one INTEGER PRIMARY KEY respectively — so there is nothing to emulate there.

Where it can cost you something is the substrate, not the database:

PostgreSQL never uses lastval(): it is session-global, so a trigger or another generated column can move it. The producer’s own RETURNING is the exact source. When later SQL needs that value and no one-statement fold exists, the default operation awaits the producer batch, re-pins the created row and every consumed non-key value, and then runs the dependent batch. A later failure can therefore leave an earlier segment committed; the error carries progress and cache invalidation follows each completed or possibly visible segment.

An explicit $transaction([operationA, operationB]) remains one indivisible native batch. VibORM does not weaken that requested atomicity by splitting it, so an array that needs a PostgreSQL RETURNING value across its internal statements still refuses before effects unless the compiler can lower the complete array to one exact statement. The same fail-closed boundary applies to a custom driver that offers neither callback transactions nor atomic batches.

Fixed decimals

s.decimal({ precision, scale }) declares one exact domain. Storage, reads, filters, ordering, cursors, grouping, aggregates, and atomic arithmetic have the same logical answer on PostgreSQL, MySQL, and SQLite-family providers:

multiply, divide, and _avg use round-half-to-even when a derived result needs quantization; input is never rounded to fit. Every update object takes exactly one operation. _sum preserves scale and may widen beyond the field’s storage precision.

SQLite raw SQL remains physical and sees the coefficient. Typed model queries apply the descriptor and return a fresh Decimal. Full storage, list, migration, provider-limit, and raw-SQL details are 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