@vsrepo/prisma7-adapter 2.0.0-dev → 2.0.0-dev.1

package/README.md

@@ -24,14 +24,19 @@
 - [Installation](#installation)
 - [Basic usage](#basic-usage)
 - [Constructor config](#constructor-config)
+- [Global config](#global-config)
 - [Relations](#relations)
-  - [The two `relations`](#the-two-relations)
-  - [`relations` in the constructor (write)](#relations-in-the-constructor-write)
-    - [`mode`](#mode)
-    - [`restriction`](#restriction)
-    - [`pk` and `nullable`](#pk-and-nullable)
-    - [How each write method resolves relations](#how-each-write-method-resolves-relations)
-  - [`relations` in method options (read)](#relations-in-method-options-read)
+    - [The two `relations`](#the-two-relations)
+    - [`relations` in the constructor (write)](#relations-in-the-constructor-write)
+        - [`mode`](#mode)
+        - [`pk`](#pk)
+        - [`onUpdate`](#onupdate)
+        - [`onDisconnect`](#ondisconnect)
+        - [Ignoring a relation (`"ignore"`)](#ignoring-a-relation-ignore)
+        - [`fkHere` and `fkThere`](#fkhere-and-fkthere)
+        - [`allowOmitPk`](#allowomitpk)
+        - [How each write method resolves relations](#how-each-write-method-resolves-relations)
+    - [`relations` in method options (read)](#relations-in-method-options-read)
 - [Atomic and aggregation methods](#atomic-and-aggregation-methods)
 - [`createMany`/`createManyReturning`/`updateMany`/`updateManyReturning` don't support nested writes](#createmanycreatemanyreturningupdatemanyupdatemanyreturning-dont-support-nested-writes)
 - [Provider-specific limitations](#provider-specific-limitations)
@@ -67,7 +72,7 @@ class UserRepository extends VSRepository<User, string, MyOrmTypes> {
                 modelName: "user",
                 pkName: "id",
                 relations: {
-                    posts: { mode: "otm", restriction: "add", pk: "id" },
+                    posts: { mode: "otm", pk: "id" },
                 },
                 logLevel: VSLogLevel.WARN,
             }),
@@ -93,6 +98,7 @@ new Prisma7Adapter(prisma, {
     relations: { ... }, // optional — see "relations in the constructor (write)" below
     provider: "postgresql", // optional — detected from the Prisma Client when omitted
     logLevel: VSLogLevel.WARN, // optional — default: VSLogLevel.WARN
+    allowOmitPk: false, // optional — default: false. Read "`allowOmitPk`" before turning it on
 });
 ```
 
@@ -102,7 +108,22 @@ At construction, the adapter checks the Prisma Client and the model, and resolve
 - a `modelName` with no matching delegate on the client (`prisma.<modelName>`) throws `MODEL_NOT_FOUND`;
 - the provider comes from `provider` when set; otherwise it's detected from the generated client (`_engineConfig.activeProvider`, falling back to the driver adapter's `provider`). If it can't be detected, construction throws `NOT_SUPPORTED` — set `provider` explicitly in that case (one of `postgresql`, `cockroachdb`, `mysql`, `sqlite`, `sqlserver`).
 
-The other fields (`pkName`, `relations`, `logLevel`) are checked by TypeScript only, not at runtime.
+The other fields (`pkName`, `relations`, `logLevel`, `allowOmitPk`) are checked by TypeScript only, not at runtime.
+
+## Global config
+
+`provider`, `logLevel` and `allowOmitPk` can be set once for every adapter, through the static `setGlobalConfig`:
+
+```typescript
+import { VSLogLevel } from "vsrepo";
+import { Prisma7Adapter } from "@vsrepo/prisma7-adapter";
+
+Prisma7Adapter.setGlobalConfig({ logLevel: VSLogLevel.WARN });
+```
+
+- It only affects adapters created **after** the call, so call it before instantiating your repositories.
+- Each call **replaces** the previous global config — it doesn't merge with it.
+- A value set in an adapter's own config always wins over the global one.
 
 ## Relations
 
@@ -110,13 +131,13 @@ The other fields (`pkName`, `relations`, `logLevel`) are checked by TypeScript o
 
 The name `relations` appears in **two different places** in the API, with **different shapes and purposes** — easy to confuse. In a nutshell:
 
-| | `relations` in the **constructor** | `relations` in **method options** |
-| --- | --- | --- |
-| Where you define it | `new Prisma7Adapter(prisma, { relations: ... })` | `repository.get(where, { relations: ... })` — and other methods |
-| Shape | One **config object** per field: `{ mode, restriction, pk, nullable? }` | One **`true`/sub-object** per field: `{ posts: true }` |
-| Purpose | **Write** — when a `create`/`update`/`upsert`/`save` payload contains a relation field, tells the adapter how to turn it into a Prisma nested write (`create`/`connectOrCreate`/`upsert`/`disconnect`/`deleteMany`/`set`) | **Read** — eager loading: which relations to fetch alongside the result (becomes a Prisma `include`) |
-| Consumed by | `parsePrismaWriteData` (write resolver) | `parsePrismaInclude` (via `resolveReadArg`) |
-| Depends on the other? | No — it only affects writes | No — it works even with no `relations` in the constructor |
+|                       | `relations` in the **constructor**                                                                                                                                                                                                  | `relations` in **method options**                                                                    |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| Where you define it   | `new Prisma7Adapter(prisma, { relations: ... })`                                                                                                                                                                                    | `repository.get(where, { relations: ... })` — and other methods                                      |
+| Shape                 | One **config object** per field (`{ mode, pk, onUpdate?, onDisconnect?, fkHere?, fkThere? }`), or `"ignore"`                                                                                                                        | One **`true`/sub-object** per field: `{ posts: true }`                                               |
+| Purpose               | **Write** — when a `create`/`update`/`upsert`/`save` payload contains a relation field, tells the adapter how to turn it into a Prisma nested write (`create`/`connect`/`connectOrCreate`/`upsert`/`disconnect`/`deleteMany`/`set`) | **Read** — eager loading: which relations to fetch alongside the result (becomes a Prisma `include`) |
+| Consumed by           | `parsePrismaWriteData` (write resolver)                                                                                                                                                                                             | `parsePrismaInclude` (via `resolveReadArg`)                                                          |
+| Depends on the other? | No — it only affects writes                                                                                                                                                                                                         | No — it works even with no `relations` in the constructor                                            |
 
 Neither depends on the other: the method-options `relations` does eager loading even when the constructor has no `relations`, and the constructor `relations` governs write behavior even if you never pass `relations` in options. The two subsections below cover each one.
 
@@ -128,9 +149,10 @@ Each relation is configured by its field name:
 
 ```typescript
 relations: {
-    posts: { mode: "otm", restriction: "add", pk: "id" },
-    address: { mode: "oto", restriction: "set", pk: "id" },
-    author: { mode: "mto", restriction: "set", pk: "id", nullable: true },
+    posts: { mode: "otm", pk: "id", onUpdate: "set" },
+    address: { mode: "oto", pk: "id", onUpdate: "upsert", onDisconnect: "delete" },
+    author: { mode: "mto", pk: "id" }, // every option has a default
+    audit: "ignore", // never written through this repository
 }
 ```
 
@@ -140,32 +162,103 @@ Without `relations`, every field — including relation fields — is passed str
 
 Cardinality of the relation, from the point of view of the entity that owns the field:
 
-| `mode` | Meaning | Field shape you send |
-| --- | --- | --- |
-| `oto` | one-to-one | a single object, or `null` |
-| `mto` | many-to-one | a single object, or `null` |
-| `otm` | one-to-many | an array of objects |
-| `mtm` | many-to-many | an array of objects |
+| `mode` | Meaning      | Field shape you send       | Options                                                                                    |
+| ------ | ------------ | -------------------------- | ------------------------------------------------------------------------------------------ |
+| `oto`  | one-to-one   | a single object, or `null` | `pk`, `onUpdate` (to-one), `onDisconnect` (`"disconnect"`/`"delete"`), `fkHere`, `fkThere` |
+| `mto`  | many-to-one  | a single object, or `null` | `pk`, `onUpdate` (to-one), `onDisconnect` (`"disconnect"`/`"delete"`), `fkHere`, `fkThere` |
+| `otm`  | one-to-many  | an array of objects        | `pk`, `onUpdate` (to-many), `fkThere`                                                      |
+| `mtm`  | many-to-many | an array of objects        | `pk`, `onUpdate` (to-many), `fkThere`                                                      |
+
+#### `pk`
+
+The field used to identify an existing related record. An item **with** `pk` in the payload is connected to (or upserted into) the existing record; an item **without** it is created.
+
+#### `onUpdate`
 
-#### `restriction`
+How `save`/`update`/`upsert` write the relation on update. The values accepted depend on the `mode`.
 
-Controls how `save`/`update`/`upsert` handle relation items that already exist (matched by `pk`) and, for to-many relations, items that were **not** included in the payload:
+**To-one (`oto`/`mto`)**, when the related object has its `pk`:
 
-- **`"add"`** — only creates/connects/upserts the items you send. Existing items that aren't in the payload are left untouched.
-- **`"set"`** — same as `"add"`, but also removes what wasn't sent: for `otm` it runs a `deleteMany` on the items missing from the array; for `mtm` it resets the join (`set: []`) before reconnecting; for `oto`/`mto` with `nullable: true`, sending `null` deletes/disconnects the relation (see below).
+- **`"connect"`** never creates nor overwrites the related record: it only points the relation to it.
+- **`"connectOrCreate"`** creates the related record when it is missing.
+- **`"upsert"`** is the one that **overwrites** the related record with the fields you sent.
+- When the owner record itself is being created (`create`, or the `create` branch of `save`), a related object with `pk` always becomes a `connectOrCreate`.
 
-#### `pk` and `nullable`
+**To-many (`otm`/`mtm`)**, for the items that already exist (matched by `pk`) and for the ones that were **not** sent:
 
-- **`pk`** — the field used to identify an existing related record. An item **with** `pk` in the payload becomes a `connectOrCreate`/`upsert`; an item **without** it becomes a plain `create`.
-- **`nullable`** — relevant for `oto`/`mto` to-one relations. When `true`, sending `null` for the field resolves to `disconnect` on update (`delete` instead for `oto` with `restriction: "set"` — an `oto` side can't just be "disconnected", the owned row is removed). When omitted/`false`, sending `null` for a to-one relation throws a `VSRepoAdapterError` (code `INVALID_DATA`) telling you the relation is not nullable.
+- **`"add"`** (default) — only creates/connects/upserts the items you send. Existing items that aren't in the payload are left untouched.
+- **`"set"`** — same as `"add"`, but also removes what wasn't sent: `otm` runs a `deleteMany` on the items missing from the array, and `mtm` resets the join (`set: []`) before reconnecting.
+
+#### `onDisconnect`
+
+What sending `null` to a to-one relation does on update:
+
+- **`"disconnect"`** (default) — detaches the related record and keeps it. Prisma rejects it when the relation is required.
+- **`"delete"`** — deletes the related record. Available for `oto` and `mto`, and always opt-in. Be careful on an `mto`: the related record is shared with other rows, so deleting it affects all of them, and Prisma rejects the write while other rows still reference it (unless the FK has a referential action such as `onDelete: Cascade`).
+
+#### Ignoring a relation (`"ignore"`)
+
+Setting a relation to `"ignore"` leaves that field out of every write (`create`, `update`, `save`...): the object (or array) is simply dropped. It is useful for a relation you **load** but don't want to **persist** through this entity.
+
+```typescript
+// AddressRepository
+relations: {
+    user: "ignore";
+}
+```
+
+Since the relation object is dropped, a scalar FK in the payload (`userId`) goes through as is, together with the primary key. That makes it the simplest way around the [`allowOmitPk` problem](#allowomitpk) when you only want to keep the FK: `address.save(addressLoadedWithItsUser)` updates the address and never touches the user.
+
+#### `fkHere` and `fkThere`
+
+In a one-to-one or many-to-one relation, only one side keeps the foreign key column. For `Address.user`, that's `Address.userId`. Tell the adapter which side each entity is on:
+
+| Entity                 | Relation field | Holds the FK?                                       | Config              |
+| ---------------------- | -------------- | --------------------------------------------------- | ------------------- |
+| `Address` (owner side) | `user`         | **yes** — `userId` is a column of `Address`         | `fkHere: "userId"`  |
+| `User` (inverse side)  | `address`      | no — the FK lives in the related entity (`Address`) | `fkThere: "userId"` |
+
+```typescript
+// UserRepository
+relations: { address: { mode: "oto", pk: "id", fkThere: "userId" } }
+
+// AddressRepository
+relations: { user: { mode: "oto", pk: "id", fkHere: "userId" } }
+```
+
+- **`fkThere`** — name of the FK that lives in the **related** entity. A related object loaded with `get`/`find` usually carries it (`address: { id, street, userId }`), but the relation already sets it, and Prisma doesn't accept it inside the nested write. The adapter strips it from the related payload(s) before building the write.
+- **`fkHere`** — name of the FK that lives in **this** entity. Prisma doesn't accept the scalar FK together with the relation object, so when the relation field is in the payload the adapter drops this field from `create` and `update`. A payload that carries only the scalar FK (and no relation object) is left as it is.
+
+`fkHere` has one more consequence, for the primary key — read the next section.
+
+#### `allowOmitPk`
+
+`allowOmitPk` is an adapter option (it can also be set in the [global config](#global-config)), but it only matters for relations configured with `fkHere`.
+
+**The problem.** Take an `Address` loaded together with its `user` (`relations: { user: true }`) and sent back to `save`. The payload has the primary key (`id`) **and** a relation that holds its FK in the entity itself. Once the relation object is there, Prisma won't take the scalar FK nor the primary key (`Unknown argument 'id'`), so the adapter can't send everything.
+
+**What the adapter does:**
+
+- **`allowOmitPk: false`** (default) — throws a `VSRepoAdapterError` (`INVALID_DATA`) **before** touching the database, explaining what to do. Payloads without a primary key (e.g. a plain `create`), or without the relation object, are not affected.
+- **`allowOmitPk: true`** — drops the primary key from `create` and `update`. Records that already exist are still found through `where: { id }`, so **updates work normally**. The catch is the `create` branch of `save`: if the record doesn't exist yet, it is created with a **database-generated primary key, not the one you sent** — and nothing warns you.
+
+**When to turn it on.** Only if you really need it, and only if it's not your application that manages the ids — i.e. the database generates them (`autoincrement`, `uuid()`/`cuid()` defaults, sequences...). If your application assigns the ids (client-generated UUIDs, ids imported from another system, ids that other records already reference), keep it **off**: a record that doesn't exist would silently be stored under a different id.
+
+**Ways around it, without `allowOmitPk`:**
+
+1. **Ignore the relation** when you only want to keep the FK: `relations: { user: "ignore" }` (see [Ignoring a relation](#ignoring-a-relation-ignore)). The payload keeps `id` and `userId`, and the related entity is not written.
+2. **Send the scalar FK instead of the relation object.** `address.save({ id, city, userId })` keeps both `id` and `userId`, since there's no relation object. Persist the related entity on its own (through its repository) when it also changed — ideally in one `transaction`.
+3. **Send only what changed.** `address.update({ id }, { city })` carries neither the primary key nor the relation.
+4. **Save from the other side.** `user.save({ ...user, address })` keeps the primary keys (configure `fkThere` there): the FK lives in `Address`, so `User` has no FK of its own to conflict with.
+5. **Let the database generate the key for new records.** Don't send `id` when creating: `address.create({ city, user })`.
 
 #### How each write method resolves relations
 
-| Method | Relations |
-| --- | --- |
-| `create` | `create`/`connectOrCreate` only (no upsert — there's nothing to update yet) |
-| `update` / `upsert` (`update` half) / `save` (upsert branch) | Full resolution: `create`/`connectOrCreate`/`upsert`/`disconnect`/`delete`/`deleteMany`/`set`, per `mode`/`restriction` |
-| `createMany` / `createManyReturning` / `updateMany` / `updateManyReturning` | Not supported — throws a `VSRepoAdapterError` naming the offending field if the payload contains a configured relation |
+| Method                                                                      | Relations                                                                                                                                     |
+| --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `create`                                                                    | `create`/`connectOrCreate` only (no upsert — there's nothing to update yet)                                                                   |
+| `update` / `upsert` (`update` half) / `save` (upsert branch)                | Full resolution: `create`/`connect`/`connectOrCreate`/`upsert`/`disconnect`/`delete`/`deleteMany`/`set`, per `mode`/`onUpdate`/`onDisconnect` |
+| `createMany` / `createManyReturning` / `updateMany` / `updateManyReturning` | Not supported — throws a `VSRepoAdapterError` naming the offending field if the payload contains a configured relation                        |
 
 ### `relations` in method options (read)
 
@@ -179,10 +272,10 @@ const user = await userRepository.get(
     "...", // primary key
     {
         relations: {
-            posts: true,                   // fetch posts along
-            author: { profile: true },     // and, inside author, its profile (nested eager loading)
+            posts: true, // fetch posts along
+            author: { profile: true }, // and, inside author, its profile (nested eager loading)
         },
-    }
+    },
 );
 ```
 
@@ -192,16 +285,14 @@ The `select` and `relations` you pass in the options are turned into a Prisma `s
 
 ```ts
 const prismaSelect = options.select && parsePrismaSelect(options.select);
-const prismaInclude = prismaSelect
-    ? undefined
-    : options.relations && parsePrismaInclude(options.relations);
+const prismaInclude = prismaSelect ? undefined : options.relations && parsePrismaInclude(options.relations);
 ```
 
 ## Atomic and aggregation methods
 
 The adapter implements the 12 abstract methods `VSRepository`'s `increment`/`decrement`/`multiply`/`divide`, their `*Many` counterparts, and `sum`/`average`/`min`/`max` delegate to: `incrementOne`, `decrementOne`, `multiplyOne`, `divideOne`, `incrementMany`, `decrementMany`, `multiplyMany`, `divideMany`, `sum`, `average`, `min`, `max`.
 
-- `incrementOne`/`decrementOne`/`multiplyOne`/`divideOne` translate directly into Prisma's native single-field atomic write — `data: { [field]: { increment: value } }` (and `decrement`/`multiply`/`divide`) — so the operation is evaluated **server-side** against the row's *current* value (`UPDATE ... SET field = field + value`), not as a fetch-then-save round trip on the client. Prisma's `update()` already returns the row reflecting the state *after* the write, so the adapter never issues a follow-up read.
+- `incrementOne`/`decrementOne`/`multiplyOne`/`divideOne` translate directly into Prisma's native single-field atomic write — `data: { [field]: { increment: value } }` (and `decrement`/`multiply`/`divide`) — so the operation is evaluated **server-side** against the row's _current_ value (`UPDATE ... SET field = field + value`), not as a fetch-then-save round trip on the client. Prisma's `update()` already returns the row reflecting the state _after_ the write, so the adapter never issues a follow-up read.
 - `incrementMany`/`decrementMany`/`multiplyMany`/`divideMany` apply that same native write to **every** record matching `where`, through Prisma's `updateMany`, also evaluated server-side. They return a `{ count }` (`CountResult`) instead of the records.
 - `sum`/`average`/`min`/`max` translate into Prisma's `aggregate()` with `_sum`/`_avg`/`_min`/`_max: { [field]: true }`. The raw result (`number`, `bigint`, a `Decimal` instance, or `null`) is normalized to `number | null` — `null` is returned as-is (mirroring SQL's `SUM()`/`AVG()`/`MIN()`/`MAX()`, which return `NULL`, not `0`, over an empty set), and a `Decimal`/`DecimalLike` value is converted via its `.toNumber()`.
 
@@ -234,11 +325,11 @@ const mostExpensive = await productRepository.max("price");
 
 Some features this adapter relies on aren't available on every database provider. The adapter checks every feature below upfront and throws a `VSRepoAdapterError` (code `NOT_SUPPORTED`) before touching the database.
 
-| Feature | Supported providers | Not supported |
-| --- | --- | --- |
-| `ignoreCase` (translated to Prisma's `mode: "insensitive"`; used by `findByXIgnoreCase` dynamic methods) | PostgreSQL, CockroachDB | MySQL, SQLite, SQL Server — MySQL and SQL Server are case-insensitive by default (depending on the collation), so no `mode` is needed there; SQLite is only case-insensitive for ASCII characters |
-| `createManyReturning` / `updateManyReturning` (built on Prisma's `createManyAndReturn`/`updateManyAndReturn`) | PostgreSQL, CockroachDB, SQLite | MySQL, SQL Server |
-| `ignoreConflicts: true` on `createMany` / `createManyReturning` (Prisma's `skipDuplicates`) | PostgreSQL, MySQL, CockroachDB | SQL Server, SQLite |
+| Feature                                                                                                       | Supported providers             | Not supported                                                                                                                                                                                     |
+| ------------------------------------------------------------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ignoreCase` (translated to Prisma's `mode: "insensitive"`; used by `findByXIgnoreCase` dynamic methods)      | PostgreSQL, CockroachDB         | MySQL, SQLite, SQL Server — MySQL and SQL Server are case-insensitive by default (depending on the collation), so no `mode` is needed there; SQLite is only case-insensitive for ASCII characters |
+| `createManyReturning` / `updateManyReturning` (built on Prisma's `createManyAndReturn`/`updateManyAndReturn`) | PostgreSQL, CockroachDB, SQLite | MySQL, SQL Server                                                                                                                                                                                 |
+| `ignoreConflicts: true` on `createMany` / `createManyReturning` (Prisma's `skipDuplicates`)                   | PostgreSQL, MySQL, CockroachDB  | SQL Server, SQLite                                                                                                                                                                                |
 
 The `like` operator isn't supported on any provider — Prisma has no equivalent, so the adapter throws `NOT_SUPPORTED`. Use `contains`, `startsWith` or `endsWith` instead.
 
@@ -297,7 +388,7 @@ The adapter uses `VSLogger` (from `vsrepo`) internally: every method logs a `DEB
 
 ## Requirements
 
-- `vsrepo` ^3.0.0-dev.2
-- `@prisma/client` ^7.10.0
+- `vsrepo` ^3.0.0-dev.3
+- `@prisma/client` ^7.10.1
 - Node.js `>=22`
 - A PostgreSQL, CockroachDB, MySQL, SQLite or SQL Server database (all covered by the integration tests)

package/README.pt-BR.md

@@ -24,14 +24,19 @@ Implementação de `VSRepoAdapter` para o [VSRepository v3](https://github.com/V
 - [Instalação](#instalação)
 - [Uso básico](#uso-básico)
 - [Config do construtor](#config-do-construtor)
+- [Config global](#config-global)
 - [Relations](#relations)
-  - [Os dois `relations`](#os-dois-relations)
-  - [`relations` no construtor (escrita)](#relations-no-construtor-escrita)
-    - [`mode`](#mode)
-    - [`restriction`](#restriction)
-    - [`pk` e `nullable`](#pk-e-nullable)
-    - [Como cada método de escrita resolve relations](#como-cada-método-de-escrita-resolve-relations)
-  - [`relations` nas options (leitura)](#relations-nas-options-leitura)
+    - [Os dois `relations`](#os-dois-relations)
+    - [`relations` no construtor (escrita)](#relations-no-construtor-escrita)
+        - [`mode`](#mode)
+        - [`pk`](#pk)
+        - [`onUpdate`](#onupdate)
+        - [`onDisconnect`](#ondisconnect)
+        - [Ignorando uma relation (`"ignore"`)](#ignorando-uma-relation-ignore)
+        - [`fkHere` e `fkThere`](#fkhere-e-fkthere)
+        - [`allowOmitPk`](#allowomitpk)
+        - [Como cada método de escrita resolve relations](#como-cada-método-de-escrita-resolve-relations)
+    - [`relations` nas options (leitura)](#relations-nas-options-leitura)
 - [Métodos atômicos e de agregação](#métodos-atômicos-e-de-agregação)
 - [`createMany`/`createManyReturning`/`updateMany`/`updateManyReturning` não suportam nested writes](#createmanycreatemanyreturningupdatemanyupdatemanyreturning-não-suportam-nested-writes)
 - [Limitações por provider](#limitações-por-provider)
@@ -67,7 +72,7 @@ class UserRepository extends VSRepository<User, string, MyOrmTypes> {
                 modelName: "user",
                 pkName: "id",
                 relations: {
-                    posts: { mode: "otm", restriction: "add", pk: "id" },
+                    posts: { mode: "otm", pk: "id" },
                 },
                 logLevel: VSLogLevel.WARN,
             }),
@@ -93,6 +98,7 @@ new Prisma7Adapter(prisma, {
     relations: { ... }, // opcional — ver "relations no construtor (escrita)" abaixo
     provider: "postgresql", // opcional — detectado a partir do Prisma Client quando omitido
     logLevel: VSLogLevel.WARN, // opcional — default: VSLogLevel.WARN
+    allowOmitPk: false, // opcional — default: false. Leia "`allowOmitPk`" antes de ativar
 });
 ```
 
@@ -102,7 +108,22 @@ Na construção, o adapter confere o Prisma Client e o model, e resolve o provid
 - um `modelName` sem delegate correspondente no client (`prisma.<modelName>`) lança `MODEL_NOT_FOUND`;
 - o provider vem do `provider`, quando informado; senão é detectado a partir do client gerado (`_engineConfig.activeProvider`, com fallback pro `provider` do driver adapter). Se não for detectável, a construção lança `NOT_SUPPORTED` — nesse caso, informe o `provider` explicitamente (um de `postgresql`, `cockroachdb`, `mysql`, `sqlite`, `sqlserver`).
 
-Os outros campos (`pkName`, `relations`, `logLevel`) são checados só pelo TypeScript, não em runtime.
+Os outros campos (`pkName`, `relations`, `logLevel`, `allowOmitPk`) são checados só pelo TypeScript, não em runtime.
+
+## Config global
+
+`provider`, `logLevel` e `allowOmitPk` podem ser definidos uma vez pra todos os adapters, pelo `setGlobalConfig` estático:
+
+```typescript
+import { VSLogLevel } from "vsrepo";
+import { Prisma7Adapter } from "@vsrepo/prisma7-adapter";
+
+Prisma7Adapter.setGlobalConfig({ logLevel: VSLogLevel.WARN });
+```
+
+- Só afeta adapters criados **depois** da chamada, então chame antes de instanciar seus repositories.
+- Cada chamada **substitui** a config global anterior — não faz merge com ela.
+- Um valor definido na config do próprio adapter sempre vence o global.
 
 ## Relations
 
@@ -110,13 +131,13 @@ Os outros campos (`pkName`, `relations`, `logLevel`) são checados só pelo Type
 
 O nome `relations` aparece em **dois lugares diferentes** da API, com **formas e propósitos diferentes** — fácil de confundir. Em resumo:
 
-| | `relations` no **construtor** | `relations` nas **options** |
-| --- | --- | --- |
-| Onde você define | `new Prisma7Adapter(prisma, { relations: ... })` | `repository.get(where, { relations: ... })` — e demais métodos |
-| Formato | Um objeto de **configuração** por campo: `{ mode, restriction, pk, nullable? }` | Um objeto por campo **só com `true` ou sub-objeto**: `{ posts: true }` |
-| Propósito | **Escrita** — quando um payload de `create`/`update`/`upsert`/`save` tem campo de relação, diz como transformá-lo num nested write do Prisma (`create`/`connectOrCreate`/`upsert`/`disconnect`/`deleteMany`/`set`) | **Leitura** — eager loading: quais relations trazer junto no resultado (vira um `include` do Prisma) |
-| Quem consome | `parsePrismaWriteData` (resolver de escrita) | `parsePrismaInclude` (via `resolveReadArg`) |
-| Precisa da outra? | Não — só afeta escritas | Não — funciona mesmo sem `relations` no construtor |
+|                   | `relations` no **construtor**                                                                                                                                                                                                | `relations` nas **options**                                                                          |
+| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| Onde você define  | `new Prisma7Adapter(prisma, { relations: ... })`                                                                                                                                                                             | `repository.get(where, { relations: ... })` — e demais métodos                                       |
+| Formato           | Um objeto de **configuração** por campo (`{ mode, pk, onUpdate?, onDisconnect?, fkHere?, fkThere? }`), ou `"ignore"`                                                                                                         | Um objeto por campo **só com `true` ou sub-objeto**: `{ posts: true }`                               |
+| Propósito         | **Escrita** — quando um payload de `create`/`update`/`upsert`/`save` tem campo de relação, diz como transformá-lo num nested write do Prisma (`create`/`connect`/`connectOrCreate`/`upsert`/`disconnect`/`deleteMany`/`set`) | **Leitura** — eager loading: quais relations trazer junto no resultado (vira um `include` do Prisma) |
+| Quem consome      | `parsePrismaWriteData` (resolver de escrita)                                                                                                                                                                                 | `parsePrismaInclude` (via `resolveReadArg`)                                                          |
+| Precisa da outra? | Não — só afeta escritas                                                                                                                                                                                                      | Não — funciona mesmo sem `relations` no construtor                                                   |
 
 Nenhum depende do outro: o `relations` das options faz eager loading de leitura mesmo quando o construtor não tem `relations`; e o `relations` do construtor governa o comportamento de escrita mesmo que você nunca passe `relations` nas options. As duas subseções abaixo detalham cada um.
 
@@ -128,9 +149,10 @@ Cada relation é configurada pelo nome do campo:
 
 ```typescript
 relations: {
-    posts: { mode: "otm", restriction: "add", pk: "id" },
-    address: { mode: "oto", restriction: "set", pk: "id" },
-    author: { mode: "mto", restriction: "set", pk: "id", nullable: true },
+    posts: { mode: "otm", pk: "id", onUpdate: "set" },
+    address: { mode: "oto", pk: "id", onUpdate: "upsert", onDisconnect: "delete" },
+    author: { mode: "mto", pk: "id" }, // toda opção tem default
+    audit: "ignore", // nunca é escrita por este repository
 }
 ```
 
@@ -140,32 +162,103 @@ Sem `relations`, todo campo — incluindo campos de relação — é repassado d
 
 Cardinalidade da relation, do ponto de vista da entidade dona do campo:
 
-| `mode` | Significado | Formato do campo que você envia |
-| --- | --- | --- |
-| `oto` | one-to-one | um único objeto, ou `null` |
-| `mto` | many-to-one | um único objeto, ou `null` |
-| `otm` | one-to-many | um array de objetos |
-| `mtm` | many-to-many | um array de objetos |
+| `mode` | Significado  | Formato do campo que você envia | Opções                                                                                     |
+| ------ | ------------ | ------------------------------- | ------------------------------------------------------------------------------------------ |
+| `oto`  | one-to-one   | um único objeto, ou `null`      | `pk`, `onUpdate` (to-one), `onDisconnect` (`"disconnect"`/`"delete"`), `fkHere`, `fkThere` |
+| `mto`  | many-to-one  | um único objeto, ou `null`      | `pk`, `onUpdate` (to-one), `onDisconnect` (`"disconnect"`/`"delete"`), `fkHere`, `fkThere` |
+| `otm`  | one-to-many  | um array de objetos             | `pk`, `onUpdate` (to-many), `fkThere`                                                      |
+| `mtm`  | many-to-many | um array de objetos             | `pk`, `onUpdate` (to-many), `fkThere`                                                      |
+
+#### `pk`
+
+O campo usado pra identificar um registro relacionado já existente. Um item **com** `pk` no payload é conectado (ou recebe upsert) ao registro existente; um item **sem** ele é criado.
+
+#### `onUpdate`
 
-#### `restriction`
+Como `save`/`update`/`upsert` escrevem a relation no update. Os valores aceitos dependem do `mode`.
 
-Controla como `save`/`update`/`upsert` tratam itens de relação que já existem (casados pela `pk`) e, pra relations to-many, itens que **não** vieram no payload:
+**To-one (`oto`/`mto`)**, quando o objeto relacionado tem a `pk`:
 
-- **`"add"`** — só cria/conecta/faz upsert dos itens enviados. Itens já existentes que não estão no payload permanecem intocados.
-- **`"set"`** — igual a `"add"`, mas também remove o que não foi enviado: em `otm` roda um `deleteMany` nos itens que faltam no array; em `mtm` reseta o vínculo (`set: []`) antes de reconectar; em `oto`/`mto` com `nullable: true`, enviar `null` apaga/desconecta a relation (ver abaixo).
+- **`"connect"`** nunca cria nem sobrescreve o registro relacionado: só aponta a relation pra ele.
+- **`"connectOrCreate"`** cria o relacionado quando ele não existe.
+- **`"upsert"`** é a que **sobrescreve** o relacionado com os campos enviados.
+- Quando o próprio registro dono está sendo criado (`create`, ou o ramo `create` do `save`), um relacionado com `pk` sempre vira `connectOrCreate`.
 
-#### `pk` e `nullable`
+**To-many (`otm`/`mtm`)**, pros itens que já existem (casados por `pk`) e pros que **não** foram enviados:
 
-- **`pk`** — o campo usado pra identificar um registro relacionado já existente. Um item **com** `pk` no payload vira um `connectOrCreate`/`upsert`; um item **sem** `pk` vira um `create` simples.
-- **`nullable`** — relevante pras relações to-one `oto`/`mto`. Quando `true`, enviar `null` no campo resolve pra `disconnect` no update (`delete` no caso de `oto` com `restriction: "set"` — um lado `oto` não dá só pra "desconectar", a linha possuída é removida). Quando omitido/`false`, enviar `null` numa relação to-one lança um `VSRepoAdapterError` (code `INVALID_DATA`) avisando que a relation não é nullable.
+- **`"add"`** (default) — só cria/conecta/faz upsert dos itens enviados. Itens já existentes que não estão no payload permanecem intocados.
+- **`"set"`** — igual ao `"add"`, mas também remove o que não foi enviado: `otm` roda um `deleteMany` nos itens ausentes do array, e `mtm` zera o join (`set: []`) antes de reconectar.
+
+#### `onDisconnect`
+
+O que enviar `null` pra uma relation to-one faz no update:
+
+- **`"disconnect"`** (default) — desanexa o registro relacionado e o mantém. O Prisma rejeita quando a relation é obrigatória.
+- **`"delete"`** — apaga o registro relacionado. Existe pra `oto` e `mto`, e é sempre opt-in. Cuidado num `mto`: o relacionado é compartilhado com outras linhas, então apagar afeta todas elas, e o Prisma rejeita a escrita enquanto outras linhas ainda o referenciam (a menos que a FK tenha uma ação referencial como `onDelete: Cascade`).
+
+#### Ignorando uma relation (`"ignore"`)
+
+Definir uma relation como `"ignore"` deixa o campo fora de toda escrita (`create`, `update`, `save`...): o objeto (ou array) é simplesmente descartado. Serve pra uma relation que você **carrega** mas não quer **persistir** por essa entidade.
+
+```typescript
+// AddressRepository
+relations: {
+    user: "ignore";
+}
+```
+
+Como o objeto de relation é descartado, uma FK escalar no payload (`userId`) passa como está, junto da primary key. Isso faz dela a forma mais simples de contornar o [problema do `allowOmitPk`](#allowomitpk) quando você só quer manter a FK: `address.save(addressCarregadoComUser)` atualiza o address e nunca toca no user.
+
+#### `fkHere` e `fkThere`
+
+Numa relation one-to-one ou many-to-one, só um dos lados guarda a coluna da foreign key. Em `Address.user`, é a `Address.userId`. Informe ao adapter em qual lado cada entidade está:
+
+| Entidade              | Campo da relation | Guarda a FK?                                        | Config              |
+| --------------------- | ----------------- | --------------------------------------------------- | ------------------- |
+| `Address` (lado dono) | `user`            | **sim** — `userId` é uma coluna de `Address`        | `fkHere: "userId"`  |
+| `User` (lado inverso) | `address`         | não — a FK fica na entidade relacionada (`Address`) | `fkThere: "userId"` |
+
+```typescript
+// UserRepository
+relations: { address: { mode: "oto", pk: "id", fkThere: "userId" } }
+
+// AddressRepository
+relations: { user: { mode: "oto", pk: "id", fkHere: "userId" } }
+```
+
+- **`fkThere`** — nome da FK que fica na entidade **relacionada**. Um objeto relacionado carregado com `get`/`find` normalmente a traz (`address: { id, street, userId }`), mas a relation já define esse valor, e o Prisma não aceita ela dentro do nested write. O adapter remove a FK do(s) payload(s) relacionado(s) antes de montar a escrita.
+- **`fkHere`** — nome da FK que fica **nesta** entidade. O Prisma não aceita a FK escalar junto do objeto de relation, então, quando o campo da relation está no payload, o adapter remove esse campo do `create` e do `update`. Um payload que traz só a FK escalar (sem o objeto de relation) fica como está.
+
+O `fkHere` tem mais uma consequência, pra primary key — leia a próxima seção.
+
+#### `allowOmitPk`
+
+`allowOmitPk` é uma opção do adapter (também dá pra definir na [config global](#config-global)), mas só importa pra relations configuradas com `fkHere`.
+
+**O problema.** Pegue um `Address` carregado junto com o `user` (`relations: { user: true }`) e enviado de volta pro `save`. O payload tem a primary key (`id`) **e** uma relation que guarda a FK na própria entidade. Com o objeto de relation presente, o Prisma não aceita nem a FK escalar nem a primary key (`Unknown argument 'id'`), então o adapter não consegue enviar tudo.
+
+**O que o adapter faz:**
+
+- **`allowOmitPk: false`** (default) — lança um `VSRepoAdapterError` (`INVALID_DATA`) **antes** de tocar no banco, explicando o que fazer. Payloads sem primary key (um `create` simples, por exemplo) ou sem o objeto de relation não são afetados.
+- **`allowOmitPk: true`** — remove a primary key do `create` e do `update`. Registros que já existem continuam sendo achados pelo `where: { id }`, então **os updates funcionam normalmente**. O porém é o ramo `create` do `save`: se o registro ainda não existe, ele é criado com uma **primary key gerada pelo banco, e não a que você enviou** — e nada te avisa disso.
+
+**Quando ativar.** Só se for realmente necessário, e só se não for a sua aplicação que gerencia os ids — ou seja, o banco os gera (`autoincrement`, defaults `uuid()`/`cuid()`, sequences...). Se a aplicação atribui os ids (UUIDs gerados no client, ids importados de outro sistema, ids que outros registros já referenciam), mantenha **desativado**: um registro que não existe seria gravado, sem aviso, com outro id.
+
+**Formas de contornar, sem `allowOmitPk`:**
+
+1. **Ignorar a relation** quando você só quer manter a FK: `relations: { user: "ignore" }` (veja [Ignorando uma relation](#ignorando-uma-relation-ignore)). O payload mantém `id` e `userId`, e a entidade relacionada não é escrita.
+2. **Enviar a FK escalar no lugar do objeto de relation.** `address.save({ id, city, userId })` mantém `id` e `userId`, já que não há objeto de relation. Persista a entidade relacionada por conta própria (pelo repository dela) quando ela também mudou — de preferência numa só `transaction`.
+3. **Enviar só o que mudou.** `address.update({ id }, { city })` não carrega nem a primary key nem a relation.
+4. **Salvar pelo outro lado.** `user.save({ ...user, address })` mantém as primary keys (configure o `fkThere` lá): a FK fica em `Address`, então `User` não tem FK própria pra conflitar.
+5. **Deixar o banco gerar a key dos registros novos.** Não envie `id` ao criar: `address.create({ city, user })`.
 
 #### Como cada método de escrita resolve relations
 
-| Método | Relations |
-| --- | --- |
-| `create` | Só `create`/`connectOrCreate` (sem upsert — ainda não existe nada pra atualizar) |
-| `update` / `upsert` (metade do `update`) / `save` (branch de upsert) | Resolução completa: `create`/`connectOrCreate`/`upsert`/`disconnect`/`delete`/`deleteMany`/`set`, conforme `mode`/`restriction` |
-| `createMany` / `createManyReturning` / `updateMany` / `updateManyReturning` | Não suportado — lança um `VSRepoAdapterError` apontando o campo problemático se o payload tiver uma relation configurada |
+| Método                                                                      | Relations                                                                                                                                             |
+| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `create`                                                                    | Só `create`/`connectOrCreate` (sem upsert — ainda não existe nada pra atualizar)                                                                      |
+| `update` / `upsert` (metade do `update`) / `save` (branch de upsert)        | Resolução completa: `create`/`connect`/`connectOrCreate`/`upsert`/`disconnect`/`delete`/`deleteMany`/`set`, conforme `mode`/`onUpdate`/`onDisconnect` |
+| `createMany` / `createManyReturning` / `updateMany` / `updateManyReturning` | Não suportado — lança um `VSRepoAdapterError` apontando o campo problemático se o payload tiver uma relation configurada                              |
 
 ### `relations` nas options (leitura)
 
@@ -179,10 +272,10 @@ const user = await userRepository.get(
     "...", // primary key
     {
         relations: {
-            posts: true,                   // carrega os posts junto
-            author: { profile: true },     // e, dentro do author, o profile (eager loading aninhado)
+            posts: true, // carrega os posts junto
+            author: { profile: true }, // e, dentro do author, o profile (eager loading aninhado)
         },
-    }
+    },
 );
 ```
 
@@ -192,16 +285,14 @@ O `select` e o `relations` que você passa nas options são transformados num `s
 
 ```ts
 const prismaSelect = options.select && parsePrismaSelect(options.select);
-const prismaInclude = prismaSelect
-    ? undefined
-    : options.relations && parsePrismaInclude(options.relations);
+const prismaInclude = prismaSelect ? undefined : options.relations && parsePrismaInclude(options.relations);
 ```
 
 ## Métodos atômicos e de agregação
 
 O adapter implementa os 12 métodos abstratos pros quais `increment`/`decrement`/`multiply`/`divide`, suas versões `*Many` e `sum`/`average`/`min`/`max` do `VSRepository` delegam: `incrementOne`, `decrementOne`, `multiplyOne`, `divideOne`, `incrementMany`, `decrementMany`, `multiplyMany`, `divideMany`, `sum`, `average`, `min`, `max`.
 
-- `incrementOne`/`decrementOne`/`multiplyOne`/`divideOne` traduzem direto pra escrita atômica nativa de campo único do Prisma — `data: { [field]: { increment: value } }` (e `decrement`/`multiply`/`divide`) — então a operação é avaliada **server-side** contra o valor *atual* do registro (`UPDATE ... SET field = field + value`), e não como um fetch-then-save no cliente. O `update()` do Prisma já retorna a linha refletindo o estado *após* a escrita, então o adapter nunca precisa fazer uma leitura extra.
+- `incrementOne`/`decrementOne`/`multiplyOne`/`divideOne` traduzem direto pra escrita atômica nativa de campo único do Prisma — `data: { [field]: { increment: value } }` (e `decrement`/`multiply`/`divide`) — então a operação é avaliada **server-side** contra o valor _atual_ do registro (`UPDATE ... SET field = field + value`), e não como um fetch-then-save no cliente. O `update()` do Prisma já retorna a linha refletindo o estado _após_ a escrita, então o adapter nunca precisa fazer uma leitura extra.
 - `incrementMany`/`decrementMany`/`multiplyMany`/`divideMany` aplicam essa mesma escrita nativa em **todo** registro que casa com `where`, através do `updateMany` do Prisma, também avaliada server-side. Eles retornam um `{ count }` (`CountResult`) em vez dos registros.
 - `sum`/`average`/`min`/`max` traduzem pro `aggregate()` do Prisma, com `_sum`/`_avg`/`_min`/`_max: { [field]: true }`. O resultado bruto (`number`, `bigint`, uma instância de `Decimal`, ou `null`) é normalizado pra `number | null` — `null` é repassado como está (espelhando o `SUM()`/`AVG()`/`MIN()`/`MAX()` do SQL, que retornam `NULL`, não `0`, sobre um conjunto vazio), e um valor `Decimal`/`DecimalLike` é convertido via seu `.toNumber()`.
 
@@ -234,11 +325,11 @@ const mostExpensive = await productRepository.max("price");
 
 Alguns recursos que esse adapter usa não estão disponíveis em todo banco. O adapter checa todos os recursos abaixo antecipadamente e lança um `VSRepoAdapterError` (code `NOT_SUPPORTED`) antes de tocar no banco.
 
-| Recurso | Providers com suporte | Sem suporte |
-| --- | --- | --- |
-| `ignoreCase` (traduzido pro `mode: "insensitive"` do Prisma; usado pelos métodos dinâmicos `findByXIgnoreCase`) | PostgreSQL, CockroachDB | MySQL, SQLite, SQL Server — MySQL e SQL Server já são case-insensitive por padrão (conforme a collation), então não precisam de `mode`; SQLite só é case-insensitive pra caracteres ASCII |
-| `createManyReturning` / `updateManyReturning` (baseados no `createManyAndReturn`/`updateManyAndReturn` do Prisma) | PostgreSQL, CockroachDB, SQLite | MySQL, SQL Server |
-| `ignoreConflicts: true` no `createMany` / `createManyReturning` (o `skipDuplicates` do Prisma) | PostgreSQL, MySQL, CockroachDB | SQL Server, SQLite |
+| Recurso                                                                                                           | Providers com suporte           | Sem suporte                                                                                                                                                                               |
+| ----------------------------------------------------------------------------------------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ignoreCase` (traduzido pro `mode: "insensitive"` do Prisma; usado pelos métodos dinâmicos `findByXIgnoreCase`)   | PostgreSQL, CockroachDB         | MySQL, SQLite, SQL Server — MySQL e SQL Server já são case-insensitive por padrão (conforme a collation), então não precisam de `mode`; SQLite só é case-insensitive pra caracteres ASCII |
+| `createManyReturning` / `updateManyReturning` (baseados no `createManyAndReturn`/`updateManyAndReturn` do Prisma) | PostgreSQL, CockroachDB, SQLite | MySQL, SQL Server                                                                                                                                                                         |
+| `ignoreConflicts: true` no `createMany` / `createManyReturning` (o `skipDuplicates` do Prisma)                    | PostgreSQL, MySQL, CockroachDB  | SQL Server, SQLite                                                                                                                                                                        |
 
 O operador `like` não é suportado em nenhum provider — o Prisma não tem equivalente, então o adapter lança `NOT_SUPPORTED`. Use `contains`, `startsWith` ou `endsWith`.
 
@@ -297,7 +388,7 @@ O adapter usa o `VSLogger` (de `vsrepo`) internamente: todo método loga uma lin
 
 ## Requisitos
 
-- `vsrepo` ^3.0.0-dev.2
-- `@prisma/client` ^7.10.0
+- `vsrepo` ^3.0.0-dev.3
+- `@prisma/client` ^7.10.1
 - Node.js `>=22`
 - Um banco PostgreSQL, CockroachDB, MySQL, SQLite ou SQL Server (todos cobertos pelos testes de integração)

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 export { VSRepoPrisma7Adapter, VSRepoPrisma7Adapter as Prisma7Adapter } from "./prisma7.adapter.js";
-export type { Relation } from "./types/relation.type.js";
+export type { Relation, DisconnectStrategy, RelationMode, ToManyStrategy, ToOneStrategy, } from "./types/relation.type.js";
 export type { Prisma7OrmTypes } from "./types/prisma7-orm-types.type.js";
 export type { Prisma7ClientLike } from "./types/prisma7-client-like.type.js";
 export type { AdapterRelations } from "./types/adapter-relations.type.js";
 export type { Prisma7AdapterConfig } from "./types/adapter-config.type.js";
 export type { PrismaClientModels } from "./types/prisma-client-models.type.js";
 export type { PrismaProvider } from "./types/prisma-provider.type.js";
+export type { Prisma7GlobalConfig } from "./types/prisma7-global-config.type.js";

package/dist/parsers/data.parser.d.ts

@@ -4,4 +4,4 @@ export interface PrismaWriteData {
     create: PlainObject;
     update: PlainObject;
 }
-export declare function parsePrismaWriteData<T>(obj: PlainObject, pkName: string, relations?: AdapterRelations<T>, omitPkInUpdate?: boolean): PrismaWriteData;
+export declare function parsePrismaWriteData<T>(obj: PlainObject, pkName: string, relations?: AdapterRelations<T>, omitPkInUpdate?: boolean, allowOmitPkWhenNeeded?: boolean): PrismaWriteData;