Maintainer review on utopia-php/migration#171 renamed
OnDuplicate::Upsert -> OnDuplicate::Overwrite (value 'upsert' ->
'overwrite') to align with Appwrite terms (skip / overwrite / fail).
Applying the cross-repo ripple here:
- app/controllers/api/migrations.php: 3 endpoint param descriptions
updated ('upsert' -> 'overwrite' in the help text). The validator
still uses OnDuplicate::values() so it auto-picks up the new value.
- tests/e2e/Services/Migrations/MigrationsBase.php: all
'onDuplicate' => 'upsert' -> 'overwrite'; method names
testAppwriteMigrationUpsert* -> testAppwriteMigrationOverwrite*;
comments / assertion messages / local var names switched.
- Left untouched: utopia's upsertDocuments operation, transaction
TransactionState 'upsert' action, Operation validator — those refer
to the database-level upsert primitive, not the OnDuplicate enum.
composer.lock: utopia-php/migration 7d71505 -> b8ae7bc.
After dropping createdAt from resolveSchemaAction, source-side recreate
no longer routes through DropAndRecreate via the outer decision. The
inner fallthrough still drops+recreates when the spec diff is a non-SDK
change, so this test now toggles 'array' (a non-SDK field) on recreate
to actually exercise the drop+recreate path it pins.
Also clarifies the two-way recreate test's docblock — with createdAt
gone and identical spec on recreate, it exercises spec-match + pair-key
dedup (both tolerate paths) rather than parent-side drop. End-state
assertions unchanged.
testAppwriteMigrationUpsertSameSpecRecreateTolerates exercises the new
spec-match guard added in utopia-php/migration c8d1789. Source drops +
recreates a column with the EXACT same spec as before; createdAt
advances but specs match → action is forced to Tolerate. Asserts dest
column's $createdAt stays at first-migration value (proving Tolerate,
not DropAndRecreate). Row pass under Upsert still propagates source's
new row value.
Companion to testAppwriteMigrationUpsertAttributeRecreateDropsAndRecreates
which exercises the spec-DIFFERS path: same precondition (drop + recreate),
different outcome (DropAndRecreate vs Tolerate) gated on spec equality.
composer.lock: utopia-php/migration 24fd23b -> c8d1789 (spec-match guard).
Two coverage gaps closed:
- testAppwriteMigrationUpsertOneWayRelationshipDropAndRecreate exercises
the path that updateRelationshipInPlace gates off: one-way + onDelete
change → returns false → falls through to DropAndRecreate via
deleteRelationship. Coverage was lost when
testAppwriteMigrationUpsertUpdatesRelationshipOnDeleteInPlace was
converted to two-way to actually hit the in-place path.
- testAppwriteMigrationUpsertAttributeRecreateDropsAndRecreates pins
the createdAt-different leaf path: source drops + recreates the
attribute (createdAt advances), re-migration must DropAndRecreate
on dest and re-flow the row data through the row pass. Companion to
testAppwriteMigrationUpsertUpdatesAttributeInPlace which covers the
same-createdAt + newer-updatedAt path.
Migration package already at 09c1b21 (the maintainability commit) from
the previous lock bump — no further composer.lock change needed.
testAppwriteMigrationUpsertTwoWayRecreateSkipsPartnerSide exercises
the DropAndRecreate path on a two-way relationship that the partner-
side pair-key dedup guards. Source recreates the relationship between
runs, forcing parent-side createdAt diff. Test asserts the migration
completes cleanly and partner-table rows survive — without dedup, the
partner pass re-fires DropAndRecreate and destroys those rows.
composer.lock: utopia-php/migration c76de9a -> c13e77d (partner-side
pair-key dedup restored).
The previous version of this test created a one-way relationship,
which falls through to DropAndRecreate (one-way + onDelete change is
gated off in updateRelationshipInPlace because utopia's
updateRelationship partner-cascade throws on one-way). It never
exercised the in-place path it was named for.
Converted to two-way (parents.kids ↔ children.parent), and asserted
both parent- and partner-side onDelete on dest. Partner-side
assertion is the regression guard for the partner-meta refresh that
was missing from updateRelationshipInPlace.
composer.lock: utopia-php/migration a36d95f -> c76de9a (partner-side
onDelete sync fix).
Three new e2e tests in MigrationsBase covering the schema reconciliation
paths added in utopia-php/migration:
- testAppwriteMigrationUpsertUpdatesAttributeInPlace: PATCH source
required/default (SDK-reachable), assert dest reflects change and the
pre-existing row's column data is preserved (drop+recreate would have
wiped it).
- testAppwriteMigrationSkipPreservesAttributeDrift: leaf-level analog
of the existing container-drift Skip test — guards Skip from ever
consulting timestamps.
- testAppwriteMigrationUpsertUpdatesRelationshipOnDeleteInPlace: PATCH
source onDelete cascade->restrict (SDK-reachable), assert dest
reflects change and structural fields (relationType, twoWay) untouched.
composer.lock: utopia-php/migration 6e6f825 -> a36d95f (mechanical
helpers replacement, parseTimestamp dedup, match dispatch, comment trim).
testAppwriteMigrationUpsertDropsOrphanColumn: adds a column directly on
destination (simulating post-rename orphan or dest-only drift), runs
Upsert, asserts the orphan is dropped and source-declared column
survives. Covers the per-table orphan cleanup fired inside
createRecord before rows land.
testAppwriteMigrationSkipKeepsOrphanColumn: same setup, Skip mode.
Asserts the orphan survives, proving the cleanup is correctly gated
to Upsert only.
Prem Palanisamy
ArnabChatterjee20kandGitHub
ArnabChatterjee20k
Matej BačoandGitHub
Matej Bačo