feat(DestinationAppwrite): tolerate existing schema on Skip/Upsert re-migration

[premtsd-code]

Summary

Re-migration against a destination Appwrite project needs the destination to tolerate existing schema resources — otherwise the second run throws DuplicateException on every collection/attribute/index that already exists. This PR makes DestinationAppwrite handle that reconciliation locally, without requiring any changes to utopia-php/database.

Per-resource behavior

Resource	Skip	Upsert	Fail (default)
Database	pre-check metadata → tolerate (hydrate sequence)	same — never dropped (contains all collections + rows)	throw
Table	pre-check metadata → tolerate (hydrate sequence)	same — never dropped (contains all rows)	throw
Attribute	pre-check attributes → tolerate	pre-check + source.updatedAt > dest.updatedAt → deleteAttribute + recreate; else tolerate	throw
Index	pre-check indexes → tolerate	same updatedAt gate → deleteIndex + recreate; else tolerate	throw
Row	existing skipDuplicates(createDocuments)	existing upsertDocuments	plain createDocuments

Why pre-check over try/catch

Migration is a sequential single-writer. The race-condition justification for exception-driven control flow doesn't apply, so pre-check reads top-to-bottom without using exceptions for control flow. On OnDuplicate::Fail (the default) the pre-check is gated off — fresh-migration paths pay zero overhead.

Why only attributes/indexes get the updatedAt drop+recreate

• Databases and tables contain user data. Dropping is never acceptable.
• Attribute drop+recreate wipes that column's data; the follow-up row Upsert repopulates it, so the end state is correct.
• Index drop+recreate costs only rebuild time; no data loss.

Zero library changes

All of this uses existing utopia-php/database APIs:

• getDocument(collection, id) for pre-check
• deleteAttribute / deleteIndex for the Upsert drop path
• skipDuplicates() (5.3.22) for row-level Skip
• upsertDocuments() (existing) for row-level Upsert

No database library bump required.

Test plan

• testAppwriteMigrationRowsOnDuplicate in appwrite/appwrite PR #11910 passes end-to-end (three scenarios: fresh, Skip re-run, Upsert re-run).
• Re-run migration with changed attribute type on source → destination column dropped + recreated (in Upsert mode only).
• Re-run migration with unchanged source → no drops, second run idempotent.
• vendor/bin/pint --test passes.
• vendor/bin/phpstan analyse --level 3 src passes.

[greptile-apps]

Greptile Summary

This PR introduces Skip/Upsert re-migration tolerance for DestinationAppwrite by adding pre-checks at each schema layer (database, table, attribute, index) and a new SchemaAction enum driving resolveSchemaAction. The OnDuplicate logic and its unit tests are solid, but three ordering bugs in createIndex and createColumn will cause real failures on Upsert re-migrations at schema limits:

• The index count limit check and IndexValidator both execute with pre-drop state, causing false "Index limit reached" and "Invalid index" errors on DropAndRecreate paths.
• checkAttribute receives a stale in-memory $table after the attribute drop, causing false "Attribute limit exceeded" errors for collections at the attribute ceiling.

Confidence Score: 2/5

Not safe to merge — three P1 ordering bugs will cause Upsert re-migrations to fail at schema limits.

The OnDuplicate decision logic and tests are correct, but the integration into createIndex and createColumn has three confirmed defects where limit checks and validators execute against stale pre-drop state, producing false exceptions on the very Upsert DropAndRecreate path this PR is designed to enable.

src/Migration/Destinations/Appwrite.php — specifically the ordering of the index count/IndexValidator calls relative to the drop block, and the stale $table reference passed to checkAttribute.

Important Files Changed

Filename	Overview
src/Migration/Destinations/Appwrite.php	Adds Skip/Upsert schema reconciliation for databases, tables, attributes, and indexes; three P1 ordering bugs remain: index limit count and IndexValidator both fire before the Upsert drop block, and stale $table is passed to checkAttribute after the attribute drop.
src/Migration/Destinations/OnDuplicate.php	Adds SchemaAction enum and resolveSchemaAction / sourceIsNewer methods; logic is clean and the zero-epoch guard for strtotime is correct.
tests/Migration/Unit/General/OnDuplicateTest.php	New unit tests covering the full mode × existence × timestamp matrix for resolveSchemaAction; thorough and well-annotated.

Comments Outside Diff (2)

1. src/Migration/Destinations/Appwrite.php, line 939-950 (link)

   Index limit check fires before the Upsert drop

   The count query runs at line 939 and throws "Index limit reached for table" if the collection is at its ceiling — but the pre-check / drop block doesn't execute until line 1016. On an Upsert re-migration where the source spec is newer, the existing index is still counted here, so the guard fires even though the net change is zero (one drop, one add). The equivalent attribute path (checkAttribute) avoids this because it runs after the drop+purge cycle; the index path needs the same ordering.

2. src/Migration/Destinations/Appwrite.php, line 982-1013 (link)

   IndexValidator uses stale $tableIndexes before the Upsert drop

   $tableColumns and $tableIndexes are extracted from the in-memory $table (lines 982–983) and IndexValidator validates the new index at line 1006 — all before the pre-check/drop block at line 1016. On a DropAndRecreate path the old index is still embedded in $tableIndexes when validation runs. If IndexValidator detects that the new key or attribute-set already exists in that list it returns invalid and throws "Invalid index: …" before the drop ever executes, causing every Upsert re-migration with a spec-changed index to fail at validation.

   Moving the $tableColumns/$tableIndexes extraction, IndexValidator instantiation, and isValid call to after the drop block (and re-fetching $table post-purgeCachedDocument for fresh state) would resolve both this and the limit-count issue above.

_{Reviews (9): Last reviewed commit: "Trim verbose comments, keep only essenti..." | Re-trigger Greptile}