From 8a0ebdbed72466a362de2580d06742cea6daff3a Mon Sep 17 00:00:00 2001 From: Jake Barnby Date: Fri, 8 May 2026 17:39:28 +1200 Subject: [PATCH] =?UTF-8?q?docs:=20clarify=20resolver=20scope=20=E2=80=94?= =?UTF-8?q?=20when=20source/destination=20DSNs=20differ?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit "Cross-instance migrations" was ambiguous: it read like cloud-to-cloud or dedicated-DB migration. The actual scope is narrower — any case where the source project's stored DSN doesn't apply to the destination project (cross-host within the same instance, cross-region, mixed shared-tables migration). Reword the property, constructor, and inline write-site comments to say that explicitly. --- src/Migration/Destinations/Appwrite.php | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index fa464e1104..a34e164b26 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -104,11 +104,13 @@ class Appwrite extends Destination protected $getDatabasesDB; /** - * Resolves the DSN written into the destination's `_databases.database` for - * a migrated database. When unset, the attribute is left blank and the - * runtime falls back to the destination project's DSN — correct for legacy - * single-DSN projects, but cross-instance / multi-type setups must inject - * a resolver so source DSNs don't bleed into the destination metadata. + * Resolves the DSN written into the destination's `_databases.database` + * for a migrated database. When the source and destination projects don't + * share the same DSN — e.g. one project is on a host the other isn't — + * pass a resolver so the destination metadata carries its own DSN instead + * of the source's. When unset, the attribute is left blank and the + * runtime falls back to the destination project's DSN at read time, which + * is safe for single-host single-type setups. * * @var (callable(Database $resource): string)|null */ @@ -150,7 +152,7 @@ class Appwrite extends Destination * @param callable(UtopiaDocument $database):UtopiaDatabase $getDatabasesDB * @param array> $collectionStructure * @param OnDuplicate $onDuplicate Behavior when a row with an existing $id is encountered. - * @param (callable(Database $resource): string)|null $getDatabaseDSN Resolver for the destination's `_databases.database` value. Required for cross-instance migrations to prevent the source DSN from being written into the destination project's metadata. + * @param (callable(Database $resource): string)|null $getDatabaseDSN Resolver for the destination's `_databases.database` value. Pass when the destination project's DSN differs from the source's, so the destination row carries its own DSN instead of inheriting the source's. */ public function __construct( string $project, @@ -185,8 +187,9 @@ class Appwrite extends Destination /** * Resolve the DSN written into the destination's `_databases.database`. * Without a resolver, leave it blank — the source DSN must never be - * propagated, since cross-instance source/destination DSNs differ and - * propagation routes destination reads to the wrong host (see PR #151). + * propagated as the default, since when source and destination DSNs + * differ propagation routes destination reads to the wrong host (the + * regression PR #151 introduced). */ private function resolveDestinationDsn(Database $resource): string { @@ -569,7 +572,7 @@ class Appwrite extends Destination '$updatedAt' => $updatedAt, 'originalId' => empty($resource->getOriginalId()) ? null : $resource->getOriginalId(), 'type' => empty($resource->getType()) ? 'legacy' : $resource->getType(), - // Source and destination can be in different locations; never write the source DSN here. + // Resolved by the destination's resolver (or left blank); never copy the source's DSN by default. 'database' => $this->resolveDestinationDsn($resource), ]));