Drop createdAt handling — spec-match guard + sourceIsNewer cover everything

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
This commit is contained in:
Prem Palanisamy committed 2026-04-28 05:43:11 +01:00
1 parent 36a1acf750
commit 6ec2c45a40
3 files changed
+33 -166

No files matched your search

+10 -22
View File
@@ -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) {
+6 -38
View File
@@ -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);
+17 -106
View File
@@ -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
{