From 6ec2c45a4077d9452ae32e4faa1b49375ad77cae Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Tue, 28 Apr 2026 05:43:11 +0100 Subject: [PATCH] =?UTF-8?q?Drop=20createdAt=20handling=20=E2=80=94=20spec-?= =?UTF-8?q?match=20guard=20+=20sourceIsNewer=20cover=20everything?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit resolveSchemaAction's createdAt branch became redundant once the spec-match guard landed. The flow: - resolveSchemaAction returns Create / Tolerate / UpdateInPlace based purely on existence and updatedAt-newer. - The destination's spec-match guard overrides UpdateInPlace to Tolerate when source and dest have identical spec. - Inner attribute/index spec checks fall through to drop+recreate when the SDK can't express the change in place. End-state behavior on every scenario is identical (verified before this commit). The createdAt path was extra work that produced the same outcome via a longer route. Removed: - $sourceCreatedAt / $destCreatedAt / $canDrop params from resolveSchemaAction - createdAtDiffers private helper - SchemaAction::DropAndRecreate enum case (no longer returned by resolveSchemaAction; inner fallthrough drops directly) - 4 call sites in Appwrite.php drop the createdAt args + canDrop: named arg + DropAndRecreate match arm + DropAndRecreate post-match if-clause - ~13 createdAt-specific unit tests; remaining 19 test the exists × mode × updatedAt matrix --- src/Migration/Destinations/Appwrite.php | 32 ++--- src/Migration/Destinations/OnDuplicate.php | 44 +------ .../Unit/General/OnDuplicateTest.php | 123 +++--------------- 3 files changed, 33 insertions(+), 166 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index 1a1acfbd5d..d215452d8d 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -68,7 +68,7 @@ class Appwrite extends Destination private const META_ATTRIBUTES = 'attributes'; private const META_INDEXES = 'indexes'; - /** Fields the SDK's per-type updateXAttribute endpoints don't expose; a change here forces DropAndRecreate. */ + /** Fields the SDK's per-type updateXAttribute endpoints don't expose; a change here forces drop+recreate. */ private const ATTRIBUTE_NON_SDK_FIELDS = [ 'type', 'array', @@ -493,11 +493,8 @@ class Appwrite extends Destination $existing = $this->dbForProject->getDocument(self::META_DATABASES, $resource->getId()); $action = $this->onDuplicate->resolveSchemaAction( !$existing->isEmpty(), - $createdAt, - $existing->getCreatedAt(), $updatedAt, $existing->getUpdatedAt(), - canDrop: false, ); // Spec match → skip work. Create excluded; nothing on dest to match against. if ($action !== SchemaAction::Create && $this->databaseSpecMatches($existing, $resource)) { @@ -523,7 +520,7 @@ class Appwrite extends Destination $resource->setSequence($existing->getSequence()); return true; })(), - SchemaAction::Create, SchemaAction::DropAndRecreate => null, + SchemaAction::Create => null, }; if ($earlyReturn !== null) { return $earlyReturn; @@ -618,11 +615,8 @@ class Appwrite extends Destination ); $action = $this->onDuplicate->resolveSchemaAction( !$existing->isEmpty(), - $createdAt, - $existing->getCreatedAt(), $updatedAt, $existing->getUpdatedAt(), - canDrop: false, ); // Spec match → skip work. Create excluded; nothing on dest to match against. if ($action !== SchemaAction::Create && $this->tableSpecMatches($existing, $resource)) { @@ -651,7 +645,7 @@ class Appwrite extends Destination $resource->setSequence($existing->getSequence()); return true; })(), - SchemaAction::Create, SchemaAction::DropAndRecreate => null, + SchemaAction::Create => null, }; if ($earlyReturn !== null) { return $earlyReturn; @@ -814,11 +808,8 @@ class Appwrite extends Destination $existingAttr = $this->dbForProject->getDocument(self::META_ATTRIBUTES, $attributeMetaId); $action = $this->onDuplicate->resolveSchemaAction( !$existingAttr->isEmpty(), - $createdAt, - $existingAttr->getCreatedAt(), $updatedAt, $existingAttr->getUpdatedAt(), - canDrop: true, ); // Spec match → skip work. Create excluded; nothing on dest to match against. if ($action !== SchemaAction::Create && $this->attributeSpecMatches($existingAttr, $resource, $type, $isRelationship)) { @@ -836,7 +827,7 @@ class Appwrite extends Destination : $this->updateAttributeInPlace($database, $table, $resource, $type, $updatedAt, $existingAttr, $dbForDatabases)) ? true : null, - SchemaAction::DropAndRecreate, SchemaAction::Create => null, + SchemaAction::Create => null, }; if ($earlyReturn !== null) { if ($twoWayPairKey !== null) { @@ -845,7 +836,7 @@ class Appwrite extends Destination return $earlyReturn; } - if ($action === SchemaAction::DropAndRecreate || $action === SchemaAction::UpdateInPlace) { + if ($action === SchemaAction::UpdateInPlace) { $this->dropAttributeForRecreate($database, $table, $resource, $dbForDatabases); } } @@ -1135,11 +1126,8 @@ class Appwrite extends Destination $existingIdx = $this->dbForProject->getDocument(self::META_INDEXES, $indexMetaId); $action = $this->onDuplicate->resolveSchemaAction( !$existingIdx->isEmpty(), - $createdAt, - $existingIdx->getCreatedAt(), $updatedAt, $existingIdx->getUpdatedAt(), - canDrop: true, ); // Spec match → skip work. Create excluded; nothing on dest to match against. if ($action !== SchemaAction::Create && $this->indexSpecMatches($existingIdx, $resource)) { @@ -1153,13 +1141,13 @@ class Appwrite extends Destination $resource->setStatus(Resource::STATUS_SKIPPED, 'Already exists on destination'); return false; })(), - SchemaAction::UpdateInPlace, SchemaAction::DropAndRecreate, SchemaAction::Create => null, + SchemaAction::UpdateInPlace, SchemaAction::Create => null, }; if ($earlyReturn !== null) { return $earlyReturn; } - if ($action === SchemaAction::DropAndRecreate || $action === SchemaAction::UpdateInPlace) { + if ($action === SchemaAction::UpdateInPlace) { $dbForDatabases->deleteIndex($this->tableCollectionId($database, $table), $resource->getKey()); $this->dbForProject->deleteDocument(self::META_INDEXES, $indexMetaId); $this->dbForProject->purgeCachedDocument($this->databaseCollectionId($database), $table->getId()); @@ -1368,7 +1356,7 @@ class Appwrite extends Destination $this->purgeTableCaches($database, $table, $dbForDatabases); } - /** Returns false when the source change isn't SDK-expressible — caller falls through to DropAndRecreate. */ + /** Returns false when the source change isn't SDK-expressible — caller falls through to drop+recreate. */ private function updateAttributeInPlace( UtopiaDocument $database, UtopiaDocument $table, @@ -1430,7 +1418,7 @@ class Appwrite extends Destination } /** - * Returns false when the source change isn't SDK-expressible — caller falls through to DropAndRecreate. + * Returns false when the source change isn't SDK-expressible — caller falls through to drop+recreate. * One-way + onDelete change is also rejected: utopia's updateRelationship partner-cascade throws on one-way. */ private function updateRelationshipInPlace( @@ -1542,7 +1530,7 @@ class Appwrite extends Destination return $sourcePerms === $destPerms; } - /** Full-spec equality: short-circuits both DropAndRecreate and UpdateInPlace to Tolerate when nothing changed. */ + /** Full-spec equality: short-circuits UpdateInPlace to Tolerate when nothing changed. */ private function attributeSpecMatches(UtopiaDocument $existing, Column|Attribute $resource, string $type, bool $isRelationship): bool { if ($existing->getAttribute('type') !== $type) { diff --git a/src/Migration/Destinations/OnDuplicate.php b/src/Migration/Destinations/OnDuplicate.php index 744b2e1561..69b4cdf8f2 100644 --- a/src/Migration/Destinations/OnDuplicate.php +++ b/src/Migration/Destinations/OnDuplicate.php @@ -6,7 +6,6 @@ enum SchemaAction { case Create; case Tolerate; - case DropAndRecreate; case UpdateInPlace; } @@ -25,16 +24,14 @@ enum OnDuplicate: string } /** - * $canDrop = false (containers like databases/tables) forces UpdateInPlace - * even on createdAt-different — dropping would orphan children. + * Coarse routing for re-migration. The caller follows up with a spec-match + * check that overrides UpdateInPlace to Tolerate when source and dest + * already have identical spec — see DestinationAppwrite for the full flow. */ public function resolveSchemaAction( bool $exists, - ?string $sourceCreatedAt = null, - ?string $destCreatedAt = null, ?string $sourceUpdatedAt = null, ?string $destUpdatedAt = null, - bool $canDrop = false, ): SchemaAction { if (!$exists) { return SchemaAction::Create; @@ -42,41 +39,12 @@ enum OnDuplicate: string return match ($this) { self::Fail => SchemaAction::Create, self::Skip => SchemaAction::Tolerate, - self::Upsert => $this->resolveUpsertAction( - $sourceCreatedAt, - $destCreatedAt, - $sourceUpdatedAt, - $destUpdatedAt, - $canDrop, - ), + self::Upsert => $this->sourceIsNewer($sourceUpdatedAt, $destUpdatedAt) + ? SchemaAction::UpdateInPlace + : SchemaAction::Tolerate, }; } - private function resolveUpsertAction( - ?string $sourceCreatedAt, - ?string $destCreatedAt, - ?string $sourceUpdatedAt, - ?string $destUpdatedAt, - bool $canDrop, - ): SchemaAction { - if ($this->createdAtDiffers($sourceCreatedAt, $destCreatedAt)) { - return $canDrop ? SchemaAction::DropAndRecreate : SchemaAction::UpdateInPlace; - } - - if ($this->sourceIsNewer($sourceUpdatedAt, $destUpdatedAt)) { - return SchemaAction::UpdateInPlace; - } - - return SchemaAction::Tolerate; - } - - private function createdAtDiffers(?string $source, ?string $dest): bool - { - $src = $this->parseTimestamp($source); - $dst = $this->parseTimestamp($dest); - return $src !== null && $dst !== null && $src !== $dst; - } - private function sourceIsNewer(?string $source, ?string $dest): bool { $src = $this->parseTimestamp($source); diff --git a/tests/Migration/Unit/General/OnDuplicateTest.php b/tests/Migration/Unit/General/OnDuplicateTest.php index c8b10e1a4a..cc32625823 100644 --- a/tests/Migration/Unit/General/OnDuplicateTest.php +++ b/tests/Migration/Unit/General/OnDuplicateTest.php @@ -9,19 +9,10 @@ use Utopia\Migration\Destinations\SchemaAction; /** * OnDuplicate::resolveSchemaAction is the load-bearing decision point for - * re-migration tolerance. These tests lock the mode × existence × createdAt × - * updatedAt × canDrop matrix so a future refactor can't silently shift the - * mapping. - * - * Decision rules under Upsert (with $exists = true): - * - createdAt differs → resource was deleted+recreated on source. Caller can - * drop and recreate (canDrop=true) or update in place (canDrop=false; for - * containers like databases/tables which would lose children on drop). - * - createdAt same + updatedAt newer → metadata-only edit. UpdateInPlace. - * The caller checks whether changed fields are SDK-updatable; if not it - * falls through to DropAndRecreate. - * - createdAt same + updatedAt equal/older → Tolerate. - * - Unparseable createdAt or updatedAt → conservative; treat as if no diff. + * re-migration tolerance. The destination then runs a spec-match guard that + * overrides UpdateInPlace to Tolerate when source and dest already have + * identical spec — see DestinationAppwrite. These tests lock the + * mode × existence × updatedAt matrix. */ class OnDuplicateTest extends TestCase { @@ -49,15 +40,11 @@ class OnDuplicateTest extends TestCase public function testSkipAlwaysToleratesExisting(): void { - // Skip must ignore createdAt/updatedAt entirely — it's the "don't - // touch" contract. Exercise both source-newer and dest-newer to prove - // comparisons aren't consulted. + // Skip must ignore updatedAt entirely — it's the "don't touch" contract. $this->assertSame( SchemaAction::Tolerate, OnDuplicate::Skip->resolveSchemaAction( exists: true, - sourceCreatedAt: '2020-01-01T00:00:00.000+00:00', - destCreatedAt: '2026-01-01T00:00:00.000+00:00', sourceUpdatedAt: '2026-01-01T00:00:00.000+00:00', destUpdatedAt: '2020-01-01T00:00:00.000+00:00', ), @@ -72,73 +59,36 @@ class OnDuplicateTest extends TestCase ); } - public function testUpsertCreatedAtDiffersOnLeafDropsAndRecreates(): void + public function testUpsertSourceNewerUpdatesInPlace(): void { - // canDrop: true + createdAt differs → leaf was deleted/recreated on - // source. Drop the destination's incarnation and create fresh. - $this->assertSame( - SchemaAction::DropAndRecreate, - OnDuplicate::Upsert->resolveSchemaAction( - exists: true, - sourceCreatedAt: '2026-04-23T10:00:00.000+00:00', - destCreatedAt: '2026-04-20T10:00:00.000+00:00', - canDrop: true, - ), - ); - } - - public function testUpsertCreatedAtDiffersOnContainerUpdatesInPlace(): void - { - // Default canDrop: false (containers like databases/tables). Even on - // createdAt diff, drop is forbidden — children would be lost. Fall - // back to UpdateInPlace. + // Source updatedAt strictly newer than dest → UpdateInPlace. The + // caller (DestinationAppwrite) follows up with attribute/index spec + // checks and falls through to drop+recreate when the SDK can't + // express the change. $this->assertSame( SchemaAction::UpdateInPlace, OnDuplicate::Upsert->resolveSchemaAction( exists: true, - sourceCreatedAt: '2026-04-23T10:00:00.000+00:00', - destCreatedAt: '2026-04-20T10:00:00.000+00:00', - ), - ); - } - - public function testUpsertCreatedAtSameUpdatedAtNewerUpdatesInPlace(): void - { - // Same createdAt + newer updatedAt → metadata-only edit on the same - // physical resource. UpdateInPlace; caller checks whether the changed - // fields are SDK-updatable and falls back to DropAndRecreate if not. - $this->assertSame( - SchemaAction::UpdateInPlace, - OnDuplicate::Upsert->resolveSchemaAction( - exists: true, - sourceCreatedAt: '2026-04-20T10:00:00.000+00:00', - destCreatedAt: '2026-04-20T10:00:00.000+00:00', sourceUpdatedAt: '2026-04-23T10:00:00.000+00:00', destUpdatedAt: '2026-04-23T09:59:59.000+00:00', - canDrop: true, ), ); } - public function testUpsertCreatedAtSameUpdatedAtEqualTolerates(): void + public function testUpsertSourceEqualTolerates(): void { - // Same createdAt + same updatedAt → nothing changed. Skip the work. - $created = '2026-04-20T10:00:00.000+00:00'; - $updated = '2026-04-23T10:00:00.000+00:00'; + $when = '2026-04-23T10:00:00.000+00:00'; $this->assertSame( SchemaAction::Tolerate, OnDuplicate::Upsert->resolveSchemaAction( exists: true, - sourceCreatedAt: $created, - destCreatedAt: $created, - sourceUpdatedAt: $updated, - destUpdatedAt: $updated, - canDrop: true, + sourceUpdatedAt: $when, + destUpdatedAt: $when, ), ); } - public function testUpsertCreatedAtSameUpdatedAtOlderTolerates(): void + public function testUpsertSourceOlderTolerates(): void { // Dest is ahead — don't roll back. Avoids overwriting newer // destination edits with stale source data. @@ -146,11 +96,8 @@ class OnDuplicateTest extends TestCase SchemaAction::Tolerate, OnDuplicate::Upsert->resolveSchemaAction( exists: true, - sourceCreatedAt: '2026-04-20T10:00:00.000+00:00', - destCreatedAt: '2026-04-20T10:00:00.000+00:00', sourceUpdatedAt: '2026-04-23T09:00:00.000+00:00', destUpdatedAt: '2026-04-23T10:00:00.000+00:00', - canDrop: true, ), ); } @@ -158,29 +105,10 @@ class OnDuplicateTest extends TestCase public function testUpsertNoTimestampsTolerates(): void { // No timestamps provided at all → no information to act on. Conservative: - // Tolerate rather than risk destructive action on uncertain input. + // Tolerate rather than risk a destructive update on uncertain input. $this->assertSame( SchemaAction::Tolerate, - OnDuplicate::Upsert->resolveSchemaAction( - exists: true, - canDrop: true, - ), - ); - } - - public function testUpsertOnlyUpdatedAtNewerWithoutCreatedAtUpdatesInPlace(): void - { - // CreatedAt missing on either side (e.g. older Appwrite versions, CSV - // sources): can't detect "recreated", so the only signal is updatedAt. - // Newer source → UpdateInPlace path (caller validates SDK-updatability). - $this->assertSame( - SchemaAction::UpdateInPlace, - OnDuplicate::Upsert->resolveSchemaAction( - exists: true, - sourceUpdatedAt: '2026-04-23T10:00:00.000+00:00', - destUpdatedAt: '2026-04-23T09:59:59.000+00:00', - canDrop: true, - ), + OnDuplicate::Upsert->resolveSchemaAction(exists: true), ); } @@ -203,23 +131,6 @@ class OnDuplicateTest extends TestCase ]; } - #[DataProvider('unparseableTimestampPairs')] - public function testUpsertUnparseableCreatedAtDoesNotTriggerDrop(?string $source, ?string $dest): void - { - // Unparseable createdAt → don't trigger DropAndRecreate. With - // updatedAt also absent, falls through to Tolerate. Safety net for - // sources that emit malformed timestamps. - $this->assertSame( - SchemaAction::Tolerate, - OnDuplicate::Upsert->resolveSchemaAction( - exists: true, - sourceCreatedAt: $source, - destCreatedAt: $dest, - canDrop: true, - ), - ); - } - #[DataProvider('unparseableTimestampPairs')] public function testUpsertUnparseableUpdatedAtTolerates(?string $source, ?string $dest): void {