Add skipDuplicates() scope guard to createDocuments

src/Database/Adapter.php

@@ -33,6 +33,36 @@ abstract class Adapter
 
     protected bool $alterLocks = false;
 
+    protected bool $skipDuplicates = false;
+
+    /**
+     * Run a callback with skipDuplicates enabled.
+     * Duplicate key errors during createDocuments() will be silently skipped
+     * instead of thrown. Nestable — saves and restores previous state.
+     * Pass $enable = false to run the callback without toggling the flag
+     * (useful for conditional forwarding from wrappers like Pool/Mirror).
+     *
+     * @template T
+     * @param callable(): T $callback
+     * @param bool $enable
+     * @return T
+     */
+    public function skipDuplicates(callable $callback, bool $enable = true): mixed
+    {
+        if (!$enable) {
+            return $callback();
+        }
+
+        $previous = $this->skipDuplicates;
+        $this->skipDuplicates = true;
+
+        try {
+            return $callback();
+        } finally {
+            $this->skipDuplicates = $previous;
+        }
+    }
+
     /**
      * @var array<string, mixed>
      */

src/Database/Adapter/Mongo.php

@@ -1449,6 +1449,42 @@ public function castingBefore(Document $collection, Document $document): Documen
         return $document;
     }
 
+    /**
+     * Find existing `_uid` values matching the given filters, fully walking the cursor.
+     *
+     * @param string $name
+     * @param array<string, mixed> $filters
+     * @param int $batchSize Hint: expected max result count — lets MongoDB return everything in one batch
+     * @return array<int, string>
+     *
+     * @throws MongoException
+     */
+    private function findExistingUids(string $name, array $filters, int $batchSize): array
+    {
+        $options = $this->getTransactionOptions([
+            'projection' => ['_uid' => 1],
+            'batchSize' => $batchSize,
+        ]);
+
+        $response = $this->client->find($name, $filters, $options);
+        $uids = [];
+
+        foreach ($response->cursor->firstBatch ?? [] as $doc) {
+            $uids[] = $doc->_uid;
+        }
+
+        $cursorId = $response->cursor->id ?? 0;
+        while ($cursorId != 0) {
+            $more = $this->client->getMore($cursorId, $name, $batchSize);
+            foreach ($more->cursor->nextBatch ?? [] as $doc) {
+                $uids[] = $doc->_uid;
+            }
+            $cursorId = $more->cursor->id ?? 0;
+        }
+
+        return $uids;
+    }
+
     /**
      * Create Documents in batches
      *
@@ -1487,6 +1523,72 @@ public function createDocuments(Document $collection, array $documents): array
             $records[] = $record;
         }
 
+        // Pre-filter duplicates within the session — MongoDB has no INSERT IGNORE,
+        // so sending a duplicate would abort the entire transaction.
+        if ($this->skipDuplicates && !empty($records)) {
+            $tenantPerDoc = $this->sharedTables && $this->tenantPerDocument;
+            $recordKey = fn (array $record): string => $tenantPerDoc
+                ? ($record['_tenant'] ?? $this->getTenant()) . ':' . ($record['_uid'] ?? '')
+                : ($record['_uid'] ?? '');
+
+            $existingKeys = [];
+
+            try {
+                if ($tenantPerDoc) {
+                    $idsByTenant = [];
+                    foreach ($records as $record) {
+                        $uid = $record['_uid'] ?? '';
+                        if ($uid === '') {
+                            continue;
+                        }
+                        $tenant = $record['_tenant'] ?? $this->getTenant();
+                        $idsByTenant[$tenant][] = $uid;
+                    }
+
+                    foreach ($idsByTenant as $tenant => $tenantUids) {
+                        $tenantUids = \array_values(\array_unique($tenantUids));
+                        $filters = ['_uid' => ['$in' => $tenantUids], '_tenant' => $tenant];
+                        foreach ($this->findExistingUids($name, $filters, \count($tenantUids)) as $uid) {
+                            $existingKeys[$tenant . ':' . $uid] = true;
+                        }
+                    }
+                } else {
+                    $uids = \array_values(\array_unique(\array_filter(
+                        \array_map(fn ($r) => $r['_uid'] ?? null, $records),
+                        fn ($v) => $v !== null
+                    )));
+                    if (!empty($uids)) {
+                        $filters = ['_uid' => ['$in' => $uids]];
+                        if ($this->sharedTables) {
+                            $filters['_tenant'] = $this->getTenantFilters($collection->getId());
+                        }
+                        foreach ($this->findExistingUids($name, $filters, \count($uids)) as $uid) {
+                            $existingKeys[$uid] = true;
+                        }
+                    }
+                }
+            } catch (MongoException $e) {
+                throw $this->processException($e);
+            }
+
+            if (!empty($existingKeys)) {
+                $filteredRecords = [];
+                $filteredDocuments = [];
+                foreach ($records as $i => $record) {
+                    if (!isset($existingKeys[$recordKey($record)])) {
+                        $filteredRecords[] = $record;
+                        $filteredDocuments[] = $documents[$i];
+                    }
+                }
+                $records = $filteredRecords;
+                $documents = $filteredDocuments;
+            }
+
+            if (empty($records)) {
+                return [];
+            }
+        }
+
         try {
             $documents = $this->client->insertMany($name, $records, $options);
         } catch (MongoException $e) {

src/Database/Adapter/Pool.php

@@ -43,7 +43,10 @@ public function __construct(UtopiaPool $pool)
     public function delegate(string $method, array $args): mixed
     {
         if ($this->pinnedAdapter !== null) {
-            return $this->pinnedAdapter->{$method}(...$args);
+            return $this->pinnedAdapter->skipDuplicates(
+                fn () => $this->pinnedAdapter->{$method}(...$args),
+                $this->skipDuplicates
+            );
         }
 
         return $this->pool->use(function (Adapter $adapter) use ($method, $args) {
@@ -66,7 +69,10 @@ public function delegate(string $method, array $args): mixed
                 $adapter->setMetadata($key, $value);
             }
 
-            return $adapter->{$method}(...$args);
+            return $adapter->skipDuplicates(
+                fn () => $adapter->{$method}(...$args),
+                $this->skipDuplicates
+            );
         });
     }
 
@@ -146,7 +152,10 @@ public function withTransaction(callable $callback): mixed
 
             $this->pinnedAdapter = $adapter;
             try {
-                return $adapter->withTransaction($callback);
+                return $adapter->skipDuplicates(
+                    fn () => $adapter->withTransaction($callback),
+                    $this->skipDuplicates
+                );
             } finally {
                 $this->pinnedAdapter = null;
             }

src/Database/Adapter/Postgres.php

@@ -1365,6 +1365,35 @@ public function updateDocument(Document $collection, string $id, Document $docum
         return $document;
     }
 
+    protected function getInsertKeyword(): string
+    {
+        return 'INSERT INTO';
+    }
+
+    protected function getInsertSuffix(string $table): string
+    {
+        if (!$this->skipDuplicates) {
+            return '';
+        }
+
+        $conflictTarget = $this->sharedTables ? '("_uid", "_tenant")' : '("_uid")';
+
+        return "ON CONFLICT {$conflictTarget} DO NOTHING";
+    }
+
+    protected function getInsertPermissionsSuffix(): string
+    {
+        if (!$this->skipDuplicates) {
+            return '';
+        }
+
+        $conflictTarget = $this->sharedTables
+            ? '("_type", "_permission", "_document", "_tenant")'
+            : '("_type", "_permission", "_document")';
+
+        return "ON CONFLICT {$conflictTarget} DO NOTHING";
+    }
+
     /**
      * @param string $tableName
      * @param string $columns