feat: adapt migration schema calls to query-lib value objects

[abnegate]

Adapts the migration destination's schema calls to the query-lib value objects.

Why this approach

Database::createCollection() takes a Collection only, so destination Appwrite now wraps the collection id, attributes and indexes — along with the named permissions and documentSecurity — in new Collection(...) instead of passing positional arrays.

utopia-php/database is pinned to dev-feat-query-lib as 2.0.0, re-pinned to that branch's head whenever it moves.

Lock repairs that came with the re-pin

Two problems surfaced only when the lock was resolved again rather than reused:

• utopia-php/query was locked to dev-feat-schema-order, a branch that no longer exists on the remote. The resolution survived only as long as nobody resolved it. database's branch requires query 0.6.*, which is released, so the lock now takes the release.
• utopia-php/storage moved 4.0.3 → 4.0.4, because 4.0.3 capped utopia-php/validators at ^0.4 while database requires ^0.5. 4.0.4 dropped the validators dependency outright. database has required ^0.5 on main as well as on the branch, so this was already true before the query-lib work and only surfaced now.

A live bug the re-pin exposed

The Appwrite destination passed the 'ASC' / 'DESC' strings a source hands back straight into Utopia\Database\Index, which takes Order cases and rejects anything else. The resulting InvalidArgumentException is not a Migration Exception, so instead of recording a failed index the whole transfer aborted.

This was already true before this PR and simply could not be seen: the lock held query at the deleted branch, whose Index took plain strings, so CI had never built an index against the contract the released library actually has. AppwriteIndexLengthsTest covers it — two of its cases pass ['ASC', 'ASC'], and both went red on the first run against the re-pinned lock and green with the fix.

It is the same defect as the one in appwrite/appwrite#11649's Databases worker, from the same cause.

Also on this branch: provisioning ownership and recovery

The branch has grown well past its title. Alongside the value-object adaptation it carries a provisioning-owner / lifecycle-fencing subsystem added 2026-08-29..31, which does not depend on query-lib at all:

• Destinations/Appwrite/ProvisioningOwner.php and owner persistence in Destinations/Appwrite.php
• fencing for concurrent provisioning attempts, and recovery of terminal migration failures
• explicit CLI flags for provisioning recovery in bin/MigrationCLI.php
• the tests that come with them: AppwriteDatabaseConcurrencyTest (+400), AppwriteDatabaseStatusTest (+1026), MigrationCLITest (+342), ProvisioningOwnerTest (+36)

Total diff against main is +3450/-714 over 23 files. Recommendation: split those commits into a PR against main so they can ship now, and leave only the Collection/Attribute/Index/Order adaptation and the lock re-pin here, where it is blocked on database#823 being tagged.

Chain

Landing order, bottom up:

1. utopia-php/database#823 — the query-lib migration itself
2. utopia-php/abuse#124, utopia-php/migration#222, utopia-php/monorepo#206 — the schema call sites in the libraries (audit moved to the monorepo, so feat: adapt audit schema to query-lib Attribute and Index VOs audit#133 is closed in favour of monorepo#206)
3. appwrite/appwrite#11649
4. appwrite-labs/cloud#5410

The three framework PRs once stacked on #823 — #947 (ORM), #948 (repositories and seeding), #949 (migration runner and schema differ) — are closed and are not part of this train.

Verified

• CI green on this head
• Greptile 5/5, no unresolved threads
• Pint on the Collection wrap

Not verified

• Open PR Support duplicate handling for Appwrite imports #205 (duplicate handling for Appwrite imports) edits the same Destinations/Appwrite.php regions; whichever lands second will need a merge.
• The utopia-php/database dependency is still a branch pin. It becomes a released tag only once #823 merges, and this PR should not land before that.

---

Fixes from the 2026-09-23 review

A progress callback can stop a transfer: Exception\Aborted (11.7)

• New Utopia\Migration\Exception\Aborted (extends RuntimeException).
  • Throw it from the callback given to Transfer::run() or Transfer::runWithResourceSelector() to stop the transfer.
  • Every library source (Appwrite, Firebase, Supabase, NHost, CSV, JSON) rethrows it from the catch that otherwise
    records a resource type's failure and moves on. Nothing further is exported or imported.
  • It leaves run()/runWithResourceSelector() as the same instance.
  • Every other failure is still recorded in getErrors() as before.
  • The batch whose callback threw has already been imported, because the callback runs after the destination imports
    a batch.
• Why: each source wraps every resource type's export in a catch-all.
  • An exception from the progress callback was recorded as that type's error, and the source went on to the next type
    and group. It imported the first batch of each before the callback threw again.
  • A consumer had no way to stop a run, and appwrite's migration worker relies on exactly that when its attempt is
    superseded.
• The nested per-file and per-deployment catches in the Appwrite source's storage, functions and sites exports rethrow
  it too. An abort no longer skips to the next file or deployment.
• Transfer keeps the first abort for the rest of the run. A source outside this library that still catches it and
  carries on cannot turn it into a normal return: later batches rethrow it without calling the callback again, and the
  run ends with it. A later run() on the same Transfer is unaffected.
• Aborted is deliberately not a Utopia\Migration\Exception. That type is the per-resource error record that sources
  append to errors, and an abort is not a resource error.

Provisioning ownership (06.1, 06.2, 06.7, 06.9)

• Owners are written only where the schema has room for them.

  • The Appwrite destination checks separately for status (Appwrite V25) and for the
    migrationId/migrationAttemptId owner pair (V26).
  • On a project that has reached V25 but not V26, databases get status tracking with no owner, as they did before
    ownership existed.
  • Before this change, every database import into such a project failed. Schemas that reject unknown attributes
    returned Unknown attribute: "migrationId". Schemas that drop them, like Appwrite's project database, left every
    database stuck in provisioning with "owner changed before finalization".

• Databases left incomplete before ownership existed can be recovered again. A provisioning or failed database
  that names no owner was left by an earlier library version or by a status-only schema. It is recovered without
  getRecoverableOwner, as it was before ownership existed:

  • A failed database is overwritten.
  • A provisioning database is resolved under the OnDuplicate policy like any existing database, and fail keeps it
    instead of colliding with it. It is marked ready when the run succeeds.

  Either way, the current attempt claims the database under the row lock when the schema can record an owner. A missing
  backing collection is recreated before the ready flip. A database that names an owner, even half of one, still needs
  attestation, and a refusal still fails closed.

• Provisioning writes are fenced without borrowed timestamps.

  • The overwrite claim no longer writes the source archive's $updatedAt into the column the optimistic fence
    compares. So $updatedAt always moves forward, whatever the preserveDates setting.
  • Every guarded write re-reads the row. If the stored timestamp did not move forward, the write fails
    (Database <id> provisioning write did not move its update timestamp forward). Inside the claim transaction it is
    rolled back.

• A relationship overwrite no longer changes an onDelete the source didn't specify.

  • If the source has no onDelete, or an empty or unknown one, the value reaches updateRelationship() as null
    ("unchanged").
  • Before, it became restrict, or an empty or unknown value threw a ValueError.
  • Both sides of the Appwrite attribute metadata keep the destination's action.

Finalization contract (06.3, 06.4, 06.8)

• A failed finalization throws.
  • Destinations\Appwrite::success() used to report a database it could not mark ready only by appending to
    getErrors(). That came after the point where most callers check for errors, so a caller that checked once before
    success() marked the migration completed while its databases stayed provisioning.
  • success() now attempts every step, records each failure with addError() as before, and then throws
    Utopia\Migration\Exception\Finalization.
  • The exception extends Utopia\Migration\Exception, and its failures property lists the recorded errors.
• One failed step no longer skips the others.
  • A single database that failed its ready write made success() return before the OnDuplicate::Overwrite orphan
    sweep. That left the unswept columns and indexes of every table behind.
  • The flip still runs first, so a sweep failure can't strand databases in provisioning. The sweep now always
    follows, as it did before finalization moved to success().
  • A table whose sweep fails no longer stops the sweep of the tables after it.
• Skipping success() is reported.
  • Finalization stays in success(), because callers such as Appwrite must persist their finalizing claim before it
    runs. Neither Transfer nor Target calls success(), and Transfer calls no lifecycle hook at all.
  • So the destination records an error for each database that a returned run left unfinalized. It does this when
    cleanUp() ends the lifecycle, or when run() starts again on the same instance.
  • A caller that calls success(), or error() for a run it won't finalize, gets no report.
  • The error can't appear before success() is due, so the error check a caller makes between run() and success()
    still passes.
• Only a run that returned is finalized. success() after a destination run() that threw now does nothing. The
  databases stay provisioning for a later attempt to recover, as they did when run() finalized itself. Before this
  change they were marked ready with only part of their contents.
• The lifecycle contract is documented on Target::success(), Target::error() and Target::cleanUp().

Upgrade notes

• Custom sources. A Source subclass that catches \Throwable around its exports should rethrow
  Utopia\Migration\Exception\Aborted before recording other errors:
  } catch (Aborted $abort) { throw $abort; } catch (\Throwable $error) { ... }. Transfer::run() still ends with the
  abort if it does not, but the source keeps exporting until it returns.
• Callers of Destinations\Appwrite:
  1. After run() returns, persist any claim that must come first, then call success().
  2. Catch Exception\Finalization from success(). Each failure is also in getErrors().
  3. For a run you won't finalize, call error() instead.
  4. After catching Aborted from Transfer::run(), call error() (or nothing), never success().
• getRecoverableOwner is unchanged. It is now called only for rows that name an owner, so existing callbacks need
  no change.

CHANGELOG highlights (3.0.0, unreleased)

mg-05 writes CHANGELOG.md in wave 2; these are the entries it should carry.

• Breaking: requires utopia-php/database 8 (main requires ^7.0.0). The PHP floor is unchanged: >=8.5, as
  on main.
• Breaking: the Appwrite destination records which migration attempt provisions each database.
  • Its constructor takes a ProvisioningOwner $owner, made from a stable logical migration id and a fresh attempt id
    for every execution.
  • It also takes a getRecoverableOwner callback that attests the terminal owner of an incomplete database.
  • The standalone CLI requires --migration-id and a fresh --migration-attempt-id. Recovering an incomplete
    database that names an owner also requires --recover-migration-id and --recover-migration-attempt-id.
  • Owners are written and enforced only where the destination's databases metadata declares both owner attributes.
    Databases that name no owner are recovered as before.
• Breaking: Destinations\Appwrite::run() no longer finalizes.
  • Call success() once run() has returned (after persisting any claim that must come first), or error() for a
    run you won't finalize.
  • success() throws Utopia\Migration\Exception\Finalization when a step fails. Each failure is also recorded with
    addError().
  • cleanUp() records an error for each database left unfinalized when neither was called.
• Added: Utopia\Migration\Exception\Aborted. Throw it from a transfer's progress callback to stop the transfer.
  Every library source rethrows it, and Transfer ends the run with it.
• Fixed:
  • Imports into a destination whose database metadata has status but no owner attributes.
  • Recovery of databases left provisioning or failed without an owner.
  • The provisioning fence no longer relies on source timestamps.
  • A relationship overwrite keeps the destination's onDelete when the source has none.
  • One failed ready flip no longer skips the overwrite orphan sweep.

Commits

• fbe35ad fix: stop a transfer when its progress callback aborts
• 346f16b fix: end a transfer with the abort even when a source swallows it
• c417528 fix(destination): write provisioning owners only where the schema declares them
• d86a306 fix(destination): recover databases left incomplete before ownership existed
• 5880597 fix(destination): fence provisioning writes without source timestamps
• 0ecd10c fix(destination): leave a relationship's onDelete alone when the source has none
• c033754 (fix): run the overwrite sweep when a database fails to flip ready
• e73646f (fix): throw Finalization when success() cannot finalize
• 2e89529 (fix): report a skipped success() when the destination lifecycle ends
• 8429254 chore: re-pin utopia-php/database to the feat-query-lib head

🤖 Generated with Claude Code

[greptile-apps]

Confidence Score: 5/5

[High risk] Upgrades database library and refactors migration schema calls.

No outstanding review finding blocks merging; the documented database release dependency remains a landing prerequisite.

Summary

This PR adapts Appwrite migration schema calls to query-lib value objects and adds provisioning ownership, recovery, abort handling, and explicit finalization. The only change since the previous review came from merging main and is already in the PR base. No new findings were accepted.

_{Reviews (47) · Last reviewed commit: "chore(merge): merge main into feat-query..."}

[abnegate]

Addressed the reload-failure finding.

createDocument can persist a _databases row whose immediately following getDocument is empty (the Mongo sequence miss this branch already reloads for). That throw sat outside the markDatabaseFailed catch, so the document stayed provisioning and a later spec-matching skip could flip it to ready with no backing collection.

Reload + createCollection now share that catch. testReloadFailureMarksTheDatabaseFailed fails without the wrap (provisioning) and passes with it (failed).

Also stubbed Swoole\Coroutine::getCid() in the PHPUnit bootstrap so the Memory-adapter suite can run on the CI image, which has no Swoole extension. utopia-php/database feat-query-lib keys silenced events with it.

@greptile-apps review

[abnegate]

@greptileai review

[abnegate]

@greptile-apps review

Force re-review of HEAD 7a3a60e. Description updated for factories and caret lock refresh.

[abnegate]

@greptileai review