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 = []; 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 * destination keys not in `attributeKeys` / `indexKeys`. Entries removed
* after their cleanup runs so the end-of-run sweep only visits tables * after their cleanup runs so the end-of-run sweep only visits tables
* that had no rows. * that had no rows.
@@ -178,7 +178,7 @@ class Appwrite extends Destination
): void { ): void {
$this->resetRunState(); $this->resetRunState();
parent::run($resources, $callback, $rootResourceId, $rootResourceType); parent::run($resources, $callback, $rootResourceId, $rootResourceType);
$this->cleanupUpsertOrphans(); $this->cleanupOverwriteOrphans();
} }
/** Per-run state must not leak across run() invocations on a reused instance. */ /** 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()); $indexMetaId = $this->attributeIndexMetaId($database, $table, $resource->getKey());
// Pre-check + drop runs BEFORE count/validator so the to-be-dropped index isn't included in // 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). // ceiling throws "Index limit reached" or "Invalid index" even though the net change is zero).
if ($this->onDuplicate !== OnDuplicate::Fail) { if ($this->onDuplicate !== OnDuplicate::Fail) {
$existingIdx = $this->dbForProject->getDocument(self::META_INDEXES, $indexMetaId); $existingIdx = $this->dbForProject->getDocument(self::META_INDEXES, $indexMetaId);
@@ -1284,7 +1284,7 @@ class Appwrite extends Destination
$dbForDatabases = ($this->getDatabasesDB)($database); $dbForDatabases = ($this->getDatabasesDB)($database);
// Drop schema orphans before rows land so the Structure validator doesn't reject on orphan required columns. // 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. // Strip row payload fields the table doesn't declare — guards against orphans surviving in source archives.
if ($dbForDatabases->getAdapter()->getSupportForAttributes()) { if ($dbForDatabases->getAdapter()->getSupportForAttributes()) {
foreach ($this->rowBuffer as $row) { foreach ($this->rowBuffer as $row) {
@@ -1311,7 +1311,7 @@ class Appwrite extends Destination
$collectionId = $this->tableCollectionId($database, $table); $collectionId = $this->tableCollectionId($database, $table);
match ($this->onDuplicate) { match ($this->onDuplicate) {
OnDuplicate::Upsert => $dbForDatabases->skipRelationshipsExistCheck( OnDuplicate::Overwrite => $dbForDatabases->skipRelationshipsExistCheck(
fn () => $dbForDatabases->upsertDocuments($collectionId, $this->rowBuffer) fn () => $dbForDatabases->upsertDocuments($collectionId, $this->rowBuffer)
), ),
OnDuplicate::Skip => $dbForDatabases->skipDuplicates( OnDuplicate::Skip => $dbForDatabases->skipDuplicates(
@@ -1699,7 +1699,7 @@ class Appwrite extends Destination
string $key, string $key,
UtopiaDatabase $dbForDatabases, UtopiaDatabase $dbForDatabases,
): void { ): void {
if ($this->onDuplicate !== OnDuplicate::Upsert) { if ($this->onDuplicate !== OnDuplicate::Overwrite) {
return; return;
} }
$tableId = $this->tableIdentity($database, $table); $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). */ /** 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) { 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. */ /** 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; return;
} }
if (!isset($this->orphansByTable[$tableId])) { if (!isset($this->orphansByTable[$tableId])) {
+2 -2
View File
@@ -13,7 +13,7 @@ enum OnDuplicate: string
{ {
case Fail = 'fail'; case Fail = 'fail';
case Skip = 'skip'; case Skip = 'skip';
case Upsert = 'upsert'; case Overwrite = 'overwrite';
/** /**
* @return list<string> * @return list<string>
@@ -39,7 +39,7 @@ enum OnDuplicate: string
return match ($this) { return match ($this) {
self::Fail => SchemaAction::Create, self::Fail => SchemaAction::Create,
self::Skip => SchemaAction::Tolerate, self::Skip => SchemaAction::Tolerate,
self::Upsert => $this->sourceIsNewer($sourceUpdatedAt, $destUpdatedAt) self::Overwrite => $this->sourceIsNewer($sourceUpdatedAt, $destUpdatedAt)
? SchemaAction::UpdateInPlace ? SchemaAction::UpdateInPlace
: SchemaAction::Tolerate, : 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 // Source updatedAt strictly newer than dest → UpdateInPlace. The
// caller (DestinationAppwrite) follows up with attribute/index spec // caller (DestinationAppwrite) follows up with attribute/index spec
@@ -67,7 +67,7 @@ class OnDuplicateTest extends TestCase
// express the change. // express the change.
$this->assertSame( $this->assertSame(
SchemaAction::UpdateInPlace, SchemaAction::UpdateInPlace,
OnDuplicate::Upsert->resolveSchemaAction( OnDuplicate::Overwrite->resolveSchemaAction(
exists: true, exists: true,
sourceUpdatedAt: '2026-04-23T10:00:00.000+00:00', sourceUpdatedAt: '2026-04-23T10:00:00.000+00:00',
destUpdatedAt: '2026-04-23T09:59:59.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'; $when = '2026-04-23T10:00:00.000+00:00';
$this->assertSame( $this->assertSame(
SchemaAction::Tolerate, SchemaAction::Tolerate,
OnDuplicate::Upsert->resolveSchemaAction( OnDuplicate::Overwrite->resolveSchemaAction(
exists: true, exists: true,
sourceUpdatedAt: $when, sourceUpdatedAt: $when,
destUpdatedAt: $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 // Dest is ahead — don't roll back. Avoids overwriting newer
// destination edits with stale source data. // destination edits with stale source data.
$this->assertSame( $this->assertSame(
SchemaAction::Tolerate, SchemaAction::Tolerate,
OnDuplicate::Upsert->resolveSchemaAction( OnDuplicate::Overwrite->resolveSchemaAction(
exists: true, exists: true,
sourceUpdatedAt: '2026-04-23T09:00:00.000+00:00', sourceUpdatedAt: '2026-04-23T09:00:00.000+00:00',
destUpdatedAt: '2026-04-23T10: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: // No timestamps provided at all → no information to act on. Conservative:
// Tolerate rather than risk a destructive update on uncertain input. // Tolerate rather than risk a destructive update on uncertain input.
$this->assertSame( $this->assertSame(
SchemaAction::Tolerate, SchemaAction::Tolerate,
OnDuplicate::Upsert->resolveSchemaAction(exists: true), OnDuplicate::Overwrite->resolveSchemaAction(exists: true),
); );
} }
@@ -132,13 +132,13 @@ class OnDuplicateTest extends TestCase
} }
#[DataProvider('unparseableTimestampPairs')] #[DataProvider('unparseableTimestampPairs')]
public function testUpsertUnparseableUpdatedAtTolerates(?string $source, ?string $dest): void public function testOverwriteUnparseableUpdatedAtTolerates(?string $source, ?string $dest): void
{ {
// Conservative: unparseable updatedAt preserves existing destination // Conservative: unparseable updatedAt preserves existing destination
// rather than risk a destructive update on garbage input. // rather than risk a destructive update on garbage input.
$this->assertSame( $this->assertSame(
SchemaAction::Tolerate, SchemaAction::Tolerate,
OnDuplicate::Upsert->resolveSchemaAction( OnDuplicate::Overwrite->resolveSchemaAction(
exists: true, exists: true,
sourceUpdatedAt: $source, sourceUpdatedAt: $source,
destUpdatedAt: $dest, destUpdatedAt: $dest,
@@ -150,6 +150,6 @@ class OnDuplicateTest extends TestCase
{ {
// The values() helper is consumed by API/SDK param validators; this // The values() helper is consumed by API/SDK param validators; this
// protects against an accidental case-rename or reorder. // protects against an accidental case-rename or reorder.
$this->assertSame(['fail', 'skip', 'upsert'], OnDuplicate::values()); $this->assertSame(['fail', 'skip', 'overwrite'], OnDuplicate::values());
} }
} }