From b8ae7bc953d1897994eaa0de7e677687a19e5133 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Thu, 30 Apr 2026 11:24:12 +0100 Subject: [PATCH] Rename OnDuplicate::Upsert -> OnDuplicate::Overwrite MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Maintainer review: align with Appwrite's terminology (skip / overwrite / fail). Public-API breaking change — value 'upsert' becomes 'overwrite', so any pre-1.9.3 consumer of OnDuplicate::Upsert or the 'upsert' string needs to update. Renamed in this repo: - enum case + value - all OnDuplicate::Upsert references in DestinationAppwrite - internal helpers cleanupUpsertOrphans(ForTable) -> cleanupOverwriteOrphans(ForTable) - comment / docblock mentions of 'Upsert-mode' / 'Upsert recreate' - unit test method names testUpsert* -> testOverwrite* Cross-repo follow-up needed in appwrite/appwrite: - app/controllers/api/migrations.php (3 endpoint param descriptions) - src/Appwrite/Platform/Workers/Migrations.php (OnDuplicate reference) - e2e tests passing 'onDuplicate' => 'upsert' - console UI hardcoded option strings (separate repo) --- src/Migration/Destinations/Appwrite.php | 20 ++++++++--------- src/Migration/Destinations/OnDuplicate.php | 4 ++-- .../Unit/General/OnDuplicateTest.php | 22 +++++++++---------- 3 files changed, 23 insertions(+), 23 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index ca0b9cd30b..fb25bb55ea 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -109,7 +109,7 @@ class Appwrite extends Destination private array $rowBuffer = []; /** - * Upsert-mode orphan tracking, keyed by (database, table). Orphans are + * Overwrite-mode orphan tracking, keyed by (database, table). Orphans are * destination keys not in `attributeKeys` / `indexKeys`. Entries removed * after their cleanup runs so the end-of-run sweep only visits tables * that had no rows. @@ -178,7 +178,7 @@ class Appwrite extends Destination ): void { $this->resetRunState(); parent::run($resources, $callback, $rootResourceId, $rootResourceType); - $this->cleanupUpsertOrphans(); + $this->cleanupOverwriteOrphans(); } /** Per-run state must not leak across run() invocations on a reused instance. */ @@ -1056,7 +1056,7 @@ class Appwrite extends Destination $indexMetaId = $this->attributeIndexMetaId($database, $table, $resource->getKey()); // Pre-check + drop runs BEFORE count/validator so the to-be-dropped index isn't included in - // the limit count or in IndexValidator's $tableIndexes (otherwise an Upsert recreate at the + // the limit count or in IndexValidator's $tableIndexes (otherwise an Overwrite recreate at the // ceiling throws "Index limit reached" or "Invalid index" even though the net change is zero). if ($this->onDuplicate !== OnDuplicate::Fail) { $existingIdx = $this->dbForProject->getDocument(self::META_INDEXES, $indexMetaId); @@ -1284,7 +1284,7 @@ class Appwrite extends Destination $dbForDatabases = ($this->getDatabasesDB)($database); // Drop schema orphans before rows land so the Structure validator doesn't reject on orphan required columns. - $this->cleanupUpsertOrphansForTable($this->tableIdentity($database, $table)); + $this->cleanupOverwriteOrphansForTable($this->tableIdentity($database, $table)); // Strip row payload fields the table doesn't declare — guards against orphans surviving in source archives. if ($dbForDatabases->getAdapter()->getSupportForAttributes()) { foreach ($this->rowBuffer as $row) { @@ -1311,7 +1311,7 @@ class Appwrite extends Destination $collectionId = $this->tableCollectionId($database, $table); match ($this->onDuplicate) { - OnDuplicate::Upsert => $dbForDatabases->skipRelationshipsExistCheck( + OnDuplicate::Overwrite => $dbForDatabases->skipRelationshipsExistCheck( fn () => $dbForDatabases->upsertDocuments($collectionId, $this->rowBuffer) ), OnDuplicate::Skip => $dbForDatabases->skipDuplicates( @@ -1699,7 +1699,7 @@ class Appwrite extends Destination string $key, UtopiaDatabase $dbForDatabases, ): void { - if ($this->onDuplicate !== OnDuplicate::Upsert) { + if ($this->onDuplicate !== OnDuplicate::Overwrite) { return; } $tableId = $this->tableIdentity($database, $table); @@ -1716,17 +1716,17 @@ class Appwrite extends Destination } /** End-of-migration sweep — only visits tables that had no rows (rest were cleaned per-table in createRecord). */ - private function cleanupUpsertOrphans(): void + private function cleanupOverwriteOrphans(): void { foreach (\array_keys($this->orphansByTable) as $tableId) { - $this->cleanupUpsertOrphansForTable($tableId); + $this->cleanupOverwriteOrphansForTable($tableId); } } /** Called per-table from createRecord before rows land so Structure validator sees the post-cleanup schema. */ - private function cleanupUpsertOrphansForTable(string $tableId): void + private function cleanupOverwriteOrphansForTable(string $tableId): void { - if ($this->onDuplicate !== OnDuplicate::Upsert) { + if ($this->onDuplicate !== OnDuplicate::Overwrite) { return; } if (!isset($this->orphansByTable[$tableId])) { diff --git a/src/Migration/Destinations/OnDuplicate.php b/src/Migration/Destinations/OnDuplicate.php index 69b4cdf8f2..3ba945c005 100644 --- a/src/Migration/Destinations/OnDuplicate.php +++ b/src/Migration/Destinations/OnDuplicate.php @@ -13,7 +13,7 @@ enum OnDuplicate: string { case Fail = 'fail'; case Skip = 'skip'; - case Upsert = 'upsert'; + case Overwrite = 'overwrite'; /** * @return list @@ -39,7 +39,7 @@ enum OnDuplicate: string return match ($this) { self::Fail => SchemaAction::Create, self::Skip => SchemaAction::Tolerate, - self::Upsert => $this->sourceIsNewer($sourceUpdatedAt, $destUpdatedAt) + self::Overwrite => $this->sourceIsNewer($sourceUpdatedAt, $destUpdatedAt) ? SchemaAction::UpdateInPlace : SchemaAction::Tolerate, }; diff --git a/tests/Migration/Unit/General/OnDuplicateTest.php b/tests/Migration/Unit/General/OnDuplicateTest.php index cc32625823..0141cb5d33 100644 --- a/tests/Migration/Unit/General/OnDuplicateTest.php +++ b/tests/Migration/Unit/General/OnDuplicateTest.php @@ -59,7 +59,7 @@ class OnDuplicateTest extends TestCase ); } - public function testUpsertSourceNewerUpdatesInPlace(): void + public function testOverwriteSourceNewerUpdatesInPlace(): void { // Source updatedAt strictly newer than dest → UpdateInPlace. The // caller (DestinationAppwrite) follows up with attribute/index spec @@ -67,7 +67,7 @@ class OnDuplicateTest extends TestCase // express the change. $this->assertSame( SchemaAction::UpdateInPlace, - OnDuplicate::Upsert->resolveSchemaAction( + OnDuplicate::Overwrite->resolveSchemaAction( exists: true, sourceUpdatedAt: '2026-04-23T10:00:00.000+00:00', destUpdatedAt: '2026-04-23T09:59:59.000+00:00', @@ -75,12 +75,12 @@ class OnDuplicateTest extends TestCase ); } - public function testUpsertSourceEqualTolerates(): void + public function testOverwriteSourceEqualTolerates(): void { $when = '2026-04-23T10:00:00.000+00:00'; $this->assertSame( SchemaAction::Tolerate, - OnDuplicate::Upsert->resolveSchemaAction( + OnDuplicate::Overwrite->resolveSchemaAction( exists: true, sourceUpdatedAt: $when, destUpdatedAt: $when, @@ -88,13 +88,13 @@ class OnDuplicateTest extends TestCase ); } - public function testUpsertSourceOlderTolerates(): void + public function testOverwriteSourceOlderTolerates(): void { // Dest is ahead — don't roll back. Avoids overwriting newer // destination edits with stale source data. $this->assertSame( SchemaAction::Tolerate, - OnDuplicate::Upsert->resolveSchemaAction( + OnDuplicate::Overwrite->resolveSchemaAction( exists: true, sourceUpdatedAt: '2026-04-23T09:00:00.000+00:00', destUpdatedAt: '2026-04-23T10:00:00.000+00:00', @@ -102,13 +102,13 @@ class OnDuplicateTest extends TestCase ); } - public function testUpsertNoTimestampsTolerates(): void + public function testOverwriteNoTimestampsTolerates(): void { // No timestamps provided at all → no information to act on. Conservative: // Tolerate rather than risk a destructive update on uncertain input. $this->assertSame( SchemaAction::Tolerate, - OnDuplicate::Upsert->resolveSchemaAction(exists: true), + OnDuplicate::Overwrite->resolveSchemaAction(exists: true), ); } @@ -132,13 +132,13 @@ class OnDuplicateTest extends TestCase } #[DataProvider('unparseableTimestampPairs')] - public function testUpsertUnparseableUpdatedAtTolerates(?string $source, ?string $dest): void + public function testOverwriteUnparseableUpdatedAtTolerates(?string $source, ?string $dest): void { // Conservative: unparseable updatedAt preserves existing destination // rather than risk a destructive update on garbage input. $this->assertSame( SchemaAction::Tolerate, - OnDuplicate::Upsert->resolveSchemaAction( + OnDuplicate::Overwrite->resolveSchemaAction( exists: true, sourceUpdatedAt: $source, destUpdatedAt: $dest, @@ -150,6 +150,6 @@ class OnDuplicateTest extends TestCase { // The values() helper is consumed by API/SDK param validators; this // protects against an accidental case-rename or reorder. - $this->assertSame(['fail', 'skip', 'upsert'], OnDuplicate::values()); + $this->assertSame(['fail', 'skip', 'overwrite'], OnDuplicate::values()); } }