DestinationAppwrite: add overwrite and skip params

Per Jake's spec, migration destinations accept two new behavior flags:

- overwrite=true → use upsertDocuments() instead of createDocuments()
  Replaces existing rows with the imported values. Naturally handles
  duplicate ids.

- skip=true → wrap createDocuments() in skipDuplicates() scope guard.
  Silently no-ops duplicate ids at the adapter layer (INSERT IGNORE
  equivalent). Existing rows are preserved.

Default (both false): plain createDocuments, fails fast on
DuplicateException. Original behavior, unchanged for existing callers.

Precedence when both set: overwrite wins (upsert subsumes skip).

The existing skipRelationshipsExistCheck() FK-guard wrapper is
preserved in all three branches.

Author: premtsd-code

src/Migration/Destinations/Appwrite.php

@@ -92,14 +92,18 @@ class Appwrite extends Destination
      * @param UtopiaDatabase $dbForProject
      * @param callable(UtopiaDocument $database):UtopiaDatabase $getDatabasesDB
      * @param array<array<string, mixed>> $collectionStructure
+     * @param bool $overwrite When true, replace existing rows by calling upsertDocuments instead of createDocuments.
+     * @param bool $skip When true, silently ignore duplicate-id rows by wrapping createDocuments in skipDuplicates.
      */
     public function __construct(
         string $project,
         string $endpoint,
         string $key,
         protected UtopiaDatabase $dbForProject,
         callable $getDatabasesDB,
-        protected array $collectionStructure
+        protected array $collectionStructure,
+        protected bool $overwrite = false,
+        protected bool $skip = false,
     ) {
         $this->project = $project;
         $this->endpoint = $endpoint;
@@ -1067,14 +1071,27 @@ protected function createRecord(Row $resource, bool $isLast): bool
                         }
                     }
                 }
-                $dbForDatabases->skipDuplicates(
-                    fn () => $dbForDatabases->skipRelationshipsExistCheck(
-                        fn () => $dbForDatabases->createDocuments(
-                            'database_' . $databaseInternalId . '_collection_' . $tableInternalId,
-                            $this->rowBuffer
+                $collectionId = 'database_' . $databaseInternalId . '_collection_' . $tableInternalId;
+
+                if ($this->overwrite) {
+                    // Replace existing rows with the imported values. Upsert naturally
+                    // handles duplicates so skipDuplicates is unnecessary here.
+                    $dbForDatabases->skipRelationshipsExistCheck(
+                        fn () => $dbForDatabases->upsertDocuments($collectionId, $this->rowBuffer)
+                    );
+                } elseif ($this->skip) {
+                    // Silently ignore duplicates via the adapter-level INSERT IGNORE equivalent.
+                    $dbForDatabases->skipDuplicates(
+                        fn () => $dbForDatabases->skipRelationshipsExistCheck(
+                            fn () => $dbForDatabases->createDocuments($collectionId, $this->rowBuffer)
                         )
-                    )
-                );
+                    );
+                } else {
+                    // Default: fail fast on duplicate ids (original behavior).
+                    $dbForDatabases->skipRelationshipsExistCheck(
+                        fn () => $dbForDatabases->createDocuments($collectionId, $this->rowBuffer)
+                    );
+                }
 
             } finally {
                 $this->rowBuffer = [];