Rename OnDuplicate::Upsert -> OnDuplicate::Overwrite

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)
This commit is contained in:
Prem Palanisamy committed 2026-04-30 11:24:12 +01:00
1 parent 5520cb2585
commit b8ae7bc953
3 files changed
+23 -23

No files matched your search

+10 -10
View File
@@ -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])) {
+2 -2
View File
@@ -13,7 +13,7 @@ enum OnDuplicate: string
{
case Fail = 'fail';
case Skip = 'skip';
case Upsert = 'upsert';
case Overwrite = 'overwrite';
/**
* @return list<string>
@@ -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,
};
@@ -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());
}
}