feat: add onDuplicate option to DestinationAppwrite

src/Migration/Destinations/Appwrite.php

@@ -92,14 +92,16 @@ class Appwrite extends Destination
      * @param UtopiaDatabase $dbForProject
      * @param callable(UtopiaDocument $database):UtopiaDatabase $getDatabasesDB
      * @param array<array<string, mixed>> $collectionStructure
+     * @param OnDuplicate $onDuplicate Behavior when a row with an existing $id is encountered.
      */
     public function __construct(
         string $project,
         string $endpoint,
         string $key,
         protected UtopiaDatabase $dbForProject,
         callable $getDatabasesDB,
-        protected array $collectionStructure
+        protected array $collectionStructure,
+        protected OnDuplicate $onDuplicate = OnDuplicate::Fail,
     ) {
         $this->project = $project;
         $this->endpoint = $endpoint;
@@ -1067,10 +1069,21 @@ protected function createRecord(Row $resource, bool $isLast): bool
                         }
                     }
                 }
-                $dbForDatabases->skipRelationshipsExistCheck(fn () => $dbForDatabases->createDocuments(
-                    'database_' . $databaseInternalId . '_collection_' . $tableInternalId,
-                    $this->rowBuffer
-                ));
+                $collectionId = 'database_' . $databaseInternalId . '_collection_' . $tableInternalId;
+
+                match ($this->onDuplicate) {
+                    OnDuplicate::Upsert => $dbForDatabases->skipRelationshipsExistCheck(
+                        fn () => $dbForDatabases->upsertDocuments($collectionId, $this->rowBuffer)
+                    ),
+                    OnDuplicate::Skip => $dbForDatabases->skipDuplicates(
+                        fn () => $dbForDatabases->skipRelationshipsExistCheck(
+                            fn () => $dbForDatabases->createDocuments($collectionId, $this->rowBuffer)
+                        )
+                    ),
+                    OnDuplicate::Fail => $dbForDatabases->skipRelationshipsExistCheck(
+                        fn () => $dbForDatabases->createDocuments($collectionId, $this->rowBuffer)
+                    ),
+                };
 
             } finally {
                 $this->rowBuffer = [];

src/Migration/Destinations/OnDuplicate.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace Utopia\Migration\Destinations;
+
+/**
+ * Behavior when a destination row with an existing ID is encountered.
+ */
+enum OnDuplicate: string
+{
+    case Fail = 'fail';
+    case Skip = 'skip';
+    case Upsert = 'upsert';
+
+    /**
+     * @return array<string>
+     */
+    public static function values(): array
+    {
+        return \array_map(fn (self $case) => $case->value, self::cases());
+    }
+}