From d3084fb816d9819eb537687bafa7a3a1962f14af Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Thu, 12 Mar 2026 13:40:47 +0000 Subject: [PATCH 01/91] Add backup policy migration support --- src/Migration/Destinations/Appwrite.php | 11 ++ src/Migration/Resource.php | 4 + src/Migration/Resources/Backups/Policy.php | 115 +++++++++++++++++++++ src/Migration/Source.php | 17 +++ src/Migration/Sources/Appwrite.php | 16 +++ src/Migration/Sources/CSV.php | 5 + src/Migration/Sources/Firebase.php | 5 + src/Migration/Sources/JSON.php | 5 + src/Migration/Sources/NHost.php | 5 + src/Migration/Transfer.php | 8 ++ 10 files changed, 191 insertions(+) create mode 100644 src/Migration/Resources/Backups/Policy.php diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index 05c62470cf..29ffc42583 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -169,6 +169,9 @@ class Appwrite extends Destination Resource::TYPE_SITE, Resource::TYPE_SITE_DEPLOYMENT, Resource::TYPE_SITE_VARIABLE, + + // Backups + Resource::TYPE_BACKUP_POLICY, ]; } @@ -325,6 +328,7 @@ class Appwrite extends Destination Transfer::GROUP_FUNCTIONS => $this->importFunctionResource($resource), Transfer::GROUP_MESSAGING => $this->importMessagingResource($resource), Transfer::GROUP_SITES => $this->importSiteResource($resource), + Transfer::GROUP_BACKUPS => $this->importBackupResource($resource), default => throw new \Exception('Invalid resource group', Exception::CODE_VALIDATION), }; } catch (\Throwable $e) { @@ -1483,6 +1487,13 @@ class Appwrite extends Destination return $resource; } + public function importBackupResource(Resource $resource): Resource + { + $resource->setStatus(Resource::STATUS_SUCCESS); + + return $resource; + } + /** * @throws AppwriteException * @throws \Exception diff --git a/src/Migration/Resource.php b/src/Migration/Resource.php index 1dc198c6ca..2fc102c553 100644 --- a/src/Migration/Resource.php +++ b/src/Migration/Resource.php @@ -75,6 +75,9 @@ abstract class Resource implements \JsonSerializable public const TYPE_MESSAGE = 'message'; + // Backups + public const TYPE_BACKUP_POLICY = 'backup-policy'; + // legacy terminologies public const TYPE_DOCUMENT = 'document'; public const TYPE_ATTRIBUTE = 'attribute'; @@ -110,6 +113,7 @@ abstract class Resource implements \JsonSerializable self::TYPE_TOPIC, self::TYPE_SUBSCRIBER, self::TYPE_MESSAGE, + self::TYPE_BACKUP_POLICY, // legacy self::TYPE_DOCUMENT, diff --git a/src/Migration/Resources/Backups/Policy.php b/src/Migration/Resources/Backups/Policy.php new file mode 100644 index 0000000000..d5358b4287 --- /dev/null +++ b/src/Migration/Resources/Backups/Policy.php @@ -0,0 +1,115 @@ + $services + * @param int $retention + * @param string $schedule + * @param bool $enabled + * @param string $resourceId + * @param string $resourceType + */ + public function __construct( + string $id = '', + private readonly string $name = '', + private readonly array $services = [], + private readonly int $retention = 0, + private readonly string $schedule = '', + private readonly bool $enabled = true, + private readonly string $resourceId = '', + private readonly string $resourceType = '', + ) { + $this->id = $id; + } + + /** + * @param array $array + * @return self + */ + public static function fromArray(array $array): self + { + return new self( + $array['id'], + $array['name'] ?? '', + $array['services'] ?? [], + $array['retention'] ?? 0, + $array['schedule'] ?? '', + $array['enabled'] ?? true, + $array['resourceId'] ?? '', + $array['resourceType'] ?? '', + ); + } + + /** + * @return array + */ + public function jsonSerialize(): array + { + return [ + 'id' => $this->id, + 'name' => $this->name, + 'services' => $this->services, + 'retention' => $this->retention, + 'schedule' => $this->schedule, + 'enabled' => $this->enabled, + 'resourceId' => $this->resourceId, + 'resourceType' => $this->resourceType, + ]; + } + + public static function getName(): string + { + return Resource::TYPE_BACKUP_POLICY; + } + + public function getGroup(): string + { + return Transfer::GROUP_BACKUPS; + } + + public function getPolicyName(): string + { + return $this->name; + } + + /** + * @return array + */ + public function getServices(): array + { + return $this->services; + } + + public function getRetention(): int + { + return $this->retention; + } + + public function getSchedule(): string + { + return $this->schedule; + } + + public function getEnabled(): bool + { + return $this->enabled; + } + + public function getResourceId(): string + { + return $this->resourceId; + } + + public function getResourceType(): string + { + return $this->resourceType; + } +} diff --git a/src/Migration/Source.php b/src/Migration/Source.php index b6eb8c429d..cd38ebbd4c 100644 --- a/src/Migration/Source.php +++ b/src/Migration/Source.php @@ -46,6 +46,11 @@ abstract class Source extends Target return static::$defaultBatchSize; } + public function getBackupsBatchSize(): int + { + return static::$defaultBatchSize; + } + /** * @param array $resources * @return void @@ -109,6 +114,7 @@ abstract class Source extends Target Transfer::GROUP_FUNCTIONS => Transfer::GROUP_FUNCTIONS_RESOURCES, Transfer::GROUP_MESSAGING => Transfer::GROUP_MESSAGING_RESOURCES, Transfer::GROUP_SITES => Transfer::GROUP_SITES_RESOURCES, + Transfer::GROUP_BACKUPS => Transfer::GROUP_BACKUPS_RESOURCES, ]; foreach ($mapping as $group => $resources) { @@ -143,6 +149,9 @@ abstract class Source extends Target case Transfer::GROUP_SITES: $this->exportGroupSites($this->getSitesBatchSize(), $resources); break; + case Transfer::GROUP_BACKUPS: + $this->exportGroupBackups($this->getBackupsBatchSize(), $resources); + break; } } } @@ -194,4 +203,12 @@ abstract class Source extends Target * @param array $resources Resources to export */ abstract protected function exportGroupSites(int $batchSize, array $resources): void; + + /** + * Export Backups Group + * + * @param int $batchSize + * @param array $resources Resources to export + */ + abstract protected function exportGroupBackups(int $batchSize, array $resources): void; } diff --git a/src/Migration/Sources/Appwrite.php b/src/Migration/Sources/Appwrite.php index 4de9c1bbd3..bba2b696e3 100644 --- a/src/Migration/Sources/Appwrite.php +++ b/src/Migration/Sources/Appwrite.php @@ -200,6 +200,9 @@ class Appwrite extends Source Resource::TYPE_SITE_DEPLOYMENT, Resource::TYPE_SITE_VARIABLE, + // Backups + Resource::TYPE_BACKUP_POLICY, + // Settings ]; } @@ -239,6 +242,7 @@ class Appwrite extends Source $this->reportFunctions($resources, $report, $resourceIds); $this->reportMessaging($resources, $report, $resourceIds); $this->reportSites($resources, $report, $resourceIds); + $this->reportBackups($resources, $report, $resourceIds); $report['version'] = $this->call( 'GET', @@ -1419,6 +1423,18 @@ class Appwrite extends Source } } + protected function exportGroupBackups(int $batchSize, array $resources): void + { + // No-op: backup policies are Cloud-only + } + + protected function reportBackups(array $resources, array &$report, array $resourceIds = []): void + { + if (\in_array(Resource::TYPE_BACKUP_POLICY, $resources)) { + $report[Resource::TYPE_BACKUP_POLICY] = 0; + } + } + /** * @throws AppwriteException */ diff --git a/src/Migration/Sources/CSV.php b/src/Migration/Sources/CSV.php index 7d02090faf..0595b95681 100644 --- a/src/Migration/Sources/CSV.php +++ b/src/Migration/Sources/CSV.php @@ -429,6 +429,11 @@ class CSV extends Source throw new \Exception('Not Implemented'); } + protected function exportGroupBackups(int $batchSize, array $resources): void + { + throw new \Exception('Not Implemented'); + } + /** * @param callable(resource $stream, string $delimiter): void $callback * @return void diff --git a/src/Migration/Sources/Firebase.php b/src/Migration/Sources/Firebase.php index 4495fb5ba1..09ada816cb 100644 --- a/src/Migration/Sources/Firebase.php +++ b/src/Migration/Sources/Firebase.php @@ -818,4 +818,9 @@ class Firebase extends Source { throw new \Exception('Not implemented'); } + + protected function exportGroupBackups(int $batchSize, array $resources): void + { + throw new \Exception('Not implemented'); + } } diff --git a/src/Migration/Sources/JSON.php b/src/Migration/Sources/JSON.php index 15e7b6aa3c..8f2a81ae39 100644 --- a/src/Migration/Sources/JSON.php +++ b/src/Migration/Sources/JSON.php @@ -209,6 +209,11 @@ class JSON extends Source throw new \Exception('Not Implemented'); } + protected function exportGroupBackups(int $batchSize, array $resources): void + { + throw new \Exception('Not Implemented'); + } + /** * @throws \Exception */ diff --git a/src/Migration/Sources/NHost.php b/src/Migration/Sources/NHost.php index 4aac49f846..2b0c9bfedd 100644 --- a/src/Migration/Sources/NHost.php +++ b/src/Migration/Sources/NHost.php @@ -951,4 +951,9 @@ class NHost extends Source { throw new \Exception('Not Implemented'); } + + protected function exportGroupBackups(int $batchSize, array $resources): void + { + throw new \Exception('Not Implemented'); + } } diff --git a/src/Migration/Transfer.php b/src/Migration/Transfer.php index 561ff28330..e8c5ee5d10 100644 --- a/src/Migration/Transfer.php +++ b/src/Migration/Transfer.php @@ -26,6 +26,8 @@ class Transfer public const GROUP_MESSAGING = 'messaging'; + public const GROUP_BACKUPS = 'backups'; + public const GROUP_AUTH_RESOURCES = [ Resource::TYPE_USER, Resource::TYPE_TEAM, @@ -88,6 +90,10 @@ class Transfer public const GROUP_SETTINGS_RESOURCES = []; + public const GROUP_BACKUPS_RESOURCES = [ + Resource::TYPE_BACKUP_POLICY, + ]; + public const GROUP_MESSAGING_RESOURCES = [ Resource::TYPE_PROVIDER, Resource::TYPE_TOPIC, @@ -116,6 +122,7 @@ class Transfer Resource::TYPE_TOPIC, Resource::TYPE_SUBSCRIBER, Resource::TYPE_MESSAGE, + Resource::TYPE_BACKUP_POLICY, // legacy Resource::TYPE_DOCUMENT, @@ -399,6 +406,7 @@ class Transfer self::GROUP_DATABASES_VECTOR_DB => array_merge($resources, self::GROUP_VECTORSDB_RESOURCES), self::GROUP_SETTINGS => array_merge($resources, self::GROUP_SETTINGS_RESOURCES), self::GROUP_MESSAGING => array_merge($resources, self::GROUP_MESSAGING_RESOURCES), + self::GROUP_BACKUPS => array_merge($resources, self::GROUP_BACKUPS_RESOURCES), default => throw new \Exception('No service group found'), }; } From 4e9b35720049ec27784df1ba41ad802349a0af25 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Thu, 12 Mar 2026 21:42:40 +0000 Subject: [PATCH 02/91] Use STATUS_SKIPPED for CE backup policy import --- src/Migration/Destinations/Appwrite.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index 29ffc42583..44ae29b468 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -1489,7 +1489,7 @@ class Appwrite extends Destination public function importBackupResource(Resource $resource): Resource { - $resource->setStatus(Resource::STATUS_SUCCESS); + $resource->setStatus(Resource::STATUS_SKIPPED); return $resource; } From 5352a2bf136610e5d940c53420cc1c64c448189e Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Thu, 12 Mar 2026 21:51:44 +0000 Subject: [PATCH 03/91] Add exportGroupBackups to MockSource test adapter --- tests/Migration/Unit/Adapters/MockSource.php | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/tests/Migration/Unit/Adapters/MockSource.php b/tests/Migration/Unit/Adapters/MockSource.php index 889eeb3c68..d4504c88cf 100644 --- a/tests/Migration/Unit/Adapters/MockSource.php +++ b/tests/Migration/Unit/Adapters/MockSource.php @@ -84,6 +84,7 @@ class MockSource extends Source Resource::TYPE_TOPIC, Resource::TYPE_SUBSCRIBER, Resource::TYPE_MESSAGE, + Resource::TYPE_BACKUP_POLICY, // legacy Resource::TYPE_DOCUMENT, @@ -198,4 +199,15 @@ class MockSource extends Source $this->handleResourceTransfer(Transfer::GROUP_SITES, $resource); } } + + protected function exportGroupBackups(int $batchSize, array $resources): void + { + foreach (Transfer::GROUP_BACKUPS_RESOURCES as $resource) { + if (!\in_array($resource, $resources)) { + continue; + } + + $this->handleResourceTransfer(Transfer::GROUP_BACKUPS, $resource); + } + } } From 73c464a2c9b6459037abc1c73ebae6d64d32ea42 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Fri, 13 Mar 2026 10:19:00 +0000 Subject: [PATCH 04/91] Add missing bucket and function migration properties Add transformations property to Bucket migration and commands, logging, scopes, specification properties to Function migration for both source export and destination import. --- src/Migration/Destinations/Appwrite.php | 9 ++++- src/Migration/Resources/Functions/Func.php | 43 +++++++++++++++++++++- src/Migration/Resources/Storage/Bucket.php | 11 +++++- src/Migration/Sources/Appwrite.php | 8 +++- 4 files changed, 65 insertions(+), 6 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index 05c62470cf..0d0e7d641a 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -1141,7 +1141,8 @@ class Appwrite extends Destination $resource->getAllowedFileExtensions(), $compression, $resource->getEncryption(), - $resource->getAntiVirus() + $resource->getAntiVirus(), + $resource->getTransformations() ); $resource->setId($response['$id']); @@ -1462,7 +1463,11 @@ class Appwrite extends Destination $resource->getSchedule(), $resource->getTimeout(), $resource->getEnabled(), - entrypoint: $resource->getEntrypoint(), + $resource->getLogging(), + $resource->getEntrypoint(), + $resource->getCommands(), + $resource->getScopes(), + specification: $resource->getSpecification() ?: null, ); break; case Resource::TYPE_ENVIRONMENT_VARIABLE: diff --git a/src/Migration/Resources/Functions/Func.php b/src/Migration/Resources/Functions/Func.php index 930f92191a..ef5e69341f 100644 --- a/src/Migration/Resources/Functions/Func.php +++ b/src/Migration/Resources/Functions/Func.php @@ -18,6 +18,10 @@ class Func extends Resource * @param int $timeout * @param string $activeDeployment * @param string $entrypoint + * @param string $commands + * @param bool $logging + * @param array $scopes + * @param string $specification */ public function __construct( string $id, @@ -29,7 +33,11 @@ class Func extends Resource private readonly string $schedule = '', private readonly int $timeout = 0, private readonly string $activeDeployment = '', - private readonly string $entrypoint = '' + private readonly string $entrypoint = '', + private readonly string $commands = '', + private readonly bool $logging = true, + private readonly array $scopes = [], + private readonly string $specification = '' ) { $this->id = $id; } @@ -50,7 +58,11 @@ class Func extends Resource $array['schedule'] ?? '', $array['timeout'] ?? 0, $array['activeDeployment'] ?? '', - $array['entrypoint'] ?? '' + $array['entrypoint'] ?? '', + $array['commands'] ?? '', + $array['logging'] ?? true, + $array['scopes'] ?? [], + $array['specification'] ?? '' ); } @@ -70,6 +82,10 @@ class Func extends Resource 'timeout' => $this->timeout, 'activeDeployment' => $this->activeDeployment, 'entrypoint' => $this->entrypoint, + 'commands' => $this->commands, + 'logging' => $this->logging, + 'scopes' => $this->scopes, + 'specification' => $this->specification, ]; } @@ -133,4 +149,27 @@ class Func extends Resource { return $this->entrypoint; } + + public function getCommands(): string + { + return $this->commands; + } + + public function getLogging(): bool + { + return $this->logging; + } + + /** + * @return array + */ + public function getScopes(): array + { + return $this->scopes; + } + + public function getSpecification(): string + { + return $this->specification; + } } diff --git a/src/Migration/Resources/Storage/Bucket.php b/src/Migration/Resources/Storage/Bucket.php index cd6fdf0621..a667ffdc17 100644 --- a/src/Migration/Resources/Storage/Bucket.php +++ b/src/Migration/Resources/Storage/Bucket.php @@ -19,6 +19,7 @@ class Bucket extends Resource * @param bool $encryption * @param bool $antiVirus * @param bool $updateLimits + * @param bool $transformations */ public function __construct( string $id = '', @@ -32,6 +33,7 @@ class Bucket extends Resource private readonly bool $encryption = false, private readonly bool $antiVirus = false, private readonly bool $updateLimits = false, + private readonly bool $transformations = false, ) { $this->id = $id; $this->permissions = $permissions; @@ -54,7 +56,8 @@ class Bucket extends Resource $array['compression'] ?? 'none', $array['encryption'] ?? false, $array['antiVirus'] ?? false, - $array['updateLimits'] ?? false + $array['updateLimits'] ?? false, + $array['transformations'] ?? false ); } @@ -74,6 +77,7 @@ class Bucket extends Resource 'encryption' => $this->encryption, 'antiVirus' => $this->antiVirus, 'updateLimits' => $this->updateLimits, + 'transformations' => $this->transformations, ]; } @@ -131,4 +135,9 @@ class Bucket extends Resource { return $this->antiVirus; } + + public function getTransformations(): bool + { + return $this->transformations; + } } diff --git a/src/Migration/Sources/Appwrite.php b/src/Migration/Sources/Appwrite.php index 4de9c1bbd3..e5e57fa90d 100644 --- a/src/Migration/Sources/Appwrite.php +++ b/src/Migration/Sources/Appwrite.php @@ -1252,6 +1252,8 @@ class Appwrite extends Source $bucket['compression'], $bucket['encryption'], $bucket['antivirus'], + false, + $bucket['transformations'] ?? false, ); $convertedBuckets[] = $bucket; } @@ -1462,7 +1464,11 @@ class Appwrite extends Source $function['schedule'], $function['timeout'], $function['deploymentId'] ?? '', - $function['entrypoint'] + $function['entrypoint'], + $function['commands'] ?? '', + $function['logging'] ?? true, + $function['scopes'] ?? [], + $function['specification'] ?? '', ); $functions[] = $convertedFunc; From a5cebfaffae91749a3af921c2b8b2b47a9397e81 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Thu, 19 Mar 2026 13:18:51 +0530 Subject: [PATCH 05/91] fix: update database property type to nullable and handle defaults in fromArray method --- src/Migration/Resources/Database/Database.php | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/Migration/Resources/Database/Database.php b/src/Migration/Resources/Database/Database.php index 05afab2c48..396cdd09d1 100644 --- a/src/Migration/Resources/Database/Database.php +++ b/src/Migration/Resources/Database/Database.php @@ -26,7 +26,7 @@ class Database extends Resource protected bool $enabled = true, protected string $originalId = '', protected string $type = '', - protected string $database = '' + protected ?string $database = '' ) { $this->id = $id; } @@ -52,7 +52,7 @@ class Database extends Resource enabled: $array['enabled'] ?? true, originalId: $array['originalId'] ?? '', type: $array['type'] ?? 'legacy', - database: $array['database'] + database: $array['database'] ?? null ); } @@ -97,7 +97,7 @@ class Database extends Resource return $this->type; } - public function getDatabase(): string + public function getDatabase(): mixed { return $this->database; } From adc6393f70604b15622fb44b8a9f08abb6bbf9f2 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k <83803257+ArnabChatterjee20k@users.noreply.github.com> Date: Thu, 19 Mar 2026 14:38:36 +0530 Subject: [PATCH 06/91] Update src/Migration/Resources/Database/Database.php Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> --- src/Migration/Resources/Database/Database.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Migration/Resources/Database/Database.php b/src/Migration/Resources/Database/Database.php index 396cdd09d1..6abfaac055 100644 --- a/src/Migration/Resources/Database/Database.php +++ b/src/Migration/Resources/Database/Database.php @@ -97,7 +97,7 @@ class Database extends Resource return $this->type; } - public function getDatabase(): mixed + public function getDatabase(): ?string { return $this->database; } From c3ea0d670d2fd86893a4f7bafad62f17883a1571 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Mon, 30 Mar 2026 14:27:23 +0530 Subject: [PATCH 07/91] feat: add BigInt column type support and update related classes --- composer.json | 2 +- composer.lock | 117 ++++++------------ src/Migration/Destinations/Appwrite.php | 1 + src/Migration/Resources/Database/Column.php | 1 + .../Resources/Database/Columns/BigInt.php | 107 ++++++++++++++++ src/Migration/Sources/Appwrite.php | 13 ++ src/Migration/Sources/CSV.php | 5 +- src/Migration/Sources/NHost.php | 3 +- 8 files changed, 168 insertions(+), 81 deletions(-) create mode 100644 src/Migration/Resources/Database/Columns/BigInt.php diff --git a/composer.json b/composer.json index 5585f2a53f..a3c194e9bc 100644 --- a/composer.json +++ b/composer.json @@ -26,7 +26,7 @@ "ext-curl": "*", "ext-openssl": "*", "appwrite/appwrite": "19.*", - "utopia-php/database": "5.*", + "utopia-php/database": "dev-big-init as 5.4", "utopia-php/storage": "1.0.*", "utopia-php/dsn": "0.2.*", "halaxa/json-machine": "^1.2" diff --git a/composer.lock b/composer.lock index 17d1422175..6a9d20728a 100644 --- a/composer.lock +++ b/composer.lock @@ -4,7 +4,7 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "37980b9001fbbd4f213f3102c1332727", + "content-hash": "16a5b9e9382b5fa55ea40c8ec5a9cc00", "packages": [ { "name": "appwrite/appwrite", @@ -2181,17 +2181,17 @@ "time": "2026-01-28T10:55:44+00:00" }, { - "name": "utopia-php/compression", - "version": "0.1.3", + "name": "utopia-php/console", + "version": "0.1.1", "source": { "type": "git", - "url": "https://github.com/utopia-php/compression.git", - "reference": "66f093557ba66d98245e562036182016c7dcfe8a" + "url": "https://github.com/utopia-php/console.git", + "reference": "d298e43960780e6d76e66de1228c75dc81220e3e" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/compression/zipball/66f093557ba66d98245e562036182016c7dcfe8a", - "reference": "66f093557ba66d98245e562036182016c7dcfe8a", + "url": "https://api.github.com/repos/utopia-php/console/zipball/d298e43960780e6d76e66de1228c75dc81220e3e", + "reference": "d298e43960780e6d76e66de1228c75dc81220e3e", "shasum": "" }, "require": { @@ -2199,45 +2199,47 @@ }, "require-dev": { "laravel/pint": "1.2.*", + "phpstan/phpstan": "^1.10", "phpunit/phpunit": "^9.3", - "vimeo/psalm": "4.0.1" + "squizlabs/php_codesniffer": "^3.6", + "swoole/ide-helper": "4.8.8" }, "type": "library", "autoload": { "psr-4": { - "Utopia\\Compression\\": "src/Compression" + "Utopia\\": "src/" } }, "notification-url": "https://packagist.org/downloads/", "license": [ "MIT" ], - "description": "A simple Compression library to handle file compression", + "description": "Console helpers for logging, prompting, and executing commands", "keywords": [ - "compression", - "framework", + "cli", + "console", "php", - "upf", + "terminal", "utopia" ], "support": { - "issues": "https://github.com/utopia-php/compression/issues", - "source": "https://github.com/utopia-php/compression/tree/0.1.3" + "issues": "https://github.com/utopia-php/console/issues", + "source": "https://github.com/utopia-php/console/tree/0.1.1" }, - "time": "2025-01-15T15:15:51+00:00" + "time": "2026-02-10T10:20:29+00:00" }, { "name": "utopia-php/database", - "version": "5.2.1", + "version": "dev-big-init", "source": { "type": "git", "url": "https://github.com/utopia-php/database.git", - "reference": "adfdf201144353a1d2ce14bb197ab746079894e0" + "reference": "ef5c77972a95129eb929cce6c8f7c674db930ec9" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/database/zipball/adfdf201144353a1d2ce14bb197ab746079894e0", - "reference": "adfdf201144353a1d2ce14bb197ab746079894e0", + "url": "https://api.github.com/repos/utopia-php/database/zipball/ef5c77972a95129eb929cce6c8f7c674db930ec9", + "reference": "ef5c77972a95129eb929cce6c8f7c674db930ec9", "shasum": "" }, "require": { @@ -2246,9 +2248,10 @@ "ext-pdo": "*", "php": ">=8.4", "utopia-php/cache": "1.*", - "utopia-php/framework": "0.33.*", + "utopia-php/console": "0.1.*", "utopia-php/mongo": "1.*", - "utopia-php/pools": "1.*" + "utopia-php/pools": "1.*", + "utopia-php/validators": "0.2.*" }, "require-dev": { "fakerphp/faker": "1.23.*", @@ -2258,7 +2261,7 @@ "phpunit/phpunit": "9.*", "rregeer/phpunit-coverage-check": "0.3.*", "swoole/ide-helper": "5.1.3", - "utopia-php/cli": "0.14.*" + "utopia-php/cli": "0.22.*" }, "type": "library", "autoload": { @@ -2280,9 +2283,9 @@ ], "support": { "issues": "https://github.com/utopia-php/database/issues", - "source": "https://github.com/utopia-php/database/tree/5.2.1" + "source": "https://github.com/utopia-php/database/tree/big-init" }, - "time": "2026-02-16T11:01:13+00:00" + "time": "2026-03-30T06:31:05+00:00" }, { "name": "utopia-php/dsn", @@ -2331,55 +2334,6 @@ }, "time": "2024-05-07T02:01:25+00:00" }, - { - "name": "utopia-php/framework", - "version": "0.33.39", - "source": { - "type": "git", - "url": "https://github.com/utopia-php/http.git", - "reference": "409a258814d664d3a50fa2f48b6695679334d30b" - }, - "dist": { - "type": "zip", - "url": "https://api.github.com/repos/utopia-php/http/zipball/409a258814d664d3a50fa2f48b6695679334d30b", - "reference": "409a258814d664d3a50fa2f48b6695679334d30b", - "shasum": "" - }, - "require": { - "php": ">=8.3", - "utopia-php/compression": "0.1.*", - "utopia-php/telemetry": "0.2.*", - "utopia-php/validators": "0.2.*" - }, - "require-dev": { - "laravel/pint": "1.*", - "phpbench/phpbench": "1.*", - "phpstan/phpstan": "1.*", - "phpunit/phpunit": "9.*", - "swoole/ide-helper": "^6.0" - }, - "type": "library", - "autoload": { - "psr-4": { - "Utopia\\": "src/" - } - }, - "notification-url": "https://packagist.org/downloads/", - "license": [ - "MIT" - ], - "description": "A simple, light and advanced PHP framework", - "keywords": [ - "framework", - "php", - "upf" - ], - "support": { - "issues": "https://github.com/utopia-php/http/issues", - "source": "https://github.com/utopia-php/http/tree/0.33.39" - }, - "time": "2026-02-11T06:33:42+00:00" - }, { "name": "utopia-php/mongo", "version": "1.0.0", @@ -4995,9 +4949,18 @@ "time": "2025-12-27T19:49:13+00:00" } ], - "aliases": [], + "aliases": [ + { + "package": "utopia-php/database", + "version": "dev-big-init", + "alias": "5.4", + "alias_normalized": "5.4.0.0" + } + ], "minimum-stability": "stable", - "stability-flags": {}, + "stability-flags": { + "utopia-php/database": 20 + }, "prefer-stable": false, "prefer-lowest": false, "platform": { @@ -5008,5 +4971,5 @@ "platform-dev": { "ext-pdo": "*" }, - "plugin-api-version": "2.6.0" + "plugin-api-version": "2.9.0" } diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index 0d0e7d641a..49cadb72e1 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -542,6 +542,7 @@ class Appwrite extends Destination Column::TYPE_DATETIME => UtopiaDatabase::VAR_DATETIME, Column::TYPE_BOOLEAN => UtopiaDatabase::VAR_BOOLEAN, Column::TYPE_INTEGER => UtopiaDatabase::VAR_INTEGER, + Column::TYPE_BIG_INT => UtopiaDatabase::VAR_BIGINT, Column::TYPE_FLOAT => UtopiaDatabase::VAR_FLOAT, Column::TYPE_RELATIONSHIP => UtopiaDatabase::VAR_RELATIONSHIP, diff --git a/src/Migration/Resources/Database/Column.php b/src/Migration/Resources/Database/Column.php index 45aea6d4c8..3a3ef4faa6 100644 --- a/src/Migration/Resources/Database/Column.php +++ b/src/Migration/Resources/Database/Column.php @@ -14,6 +14,7 @@ abstract class Column extends Resource public const TYPE_LONGTEXT = 'longtext'; public const TYPE_INTEGER = 'integer'; + public const TYPE_BIG_INT = 'bigint'; public const TYPE_FLOAT = 'double'; public const TYPE_BOOLEAN = 'boolean'; public const TYPE_DATETIME = 'datetime'; diff --git a/src/Migration/Resources/Database/Columns/BigInt.php b/src/Migration/Resources/Database/Columns/BigInt.php new file mode 100644 index 0000000000..7620e770d5 --- /dev/null +++ b/src/Migration/Resources/Database/Columns/BigInt.php @@ -0,0 +1,107 @@ + $min, + 'max' => $max, + ], + createdAt: $createdAt, + updatedAt: $updatedAt + ); + } + + /** + * @param array{ + * key: string, + * collection?: array{ + * database: array{ + * id: string, + * name: string, + * }, + * name: string, + * id: string, + * documentSecurity: bool, + * permissions: ?array + * }, + * table?: array{ + * database: array{ + * id: string, + * name: string, + * }, + * name: string, + * id: string, + * rowSecurity: bool, + * permissions: ?array + * }, + * required: bool, + * array: bool, + * default: ?int, + * formatOptions: array{ + * min: ?int, + * max: ?int + * }, + * createdAt: string, + * updatedAt: string, + * } $array + * @return self + */ + public static function fromArray(array $array): self + { + return new self( + $array['key'], + Table::fromArray($array['table'] ?? $array['collection']), + required: $array['required'], + default: $array['default'], + array: $array['array'], + min: $array['formatOptions']['min'] ?? null, + max: $array['formatOptions']['max'] ?? null, + createdAt: $array['createdAt'] ?? '', + updatedAt: $array['updatedAt'] ?? '', + ); + } + + public function getType(): string + { + return Column::TYPE_BIG_INT; + } + + public function getMin(): ?int + { + return (int)$this->formatOptions['min']; + } + + public function getMax(): ?int + { + return (int)$this->formatOptions['max']; + } +} diff --git a/src/Migration/Sources/Appwrite.php b/src/Migration/Sources/Appwrite.php index e5e57fa90d..db59cc9dd7 100644 --- a/src/Migration/Sources/Appwrite.php +++ b/src/Migration/Sources/Appwrite.php @@ -24,6 +24,7 @@ use Utopia\Migration\Resources\Auth\User; use Utopia\Migration\Resources\Database\Attribute; use Utopia\Migration\Resources\Database\Collection; use Utopia\Migration\Resources\Database\Column; +use Utopia\Migration\Resources\Database\Columns\BigInt; use Utopia\Migration\Resources\Database\Columns\Boolean; use Utopia\Migration\Resources\Database\Columns\DateTime; use Utopia\Migration\Resources\Database\Columns\Decimal; @@ -2368,6 +2369,18 @@ class Appwrite extends Source updatedAt: $column['$updatedAt'] ?? '', ), + Column::TYPE_BIG_INT => new BigInt( + $column['key'], + $table, + required: $column['required'], + default: $column['default'], + array: $column['array'], + min: $column['min'] ?? null, + max: $column['max'] ?? null, + createdAt: $column['$createdAt'] ?? '', + updatedAt: $column['$updatedAt'] ?? '', + ), + Column::TYPE_FLOAT => new Decimal( $column['key'], $table, diff --git a/src/Migration/Sources/CSV.php b/src/Migration/Sources/CSV.php index 7d02090faf..9b580df2d0 100644 --- a/src/Migration/Sources/CSV.php +++ b/src/Migration/Sources/CSV.php @@ -301,7 +301,7 @@ class CSV extends Source $parsedData[$key] = array_map(function ($item) use ($type) { return match ($type) { - Column::TYPE_INTEGER => is_numeric($item) ? (int)$item : null, + Column::TYPE_INTEGER,Column::TYPE_BIG_INT => is_numeric($item) ? (int)$item : null, Column::TYPE_FLOAT => is_numeric($item) ? (float)$item : null, Column::TYPE_BOOLEAN => filter_var($item, FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE), default => $item, @@ -323,6 +323,7 @@ class CSV extends Source 'null' => null, // 'null' string is converted to null '' => match ($type) { Column::TYPE_INTEGER, + Column::TYPE_BIG_INT, Column::TYPE_FLOAT, Column::TYPE_BOOLEAN, Column::TYPE_DATETIME, @@ -330,7 +331,7 @@ class CSV extends Source default => '', // but empty string stays empty string for compatibility }, default => match ($type) { - Column::TYPE_INTEGER => \is_numeric($parsedValue) ? (int)$parsedValue : null, + Column::TYPE_INTEGER, Column::TYPE_BIG_INT => \is_numeric($parsedValue) ? (int)$parsedValue : null, Column::TYPE_FLOAT => \is_numeric($parsedValue) ? (float)$parsedValue : null, Column::TYPE_BOOLEAN => \filter_var( $parsedValue, diff --git a/src/Migration/Sources/NHost.php b/src/Migration/Sources/NHost.php index 4aac49f846..ada1afb5ff 100644 --- a/src/Migration/Sources/NHost.php +++ b/src/Migration/Sources/NHost.php @@ -8,6 +8,7 @@ use Utopia\Migration\Resource; use Utopia\Migration\Resources\Auth\Hash; use Utopia\Migration\Resources\Auth\User; use Utopia\Migration\Resources\Database\Column; +use Utopia\Migration\Resources\Database\Columns\BigInt; use Utopia\Migration\Resources\Database\Columns\Boolean; use Utopia\Migration\Resources\Database\Columns\DateTime; use Utopia\Migration\Resources\Database\Columns\Decimal; @@ -679,7 +680,7 @@ class NHost extends Source $column['column_default'] = null; } - return new Integer( + return new BigInt( $column['column_name'], $table, required: $column['is_nullable'] === 'NO', From 0357de375a74069a7dedb503be2c83fbd472361c Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k <83803257+ArnabChatterjee20k@users.noreply.github.com> Date: Mon, 30 Mar 2026 15:30:38 +0530 Subject: [PATCH 08/91] Update src/Migration/Resources/Database/Columns/BigInt.php Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> --- src/Migration/Resources/Database/Columns/BigInt.php | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/Migration/Resources/Database/Columns/BigInt.php b/src/Migration/Resources/Database/Columns/BigInt.php index 7620e770d5..9cefeda90b 100644 --- a/src/Migration/Resources/Database/Columns/BigInt.php +++ b/src/Migration/Resources/Database/Columns/BigInt.php @@ -85,10 +85,12 @@ class BigInt extends Column array: $array['array'], min: $array['formatOptions']['min'] ?? null, max: $array['formatOptions']['max'] ?? null, + signed: $array['signed'] ?? true, createdAt: $array['createdAt'] ?? '', updatedAt: $array['updatedAt'] ?? '', ); } + } public function getType(): string { From 9e8708883677661ac568ba41f7a0b79cd6f04253 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Mon, 30 Mar 2026 15:33:42 +0530 Subject: [PATCH 09/91] lint --- src/Migration/Resources/Database/Columns/BigInt.php | 1 - 1 file changed, 1 deletion(-) diff --git a/src/Migration/Resources/Database/Columns/BigInt.php b/src/Migration/Resources/Database/Columns/BigInt.php index 9cefeda90b..a6d9045068 100644 --- a/src/Migration/Resources/Database/Columns/BigInt.php +++ b/src/Migration/Resources/Database/Columns/BigInt.php @@ -90,7 +90,6 @@ class BigInt extends Column updatedAt: $array['updatedAt'] ?? '', ); } - } public function getType(): string { From 0d43b66f55c25a886b7127769750dad69bab3961 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Wed, 15 Apr 2026 13:05:33 +0100 Subject: [PATCH 10/91] Wrap createDocuments in skipDuplicates for idempotent re-imports CSV / JSON / appwrite-to-appwrite imports that re-run on the same batch (e.g. user re-uploads the same file, or a worker retries a failed chunk) currently throw DuplicateException and abort the whole batch. Wrap the row-buffer flush in the new skipDuplicates() scope guard so duplicate-by-id rows are silently no-op'd at the adapter layer (INSERT IGNORE / ON CONFLICT DO NOTHING / $setOnInsert), letting the rest of the batch proceed. The existing skipRelationshipsExistCheck() wrapper is preserved (FK-target guard); skipDuplicates composes around it. Feature-branch note: depends on utopia-php/database's skipDuplicates() scope guard from PR utopia-php/database#852. composer.json is temporarily pinned to dev-csv-import-upsert-v2 with a 5.99.0 alias so composer can resolve the 5.* constraint transitively. Must be reset to the proper release version (^5.X.Y) once PR #852 merges and utopia-php/database ships. --- composer.json | 5 +- composer.lock | 301 +++++++++++------------- src/Migration/Destinations/Appwrite.php | 12 +- 3 files changed, 143 insertions(+), 175 deletions(-) diff --git a/composer.json b/composer.json index 5585f2a53f..517c74860d 100644 --- a/composer.json +++ b/composer.json @@ -4,7 +4,8 @@ "type": "library", "keywords": ["php", "framework", "upf", "utopia", "migration"], "license": "MIT", - "minimum-stability": "stable", + "minimum-stability": "dev", + "prefer-stable": true, "autoload": { "psr-4": { "Utopia\\Migration\\": "src/Migration" @@ -26,7 +27,7 @@ "ext-curl": "*", "ext-openssl": "*", "appwrite/appwrite": "19.*", - "utopia-php/database": "5.*", + "utopia-php/database": "dev-csv-import-upsert-v2 as 5.99.0", "utopia-php/storage": "1.0.*", "utopia-php/dsn": "0.2.*", "halaxa/json-machine": "^1.2" diff --git a/composer.lock b/composer.lock index 17d1422175..baebdadebc 100644 --- a/composer.lock +++ b/composer.lock @@ -4,7 +4,7 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "37980b9001fbbd4f213f3102c1332727", + "content-hash": "10d1d2946e15451bd0d1e6b2b27d8798", "packages": [ { "name": "appwrite/appwrite", @@ -187,23 +187,23 @@ }, { "name": "google/protobuf", - "version": "v4.33.5", + "version": "v4.33.6", "source": { "type": "git", "url": "https://github.com/protocolbuffers/protobuf-php.git", - "reference": "ebe8010a61b2ae0cff0d246fe1c4d44e9f7dfa6d" + "reference": "84b008c23915ed94536737eae46f41ba3bccfe67" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/protocolbuffers/protobuf-php/zipball/ebe8010a61b2ae0cff0d246fe1c4d44e9f7dfa6d", - "reference": "ebe8010a61b2ae0cff0d246fe1c4d44e9f7dfa6d", + "url": "https://api.github.com/repos/protocolbuffers/protobuf-php/zipball/84b008c23915ed94536737eae46f41ba3bccfe67", + "reference": "84b008c23915ed94536737eae46f41ba3bccfe67", "shasum": "" }, "require": { "php": ">=8.1.0" }, "require-dev": { - "phpunit/phpunit": ">=5.0.0 <8.5.27" + "phpunit/phpunit": ">=10.5.62 <11.0.0" }, "suggest": { "ext-bcmath": "Need to support JSON deserialization" @@ -225,9 +225,9 @@ "proto" ], "support": { - "source": "https://github.com/protocolbuffers/protobuf-php/tree/v4.33.5" + "source": "https://github.com/protocolbuffers/protobuf-php/tree/v4.33.6" }, - "time": "2026-01-29T20:49:00+00:00" + "time": "2026-03-18T17:32:05+00:00" }, { "name": "halaxa/json-machine", @@ -514,16 +514,16 @@ }, { "name": "open-telemetry/api", - "version": "1.8.0", + "version": "1.9.0", "source": { "type": "git", "url": "https://github.com/opentelemetry-php/api.git", - "reference": "df5197c6fd0ddd8e9883b87de042d9341300e2ad" + "reference": "6f8d237ce2c304ca85f31970f788e7f074d147be" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/opentelemetry-php/api/zipball/df5197c6fd0ddd8e9883b87de042d9341300e2ad", - "reference": "df5197c6fd0ddd8e9883b87de042d9341300e2ad", + "url": "https://api.github.com/repos/opentelemetry-php/api/zipball/6f8d237ce2c304ca85f31970f788e7f074d147be", + "reference": "6f8d237ce2c304ca85f31970f788e7f074d147be", "shasum": "" }, "require": { @@ -580,20 +580,20 @@ "issues": "https://github.com/open-telemetry/opentelemetry-php/issues", "source": "https://github.com/open-telemetry/opentelemetry-php" }, - "time": "2026-01-21T04:14:03+00:00" + "time": "2026-02-25T13:24:05+00:00" }, { "name": "open-telemetry/context", - "version": "1.4.0", + "version": "1.5.0", "source": { "type": "git", "url": "https://github.com/opentelemetry-php/context.git", - "reference": "d4c4470b541ce72000d18c339cfee633e4c8e0cf" + "reference": "3c414b246e0dabb7d6145404e6a5e4536ca18d07" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/opentelemetry-php/context/zipball/d4c4470b541ce72000d18c339cfee633e4c8e0cf", - "reference": "d4c4470b541ce72000d18c339cfee633e4c8e0cf", + "url": "https://api.github.com/repos/opentelemetry-php/context/zipball/3c414b246e0dabb7d6145404e6a5e4536ca18d07", + "reference": "3c414b246e0dabb7d6145404e6a5e4536ca18d07", "shasum": "" }, "require": { @@ -635,11 +635,11 @@ ], "support": { "chat": "https://app.slack.com/client/T08PSQ7BQ/C01NFPCV44V", - "docs": "https://opentelemetry.io/docs/php", + "docs": "https://opentelemetry.io/docs/languages/php", "issues": "https://github.com/open-telemetry/opentelemetry-php/issues", "source": "https://github.com/open-telemetry/opentelemetry-php" }, - "time": "2025-09-19T00:05:49+00:00" + "time": "2025-10-19T06:44:33+00:00" }, { "name": "open-telemetry/exporter-otlp", @@ -707,16 +707,16 @@ }, { "name": "open-telemetry/gen-otlp-protobuf", - "version": "1.8.0", + "version": "1.9.0", "source": { "type": "git", "url": "https://github.com/opentelemetry-php/gen-otlp-protobuf.git", - "reference": "673af5b06545b513466081884b47ef15a536edde" + "reference": "a229cf161d42001d64c8f21e8f678581fe1c66b9" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/opentelemetry-php/gen-otlp-protobuf/zipball/673af5b06545b513466081884b47ef15a536edde", - "reference": "673af5b06545b513466081884b47ef15a536edde", + "url": "https://api.github.com/repos/opentelemetry-php/gen-otlp-protobuf/zipball/a229cf161d42001d64c8f21e8f678581fe1c66b9", + "reference": "a229cf161d42001d64c8f21e8f678581fe1c66b9", "shasum": "" }, "require": { @@ -762,30 +762,30 @@ ], "support": { "chat": "https://app.slack.com/client/T08PSQ7BQ/C01NFPCV44V", - "docs": "https://opentelemetry.io/docs/php", + "docs": "https://opentelemetry.io/docs/languages/php", "issues": "https://github.com/open-telemetry/opentelemetry-php/issues", "source": "https://github.com/open-telemetry/opentelemetry-php" }, - "time": "2025-09-17T23:10:12+00:00" + "time": "2025-10-19T06:44:33+00:00" }, { "name": "open-telemetry/sdk", - "version": "1.13.0", + "version": "1.14.0", "source": { "type": "git", "url": "https://github.com/opentelemetry-php/sdk.git", - "reference": "c76f91203bf7ef98ab3f4e0a82ca21699af185e1" + "reference": "6e3d0ce93e76555dd5e2f1d19443ff45b990e410" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/opentelemetry-php/sdk/zipball/c76f91203bf7ef98ab3f4e0a82ca21699af185e1", - "reference": "c76f91203bf7ef98ab3f4e0a82ca21699af185e1", + "url": "https://api.github.com/repos/opentelemetry-php/sdk/zipball/6e3d0ce93e76555dd5e2f1d19443ff45b990e410", + "reference": "6e3d0ce93e76555dd5e2f1d19443ff45b990e410", "shasum": "" }, "require": { "ext-json": "*", "nyholm/psr7-server": "^1.1", - "open-telemetry/api": "^1.7", + "open-telemetry/api": "^1.8", "open-telemetry/context": "^1.4", "open-telemetry/sem-conv": "^1.0", "php": "^8.1", @@ -863,7 +863,7 @@ "issues": "https://github.com/open-telemetry/opentelemetry-php/issues", "source": "https://github.com/open-telemetry/opentelemetry-php" }, - "time": "2026-01-28T11:38:11+00:00" + "time": "2026-03-21T11:50:01+00:00" }, { "name": "open-telemetry/sem-conv", @@ -1487,16 +1487,16 @@ }, { "name": "symfony/http-client", - "version": "v7.4.5", + "version": "v7.4.8", "source": { "type": "git", "url": "https://github.com/symfony/http-client.git", - "reference": "84bb634857a893cc146cceb467e31b3f02c5fe9f" + "reference": "01933e626c3de76bea1e22641e205e78f6a34342" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/symfony/http-client/zipball/84bb634857a893cc146cceb467e31b3f02c5fe9f", - "reference": "84bb634857a893cc146cceb467e31b3f02c5fe9f", + "url": "https://api.github.com/repos/symfony/http-client/zipball/01933e626c3de76bea1e22641e205e78f6a34342", + "reference": "01933e626c3de76bea1e22641e205e78f6a34342", "shasum": "" }, "require": { @@ -1564,7 +1564,7 @@ "http" ], "support": { - "source": "https://github.com/symfony/http-client/tree/v7.4.5" + "source": "https://github.com/symfony/http-client/tree/v7.4.8" }, "funding": [ { @@ -1584,7 +1584,7 @@ "type": "tidelift" } ], - "time": "2026-01-27T16:16:02+00:00" + "time": "2026-03-30T12:55:43+00:00" }, { "name": "symfony/http-client-contracts", @@ -1666,16 +1666,16 @@ }, { "name": "symfony/polyfill-mbstring", - "version": "v1.33.0", + "version": "v1.35.0", "source": { "type": "git", "url": "https://github.com/symfony/polyfill-mbstring.git", - "reference": "6d857f4d76bd4b343eac26d6b539585d2bc56493" + "reference": "6a21eb99c6973357967f6ce3708cd55a6bec6315" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/symfony/polyfill-mbstring/zipball/6d857f4d76bd4b343eac26d6b539585d2bc56493", - "reference": "6d857f4d76bd4b343eac26d6b539585d2bc56493", + "url": "https://api.github.com/repos/symfony/polyfill-mbstring/zipball/6a21eb99c6973357967f6ce3708cd55a6bec6315", + "reference": "6a21eb99c6973357967f6ce3708cd55a6bec6315", "shasum": "" }, "require": { @@ -1727,7 +1727,7 @@ "shim" ], "support": { - "source": "https://github.com/symfony/polyfill-mbstring/tree/v1.33.0" + "source": "https://github.com/symfony/polyfill-mbstring/tree/v1.35.0" }, "funding": [ { @@ -1747,20 +1747,20 @@ "type": "tidelift" } ], - "time": "2024-12-23T08:48:59+00:00" + "time": "2026-04-10T17:25:58+00:00" }, { "name": "symfony/polyfill-php82", - "version": "v1.33.0", + "version": "v1.35.0", "source": { "type": "git", "url": "https://github.com/symfony/polyfill-php82.git", - "reference": "5d2ed36f7734637dacc025f179698031951b1692" + "reference": "34808efe3e68f69685796f7c253a2f1d8ea9df59" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/symfony/polyfill-php82/zipball/5d2ed36f7734637dacc025f179698031951b1692", - "reference": "5d2ed36f7734637dacc025f179698031951b1692", + "url": "https://api.github.com/repos/symfony/polyfill-php82/zipball/34808efe3e68f69685796f7c253a2f1d8ea9df59", + "reference": "34808efe3e68f69685796f7c253a2f1d8ea9df59", "shasum": "" }, "require": { @@ -1807,7 +1807,7 @@ "shim" ], "support": { - "source": "https://github.com/symfony/polyfill-php82/tree/v1.33.0" + "source": "https://github.com/symfony/polyfill-php82/tree/v1.35.0" }, "funding": [ { @@ -1827,20 +1827,20 @@ "type": "tidelift" } ], - "time": "2024-09-09T11:45:10+00:00" + "time": "2026-04-10T16:19:22+00:00" }, { "name": "symfony/polyfill-php83", - "version": "v1.33.0", + "version": "v1.35.0", "source": { "type": "git", "url": "https://github.com/symfony/polyfill-php83.git", - "reference": "17f6f9a6b1735c0f163024d959f700cfbc5155e5" + "reference": "3600c2cb22399e25bb226e4a135ce91eeb2a6149" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/symfony/polyfill-php83/zipball/17f6f9a6b1735c0f163024d959f700cfbc5155e5", - "reference": "17f6f9a6b1735c0f163024d959f700cfbc5155e5", + "url": "https://api.github.com/repos/symfony/polyfill-php83/zipball/3600c2cb22399e25bb226e4a135ce91eeb2a6149", + "reference": "3600c2cb22399e25bb226e4a135ce91eeb2a6149", "shasum": "" }, "require": { @@ -1887,7 +1887,7 @@ "shim" ], "support": { - "source": "https://github.com/symfony/polyfill-php83/tree/v1.33.0" + "source": "https://github.com/symfony/polyfill-php83/tree/v1.35.0" }, "funding": [ { @@ -1907,20 +1907,20 @@ "type": "tidelift" } ], - "time": "2025-07-08T02:45:35+00:00" + "time": "2026-04-10T17:25:58+00:00" }, { "name": "symfony/polyfill-php85", - "version": "v1.33.0", + "version": "v1.35.0", "source": { "type": "git", "url": "https://github.com/symfony/polyfill-php85.git", - "reference": "d4e5fcd4ab3d998ab16c0db48e6cbb9a01993f91" + "reference": "2c408a6bb0313e6001a83628dc5506100474254e" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/symfony/polyfill-php85/zipball/d4e5fcd4ab3d998ab16c0db48e6cbb9a01993f91", - "reference": "d4e5fcd4ab3d998ab16c0db48e6cbb9a01993f91", + "url": "https://api.github.com/repos/symfony/polyfill-php85/zipball/2c408a6bb0313e6001a83628dc5506100474254e", + "reference": "2c408a6bb0313e6001a83628dc5506100474254e", "shasum": "" }, "require": { @@ -1967,7 +1967,7 @@ "shim" ], "support": { - "source": "https://github.com/symfony/polyfill-php85/tree/v1.33.0" + "source": "https://github.com/symfony/polyfill-php85/tree/v1.35.0" }, "funding": [ { @@ -1987,7 +1987,7 @@ "type": "tidelift" } ], - "time": "2025-06-23T16:12:55+00:00" + "time": "2026-04-10T16:50:15+00:00" }, { "name": "symfony/service-contracts", @@ -2130,16 +2130,16 @@ }, { "name": "utopia-php/cache", - "version": "1.0.0", + "version": "1.0.1", "source": { "type": "git", "url": "https://github.com/utopia-php/cache.git", - "reference": "7068870c086a6aea16173563a26b93ef3e408439" + "reference": "05ceba981436a4022553f7aaa2a05fa049d0f71c" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/cache/zipball/7068870c086a6aea16173563a26b93ef3e408439", - "reference": "7068870c086a6aea16173563a26b93ef3e408439", + "url": "https://api.github.com/repos/utopia-php/cache/zipball/05ceba981436a4022553f7aaa2a05fa049d0f71c", + "reference": "05ceba981436a4022553f7aaa2a05fa049d0f71c", "shasum": "" }, "require": { @@ -2176,22 +2176,22 @@ ], "support": { "issues": "https://github.com/utopia-php/cache/issues", - "source": "https://github.com/utopia-php/cache/tree/1.0.0" + "source": "https://github.com/utopia-php/cache/tree/1.0.1" }, - "time": "2026-01-28T10:55:44+00:00" + "time": "2026-03-12T03:39:09+00:00" }, { - "name": "utopia-php/compression", - "version": "0.1.3", + "name": "utopia-php/console", + "version": "0.1.1", "source": { "type": "git", - "url": "https://github.com/utopia-php/compression.git", - "reference": "66f093557ba66d98245e562036182016c7dcfe8a" + "url": "https://github.com/utopia-php/console.git", + "reference": "d298e43960780e6d76e66de1228c75dc81220e3e" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/compression/zipball/66f093557ba66d98245e562036182016c7dcfe8a", - "reference": "66f093557ba66d98245e562036182016c7dcfe8a", + "url": "https://api.github.com/repos/utopia-php/console/zipball/d298e43960780e6d76e66de1228c75dc81220e3e", + "reference": "d298e43960780e6d76e66de1228c75dc81220e3e", "shasum": "" }, "require": { @@ -2199,45 +2199,47 @@ }, "require-dev": { "laravel/pint": "1.2.*", + "phpstan/phpstan": "^1.10", "phpunit/phpunit": "^9.3", - "vimeo/psalm": "4.0.1" + "squizlabs/php_codesniffer": "^3.6", + "swoole/ide-helper": "4.8.8" }, "type": "library", "autoload": { "psr-4": { - "Utopia\\Compression\\": "src/Compression" + "Utopia\\": "src/" } }, "notification-url": "https://packagist.org/downloads/", "license": [ "MIT" ], - "description": "A simple Compression library to handle file compression", + "description": "Console helpers for logging, prompting, and executing commands", "keywords": [ - "compression", - "framework", + "cli", + "console", "php", - "upf", + "terminal", "utopia" ], "support": { - "issues": "https://github.com/utopia-php/compression/issues", - "source": "https://github.com/utopia-php/compression/tree/0.1.3" + "issues": "https://github.com/utopia-php/console/issues", + "source": "https://github.com/utopia-php/console/tree/0.1.1" }, - "time": "2025-01-15T15:15:51+00:00" + "time": "2026-02-10T10:20:29+00:00" }, { "name": "utopia-php/database", - "version": "5.2.1", + "version": "dev-csv-import-upsert-v2", "source": { "type": "git", "url": "https://github.com/utopia-php/database.git", - "reference": "adfdf201144353a1d2ce14bb197ab746079894e0" + "reference": "52b189bded7ef409bb978483a7231d779051b510" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/database/zipball/adfdf201144353a1d2ce14bb197ab746079894e0", - "reference": "adfdf201144353a1d2ce14bb197ab746079894e0", + "url": "https://api.github.com/repos/utopia-php/database/zipball/52b189bded7ef409bb978483a7231d779051b510", + "reference": "52b189bded7ef409bb978483a7231d779051b510", "shasum": "" }, "require": { @@ -2246,9 +2248,10 @@ "ext-pdo": "*", "php": ">=8.4", "utopia-php/cache": "1.*", - "utopia-php/framework": "0.33.*", + "utopia-php/console": "0.1.*", "utopia-php/mongo": "1.*", - "utopia-php/pools": "1.*" + "utopia-php/pools": "1.*", + "utopia-php/validators": "0.2.*" }, "require-dev": { "fakerphp/faker": "1.23.*", @@ -2258,7 +2261,7 @@ "phpunit/phpunit": "9.*", "rregeer/phpunit-coverage-check": "0.3.*", "swoole/ide-helper": "5.1.3", - "utopia-php/cli": "0.14.*" + "utopia-php/cli": "0.22.*" }, "type": "library", "autoload": { @@ -2280,9 +2283,9 @@ ], "support": { "issues": "https://github.com/utopia-php/database/issues", - "source": "https://github.com/utopia-php/database/tree/5.2.1" + "source": "https://github.com/utopia-php/database/tree/csv-import-upsert-v2" }, - "time": "2026-02-16T11:01:13+00:00" + "time": "2026-04-15T10:53:53+00:00" }, { "name": "utopia-php/dsn", @@ -2331,67 +2334,18 @@ }, "time": "2024-05-07T02:01:25+00:00" }, - { - "name": "utopia-php/framework", - "version": "0.33.39", - "source": { - "type": "git", - "url": "https://github.com/utopia-php/http.git", - "reference": "409a258814d664d3a50fa2f48b6695679334d30b" - }, - "dist": { - "type": "zip", - "url": "https://api.github.com/repos/utopia-php/http/zipball/409a258814d664d3a50fa2f48b6695679334d30b", - "reference": "409a258814d664d3a50fa2f48b6695679334d30b", - "shasum": "" - }, - "require": { - "php": ">=8.3", - "utopia-php/compression": "0.1.*", - "utopia-php/telemetry": "0.2.*", - "utopia-php/validators": "0.2.*" - }, - "require-dev": { - "laravel/pint": "1.*", - "phpbench/phpbench": "1.*", - "phpstan/phpstan": "1.*", - "phpunit/phpunit": "9.*", - "swoole/ide-helper": "^6.0" - }, - "type": "library", - "autoload": { - "psr-4": { - "Utopia\\": "src/" - } - }, - "notification-url": "https://packagist.org/downloads/", - "license": [ - "MIT" - ], - "description": "A simple, light and advanced PHP framework", - "keywords": [ - "framework", - "php", - "upf" - ], - "support": { - "issues": "https://github.com/utopia-php/http/issues", - "source": "https://github.com/utopia-php/http/tree/0.33.39" - }, - "time": "2026-02-11T06:33:42+00:00" - }, { "name": "utopia-php/mongo", - "version": "1.0.0", + "version": "1.0.2", "source": { "type": "git", "url": "https://github.com/utopia-php/mongo.git", - "reference": "45bedf36c2c946ec7a0a3e59b9f12f772de0b01d" + "reference": "677a21c53f7a1316c528b4b45b3fce886cee7223" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/mongo/zipball/45bedf36c2c946ec7a0a3e59b9f12f772de0b01d", - "reference": "45bedf36c2c946ec7a0a3e59b9f12f772de0b01d", + "url": "https://api.github.com/repos/utopia-php/mongo/zipball/677a21c53f7a1316c528b4b45b3fce886cee7223", + "reference": "677a21c53f7a1316c528b4b45b3fce886cee7223", "shasum": "" }, "require": { @@ -2437,22 +2391,22 @@ ], "support": { "issues": "https://github.com/utopia-php/mongo/issues", - "source": "https://github.com/utopia-php/mongo/tree/1.0.0" + "source": "https://github.com/utopia-php/mongo/tree/1.0.2" }, - "time": "2026-02-12T05:54:06+00:00" + "time": "2026-03-18T02:45:50+00:00" }, { "name": "utopia-php/pools", - "version": "1.0.2", + "version": "1.0.3", "source": { "type": "git", "url": "https://github.com/utopia-php/pools.git", - "reference": "b7d8dd00306cdd8bf3ff6f1dc90caeaf27dabeb1" + "reference": "74de7c5457a2c447f27e7ec4d72e8412a7d68c10" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/pools/zipball/b7d8dd00306cdd8bf3ff6f1dc90caeaf27dabeb1", - "reference": "b7d8dd00306cdd8bf3ff6f1dc90caeaf27dabeb1", + "url": "https://api.github.com/repos/utopia-php/pools/zipball/74de7c5457a2c447f27e7ec4d72e8412a7d68c10", + "reference": "74de7c5457a2c447f27e7ec4d72e8412a7d68c10", "shasum": "" }, "require": { @@ -2490,9 +2444,9 @@ ], "support": { "issues": "https://github.com/utopia-php/pools/issues", - "source": "https://github.com/utopia-php/pools/tree/1.0.2" + "source": "https://github.com/utopia-php/pools/tree/1.0.3" }, - "time": "2026-01-28T13:12:36+00:00" + "time": "2026-02-26T08:42:40+00:00" }, { "name": "utopia-php/storage", @@ -4695,16 +4649,16 @@ }, { "name": "symfony/polyfill-ctype", - "version": "v1.33.0", + "version": "v1.35.0", "source": { "type": "git", "url": "https://github.com/symfony/polyfill-ctype.git", - "reference": "a3cc8b044a6ea513310cbd48ef7333b384945638" + "reference": "141046a8f9477948ff284fa65be2095baafb94f2" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/symfony/polyfill-ctype/zipball/a3cc8b044a6ea513310cbd48ef7333b384945638", - "reference": "a3cc8b044a6ea513310cbd48ef7333b384945638", + "url": "https://api.github.com/repos/symfony/polyfill-ctype/zipball/141046a8f9477948ff284fa65be2095baafb94f2", + "reference": "141046a8f9477948ff284fa65be2095baafb94f2", "shasum": "" }, "require": { @@ -4754,7 +4708,7 @@ "portable" ], "support": { - "source": "https://github.com/symfony/polyfill-ctype/tree/v1.33.0" + "source": "https://github.com/symfony/polyfill-ctype/tree/v1.35.0" }, "funding": [ { @@ -4774,20 +4728,20 @@ "type": "tidelift" } ], - "time": "2024-09-09T11:45:10+00:00" + "time": "2026-04-10T16:19:22+00:00" }, { "name": "symfony/polyfill-php80", - "version": "v1.33.0", + "version": "v1.35.0", "source": { "type": "git", "url": "https://github.com/symfony/polyfill-php80.git", - "reference": "0cc9dd0f17f61d8131e7df6b84bd344899fe2608" + "reference": "dfb55726c3a76ea3b6459fcfda1ec2d80a682411" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/symfony/polyfill-php80/zipball/0cc9dd0f17f61d8131e7df6b84bd344899fe2608", - "reference": "0cc9dd0f17f61d8131e7df6b84bd344899fe2608", + "url": "https://api.github.com/repos/symfony/polyfill-php80/zipball/dfb55726c3a76ea3b6459fcfda1ec2d80a682411", + "reference": "dfb55726c3a76ea3b6459fcfda1ec2d80a682411", "shasum": "" }, "require": { @@ -4838,7 +4792,7 @@ "shim" ], "support": { - "source": "https://github.com/symfony/polyfill-php80/tree/v1.33.0" + "source": "https://github.com/symfony/polyfill-php80/tree/v1.35.0" }, "funding": [ { @@ -4858,7 +4812,7 @@ "type": "tidelift" } ], - "time": "2025-01-02T08:10:11+00:00" + "time": "2026-04-10T16:19:22+00:00" }, { "name": "theseer/tokenizer", @@ -4995,10 +4949,19 @@ "time": "2025-12-27T19:49:13+00:00" } ], - "aliases": [], - "minimum-stability": "stable", - "stability-flags": {}, - "prefer-stable": false, + "aliases": [ + { + "package": "utopia-php/database", + "version": "dev-csv-import-upsert-v2", + "alias": "5.99.0", + "alias_normalized": "5.99.0.0" + } + ], + "minimum-stability": "dev", + "stability-flags": { + "utopia-php/database": 20 + }, + "prefer-stable": true, "prefer-lowest": false, "platform": { "php": ">=8.1", @@ -5008,5 +4971,5 @@ "platform-dev": { "ext-pdo": "*" }, - "plugin-api-version": "2.6.0" + "plugin-api-version": "2.9.0" } diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index 0d0e7d641a..7b02a0a473 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -1067,10 +1067,14 @@ class Appwrite extends Destination } } } - $dbForDatabases->skipRelationshipsExistCheck(fn () => $dbForDatabases->createDocuments( - 'database_' . $databaseInternalId . '_collection_' . $tableInternalId, - $this->rowBuffer - )); + $dbForDatabases->skipDuplicates( + fn () => $dbForDatabases->skipRelationshipsExistCheck( + fn () => $dbForDatabases->createDocuments( + 'database_' . $databaseInternalId . '_collection_' . $tableInternalId, + $this->rowBuffer + ) + ) + ); } finally { $this->rowBuffer = []; From 2012cda162ad0ab79678c924d7534de6f3ec85ad Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Wed, 15 Apr 2026 13:36:51 +0100 Subject: [PATCH 11/91] DestinationAppwrite: add overwrite and skip params MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per Jake's spec, migration destinations accept two new behavior flags: - overwrite=true → use upsertDocuments() instead of createDocuments() Replaces existing rows with the imported values. Naturally handles duplicate ids. - skip=true → wrap createDocuments() in skipDuplicates() scope guard. Silently no-ops duplicate ids at the adapter layer (INSERT IGNORE equivalent). Existing rows are preserved. Default (both false): plain createDocuments, fails fast on DuplicateException. Original behavior, unchanged for existing callers. Precedence when both set: overwrite wins (upsert subsumes skip). The existing skipRelationshipsExistCheck() FK-guard wrapper is preserved in all three branches. --- src/Migration/Destinations/Appwrite.php | 33 +++++++++++++++++++------ 1 file changed, 25 insertions(+), 8 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index 7b02a0a473..bbe0cc2282 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -92,6 +92,8 @@ class Appwrite extends Destination * @param UtopiaDatabase $dbForProject * @param callable(UtopiaDocument $database):UtopiaDatabase $getDatabasesDB * @param array> $collectionStructure + * @param bool $overwrite When true, replace existing rows by calling upsertDocuments instead of createDocuments. + * @param bool $skip When true, silently ignore duplicate-id rows by wrapping createDocuments in skipDuplicates. */ public function __construct( string $project, @@ -99,7 +101,9 @@ class Appwrite extends Destination string $key, protected UtopiaDatabase $dbForProject, callable $getDatabasesDB, - protected array $collectionStructure + protected array $collectionStructure, + protected bool $overwrite = false, + protected bool $skip = false, ) { $this->project = $project; $this->endpoint = $endpoint; @@ -1067,14 +1071,27 @@ class Appwrite extends Destination } } } - $dbForDatabases->skipDuplicates( - fn () => $dbForDatabases->skipRelationshipsExistCheck( - fn () => $dbForDatabases->createDocuments( - 'database_' . $databaseInternalId . '_collection_' . $tableInternalId, - $this->rowBuffer + $collectionId = 'database_' . $databaseInternalId . '_collection_' . $tableInternalId; + + if ($this->overwrite) { + // Replace existing rows with the imported values. Upsert naturally + // handles duplicates so skipDuplicates is unnecessary here. + $dbForDatabases->skipRelationshipsExistCheck( + fn () => $dbForDatabases->upsertDocuments($collectionId, $this->rowBuffer) + ); + } elseif ($this->skip) { + // Silently ignore duplicates via the adapter-level INSERT IGNORE equivalent. + $dbForDatabases->skipDuplicates( + fn () => $dbForDatabases->skipRelationshipsExistCheck( + fn () => $dbForDatabases->createDocuments($collectionId, $this->rowBuffer) ) - ) - ); + ); + } else { + // Default: fail fast on duplicate ids (original behavior). + $dbForDatabases->skipRelationshipsExistCheck( + fn () => $dbForDatabases->createDocuments($collectionId, $this->rowBuffer) + ); + } } finally { $this->rowBuffer = []; From 71efc763e62f7c452e4b238ab092e3a6f836e2eb Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Mon, 20 Apr 2026 09:37:24 +0100 Subject: [PATCH 12/91] Bump utopia-php/database to 5.3.22 --- composer.json | 2 +- composer.lock | 51 +++++++++++++++++++++------------------------------ 2 files changed, 22 insertions(+), 31 deletions(-) diff --git a/composer.json b/composer.json index 517c74860d..4179fe81e2 100644 --- a/composer.json +++ b/composer.json @@ -27,7 +27,7 @@ "ext-curl": "*", "ext-openssl": "*", "appwrite/appwrite": "19.*", - "utopia-php/database": "dev-csv-import-upsert-v2 as 5.99.0", + "utopia-php/database": "5.3.22", "utopia-php/storage": "1.0.*", "utopia-php/dsn": "0.2.*", "halaxa/json-machine": "^1.2" diff --git a/composer.lock b/composer.lock index baebdadebc..7689d2edcc 100644 --- a/composer.lock +++ b/composer.lock @@ -4,7 +4,7 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "10d1d2946e15451bd0d1e6b2b27d8798", + "content-hash": "d689ed25a7660f4c1f4a293b49e36fce", "packages": [ { "name": "appwrite/appwrite", @@ -1666,7 +1666,7 @@ }, { "name": "symfony/polyfill-mbstring", - "version": "v1.35.0", + "version": "v1.36.0", "source": { "type": "git", "url": "https://github.com/symfony/polyfill-mbstring.git", @@ -1727,7 +1727,7 @@ "shim" ], "support": { - "source": "https://github.com/symfony/polyfill-mbstring/tree/v1.35.0" + "source": "https://github.com/symfony/polyfill-mbstring/tree/v1.36.0" }, "funding": [ { @@ -1751,7 +1751,7 @@ }, { "name": "symfony/polyfill-php82", - "version": "v1.35.0", + "version": "v1.36.0", "source": { "type": "git", "url": "https://github.com/symfony/polyfill-php82.git", @@ -1807,7 +1807,7 @@ "shim" ], "support": { - "source": "https://github.com/symfony/polyfill-php82/tree/v1.35.0" + "source": "https://github.com/symfony/polyfill-php82/tree/v1.36.0" }, "funding": [ { @@ -1831,7 +1831,7 @@ }, { "name": "symfony/polyfill-php83", - "version": "v1.35.0", + "version": "v1.36.0", "source": { "type": "git", "url": "https://github.com/symfony/polyfill-php83.git", @@ -1887,7 +1887,7 @@ "shim" ], "support": { - "source": "https://github.com/symfony/polyfill-php83/tree/v1.35.0" + "source": "https://github.com/symfony/polyfill-php83/tree/v1.36.0" }, "funding": [ { @@ -1911,7 +1911,7 @@ }, { "name": "symfony/polyfill-php85", - "version": "v1.35.0", + "version": "v1.36.0", "source": { "type": "git", "url": "https://github.com/symfony/polyfill-php85.git", @@ -1967,7 +1967,7 @@ "shim" ], "support": { - "source": "https://github.com/symfony/polyfill-php85/tree/v1.35.0" + "source": "https://github.com/symfony/polyfill-php85/tree/v1.36.0" }, "funding": [ { @@ -2230,16 +2230,16 @@ }, { "name": "utopia-php/database", - "version": "dev-csv-import-upsert-v2", + "version": "5.3.22", "source": { "type": "git", "url": "https://github.com/utopia-php/database.git", - "reference": "52b189bded7ef409bb978483a7231d779051b510" + "reference": "d765945da6b3141852014b2f96ecf1fe7e3d6ba7" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/database/zipball/52b189bded7ef409bb978483a7231d779051b510", - "reference": "52b189bded7ef409bb978483a7231d779051b510", + "url": "https://api.github.com/repos/utopia-php/database/zipball/d765945da6b3141852014b2f96ecf1fe7e3d6ba7", + "reference": "d765945da6b3141852014b2f96ecf1fe7e3d6ba7", "shasum": "" }, "require": { @@ -2283,9 +2283,9 @@ ], "support": { "issues": "https://github.com/utopia-php/database/issues", - "source": "https://github.com/utopia-php/database/tree/csv-import-upsert-v2" + "source": "https://github.com/utopia-php/database/tree/5.3.22" }, - "time": "2026-04-15T10:53:53+00:00" + "time": "2026-04-20T07:12:46+00:00" }, { "name": "utopia-php/dsn", @@ -4649,7 +4649,7 @@ }, { "name": "symfony/polyfill-ctype", - "version": "v1.35.0", + "version": "v1.36.0", "source": { "type": "git", "url": "https://github.com/symfony/polyfill-ctype.git", @@ -4708,7 +4708,7 @@ "portable" ], "support": { - "source": "https://github.com/symfony/polyfill-ctype/tree/v1.35.0" + "source": "https://github.com/symfony/polyfill-ctype/tree/v1.36.0" }, "funding": [ { @@ -4732,7 +4732,7 @@ }, { "name": "symfony/polyfill-php80", - "version": "v1.35.0", + "version": "v1.36.0", "source": { "type": "git", "url": "https://github.com/symfony/polyfill-php80.git", @@ -4792,7 +4792,7 @@ "shim" ], "support": { - "source": "https://github.com/symfony/polyfill-php80/tree/v1.35.0" + "source": "https://github.com/symfony/polyfill-php80/tree/v1.36.0" }, "funding": [ { @@ -4949,18 +4949,9 @@ "time": "2025-12-27T19:49:13+00:00" } ], - "aliases": [ - { - "package": "utopia-php/database", - "version": "dev-csv-import-upsert-v2", - "alias": "5.99.0", - "alias_normalized": "5.99.0.0" - } - ], + "aliases": [], "minimum-stability": "dev", - "stability-flags": { - "utopia-php/database": 20 - }, + "stability-flags": {}, "prefer-stable": true, "prefer-lowest": false, "platform": { From 6025318d61c15355015c0e34427480e84ad690ad Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Mon, 20 Apr 2026 10:07:20 +0100 Subject: [PATCH 13/91] Replace $overwrite/$skip with $onDuplicate enum-like string --- src/Migration/Destinations/Appwrite.php | 47 +++++++++++++++---------- 1 file changed, 29 insertions(+), 18 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index bbe0cc2282..bc5e01d46b 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -63,6 +63,19 @@ use Utopia\Migration\Transfer; class Appwrite extends Destination { + public const ON_DUPLICATE_FAIL = 'fail'; + public const ON_DUPLICATE_SKIP = 'skip'; + public const ON_DUPLICATE_UPSERT = 'upsert'; + + /** + * @var array + */ + public const ON_DUPLICATES = [ + self::ON_DUPLICATE_FAIL, + self::ON_DUPLICATE_SKIP, + self::ON_DUPLICATE_UPSERT, + ]; + protected Client $client; protected string $project; @@ -92,8 +105,7 @@ class Appwrite extends Destination * @param UtopiaDatabase $dbForProject * @param callable(UtopiaDocument $database):UtopiaDatabase $getDatabasesDB * @param array> $collectionStructure - * @param bool $overwrite When true, replace existing rows by calling upsertDocuments instead of createDocuments. - * @param bool $skip When true, silently ignore duplicate-id rows by wrapping createDocuments in skipDuplicates. + * @param string $onDuplicate Behavior when a row with an existing $id is encountered. One of ON_DUPLICATE_FAIL (abort), ON_DUPLICATE_SKIP (silently ignore), ON_DUPLICATE_UPSERT (replace existing). */ public function __construct( string $project, @@ -102,9 +114,14 @@ class Appwrite extends Destination protected UtopiaDatabase $dbForProject, callable $getDatabasesDB, protected array $collectionStructure, - protected bool $overwrite = false, - protected bool $skip = false, + protected string $onDuplicate = self::ON_DUPLICATE_FAIL, ) { + if (!\in_array($onDuplicate, self::ON_DUPLICATES, true)) { + throw new \InvalidArgumentException( + "Invalid onDuplicate value '{$onDuplicate}'. Must be one of: " . \implode(', ', self::ON_DUPLICATES) + ); + } + $this->project = $project; $this->endpoint = $endpoint; $this->key = $key; @@ -1073,25 +1090,19 @@ class Appwrite extends Destination } $collectionId = 'database_' . $databaseInternalId . '_collection_' . $tableInternalId; - if ($this->overwrite) { - // Replace existing rows with the imported values. Upsert naturally - // handles duplicates so skipDuplicates is unnecessary here. - $dbForDatabases->skipRelationshipsExistCheck( + match ($this->onDuplicate) { + self::ON_DUPLICATE_UPSERT => $dbForDatabases->skipRelationshipsExistCheck( fn () => $dbForDatabases->upsertDocuments($collectionId, $this->rowBuffer) - ); - } elseif ($this->skip) { - // Silently ignore duplicates via the adapter-level INSERT IGNORE equivalent. - $dbForDatabases->skipDuplicates( + ), + self::ON_DUPLICATE_SKIP => $dbForDatabases->skipDuplicates( fn () => $dbForDatabases->skipRelationshipsExistCheck( fn () => $dbForDatabases->createDocuments($collectionId, $this->rowBuffer) ) - ); - } else { - // Default: fail fast on duplicate ids (original behavior). - $dbForDatabases->skipRelationshipsExistCheck( + ), + self::ON_DUPLICATE_FAIL => $dbForDatabases->skipRelationshipsExistCheck( fn () => $dbForDatabases->createDocuments($collectionId, $this->rowBuffer) - ); - } + ), + }; } finally { $this->rowBuffer = []; From 79dd2d9b96805db1623dbe9d5a88a527780fa4ae Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Mon, 20 Apr 2026 10:45:37 +0100 Subject: [PATCH 14/91] Revert composer.json dev-stability pin, resolve database via 5.* wildcard --- composer.json | 5 +- composer.lock | 186 +++++++++++++++++++++++++------------------------- 2 files changed, 95 insertions(+), 96 deletions(-) diff --git a/composer.json b/composer.json index 4179fe81e2..5585f2a53f 100644 --- a/composer.json +++ b/composer.json @@ -4,8 +4,7 @@ "type": "library", "keywords": ["php", "framework", "upf", "utopia", "migration"], "license": "MIT", - "minimum-stability": "dev", - "prefer-stable": true, + "minimum-stability": "stable", "autoload": { "psr-4": { "Utopia\\Migration\\": "src/Migration" @@ -27,7 +26,7 @@ "ext-curl": "*", "ext-openssl": "*", "appwrite/appwrite": "19.*", - "utopia-php/database": "5.3.22", + "utopia-php/database": "5.*", "utopia-php/storage": "1.0.*", "utopia-php/dsn": "0.2.*", "halaxa/json-machine": "^1.2" diff --git a/composer.lock b/composer.lock index 7689d2edcc..1df76054f6 100644 --- a/composer.lock +++ b/composer.lock @@ -4,7 +4,7 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "d689ed25a7660f4c1f4a293b49e36fce", + "content-hash": "37980b9001fbbd4f213f3102c1332727", "packages": [ { "name": "appwrite/appwrite", @@ -187,23 +187,23 @@ }, { "name": "google/protobuf", - "version": "v4.33.6", + "version": "v4.33.5", "source": { "type": "git", "url": "https://github.com/protocolbuffers/protobuf-php.git", - "reference": "84b008c23915ed94536737eae46f41ba3bccfe67" + "reference": "ebe8010a61b2ae0cff0d246fe1c4d44e9f7dfa6d" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/protocolbuffers/protobuf-php/zipball/84b008c23915ed94536737eae46f41ba3bccfe67", - "reference": "84b008c23915ed94536737eae46f41ba3bccfe67", + "url": "https://api.github.com/repos/protocolbuffers/protobuf-php/zipball/ebe8010a61b2ae0cff0d246fe1c4d44e9f7dfa6d", + "reference": "ebe8010a61b2ae0cff0d246fe1c4d44e9f7dfa6d", "shasum": "" }, "require": { "php": ">=8.1.0" }, "require-dev": { - "phpunit/phpunit": ">=10.5.62 <11.0.0" + "phpunit/phpunit": ">=5.0.0 <8.5.27" }, "suggest": { "ext-bcmath": "Need to support JSON deserialization" @@ -225,9 +225,9 @@ "proto" ], "support": { - "source": "https://github.com/protocolbuffers/protobuf-php/tree/v4.33.6" + "source": "https://github.com/protocolbuffers/protobuf-php/tree/v4.33.5" }, - "time": "2026-03-18T17:32:05+00:00" + "time": "2026-01-29T20:49:00+00:00" }, { "name": "halaxa/json-machine", @@ -514,16 +514,16 @@ }, { "name": "open-telemetry/api", - "version": "1.9.0", + "version": "1.8.0", "source": { "type": "git", "url": "https://github.com/opentelemetry-php/api.git", - "reference": "6f8d237ce2c304ca85f31970f788e7f074d147be" + "reference": "df5197c6fd0ddd8e9883b87de042d9341300e2ad" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/opentelemetry-php/api/zipball/6f8d237ce2c304ca85f31970f788e7f074d147be", - "reference": "6f8d237ce2c304ca85f31970f788e7f074d147be", + "url": "https://api.github.com/repos/opentelemetry-php/api/zipball/df5197c6fd0ddd8e9883b87de042d9341300e2ad", + "reference": "df5197c6fd0ddd8e9883b87de042d9341300e2ad", "shasum": "" }, "require": { @@ -580,20 +580,20 @@ "issues": "https://github.com/open-telemetry/opentelemetry-php/issues", "source": "https://github.com/open-telemetry/opentelemetry-php" }, - "time": "2026-02-25T13:24:05+00:00" + "time": "2026-01-21T04:14:03+00:00" }, { "name": "open-telemetry/context", - "version": "1.5.0", + "version": "1.4.0", "source": { "type": "git", "url": "https://github.com/opentelemetry-php/context.git", - "reference": "3c414b246e0dabb7d6145404e6a5e4536ca18d07" + "reference": "d4c4470b541ce72000d18c339cfee633e4c8e0cf" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/opentelemetry-php/context/zipball/3c414b246e0dabb7d6145404e6a5e4536ca18d07", - "reference": "3c414b246e0dabb7d6145404e6a5e4536ca18d07", + "url": "https://api.github.com/repos/opentelemetry-php/context/zipball/d4c4470b541ce72000d18c339cfee633e4c8e0cf", + "reference": "d4c4470b541ce72000d18c339cfee633e4c8e0cf", "shasum": "" }, "require": { @@ -635,11 +635,11 @@ ], "support": { "chat": "https://app.slack.com/client/T08PSQ7BQ/C01NFPCV44V", - "docs": "https://opentelemetry.io/docs/languages/php", + "docs": "https://opentelemetry.io/docs/php", "issues": "https://github.com/open-telemetry/opentelemetry-php/issues", "source": "https://github.com/open-telemetry/opentelemetry-php" }, - "time": "2025-10-19T06:44:33+00:00" + "time": "2025-09-19T00:05:49+00:00" }, { "name": "open-telemetry/exporter-otlp", @@ -707,16 +707,16 @@ }, { "name": "open-telemetry/gen-otlp-protobuf", - "version": "1.9.0", + "version": "1.8.0", "source": { "type": "git", "url": "https://github.com/opentelemetry-php/gen-otlp-protobuf.git", - "reference": "a229cf161d42001d64c8f21e8f678581fe1c66b9" + "reference": "673af5b06545b513466081884b47ef15a536edde" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/opentelemetry-php/gen-otlp-protobuf/zipball/a229cf161d42001d64c8f21e8f678581fe1c66b9", - "reference": "a229cf161d42001d64c8f21e8f678581fe1c66b9", + "url": "https://api.github.com/repos/opentelemetry-php/gen-otlp-protobuf/zipball/673af5b06545b513466081884b47ef15a536edde", + "reference": "673af5b06545b513466081884b47ef15a536edde", "shasum": "" }, "require": { @@ -762,30 +762,30 @@ ], "support": { "chat": "https://app.slack.com/client/T08PSQ7BQ/C01NFPCV44V", - "docs": "https://opentelemetry.io/docs/languages/php", + "docs": "https://opentelemetry.io/docs/php", "issues": "https://github.com/open-telemetry/opentelemetry-php/issues", "source": "https://github.com/open-telemetry/opentelemetry-php" }, - "time": "2025-10-19T06:44:33+00:00" + "time": "2025-09-17T23:10:12+00:00" }, { "name": "open-telemetry/sdk", - "version": "1.14.0", + "version": "1.13.0", "source": { "type": "git", "url": "https://github.com/opentelemetry-php/sdk.git", - "reference": "6e3d0ce93e76555dd5e2f1d19443ff45b990e410" + "reference": "c76f91203bf7ef98ab3f4e0a82ca21699af185e1" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/opentelemetry-php/sdk/zipball/6e3d0ce93e76555dd5e2f1d19443ff45b990e410", - "reference": "6e3d0ce93e76555dd5e2f1d19443ff45b990e410", + "url": "https://api.github.com/repos/opentelemetry-php/sdk/zipball/c76f91203bf7ef98ab3f4e0a82ca21699af185e1", + "reference": "c76f91203bf7ef98ab3f4e0a82ca21699af185e1", "shasum": "" }, "require": { "ext-json": "*", "nyholm/psr7-server": "^1.1", - "open-telemetry/api": "^1.8", + "open-telemetry/api": "^1.7", "open-telemetry/context": "^1.4", "open-telemetry/sem-conv": "^1.0", "php": "^8.1", @@ -863,7 +863,7 @@ "issues": "https://github.com/open-telemetry/opentelemetry-php/issues", "source": "https://github.com/open-telemetry/opentelemetry-php" }, - "time": "2026-03-21T11:50:01+00:00" + "time": "2026-01-28T11:38:11+00:00" }, { "name": "open-telemetry/sem-conv", @@ -1487,16 +1487,16 @@ }, { "name": "symfony/http-client", - "version": "v7.4.8", + "version": "v7.4.5", "source": { "type": "git", "url": "https://github.com/symfony/http-client.git", - "reference": "01933e626c3de76bea1e22641e205e78f6a34342" + "reference": "84bb634857a893cc146cceb467e31b3f02c5fe9f" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/symfony/http-client/zipball/01933e626c3de76bea1e22641e205e78f6a34342", - "reference": "01933e626c3de76bea1e22641e205e78f6a34342", + "url": "https://api.github.com/repos/symfony/http-client/zipball/84bb634857a893cc146cceb467e31b3f02c5fe9f", + "reference": "84bb634857a893cc146cceb467e31b3f02c5fe9f", "shasum": "" }, "require": { @@ -1564,7 +1564,7 @@ "http" ], "support": { - "source": "https://github.com/symfony/http-client/tree/v7.4.8" + "source": "https://github.com/symfony/http-client/tree/v7.4.5" }, "funding": [ { @@ -1584,7 +1584,7 @@ "type": "tidelift" } ], - "time": "2026-03-30T12:55:43+00:00" + "time": "2026-01-27T16:16:02+00:00" }, { "name": "symfony/http-client-contracts", @@ -1666,16 +1666,16 @@ }, { "name": "symfony/polyfill-mbstring", - "version": "v1.36.0", + "version": "v1.33.0", "source": { "type": "git", "url": "https://github.com/symfony/polyfill-mbstring.git", - "reference": "6a21eb99c6973357967f6ce3708cd55a6bec6315" + "reference": "6d857f4d76bd4b343eac26d6b539585d2bc56493" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/symfony/polyfill-mbstring/zipball/6a21eb99c6973357967f6ce3708cd55a6bec6315", - "reference": "6a21eb99c6973357967f6ce3708cd55a6bec6315", + "url": "https://api.github.com/repos/symfony/polyfill-mbstring/zipball/6d857f4d76bd4b343eac26d6b539585d2bc56493", + "reference": "6d857f4d76bd4b343eac26d6b539585d2bc56493", "shasum": "" }, "require": { @@ -1727,7 +1727,7 @@ "shim" ], "support": { - "source": "https://github.com/symfony/polyfill-mbstring/tree/v1.36.0" + "source": "https://github.com/symfony/polyfill-mbstring/tree/v1.33.0" }, "funding": [ { @@ -1747,20 +1747,20 @@ "type": "tidelift" } ], - "time": "2026-04-10T17:25:58+00:00" + "time": "2024-12-23T08:48:59+00:00" }, { "name": "symfony/polyfill-php82", - "version": "v1.36.0", + "version": "v1.33.0", "source": { "type": "git", "url": "https://github.com/symfony/polyfill-php82.git", - "reference": "34808efe3e68f69685796f7c253a2f1d8ea9df59" + "reference": "5d2ed36f7734637dacc025f179698031951b1692" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/symfony/polyfill-php82/zipball/34808efe3e68f69685796f7c253a2f1d8ea9df59", - "reference": "34808efe3e68f69685796f7c253a2f1d8ea9df59", + "url": "https://api.github.com/repos/symfony/polyfill-php82/zipball/5d2ed36f7734637dacc025f179698031951b1692", + "reference": "5d2ed36f7734637dacc025f179698031951b1692", "shasum": "" }, "require": { @@ -1807,7 +1807,7 @@ "shim" ], "support": { - "source": "https://github.com/symfony/polyfill-php82/tree/v1.36.0" + "source": "https://github.com/symfony/polyfill-php82/tree/v1.33.0" }, "funding": [ { @@ -1827,20 +1827,20 @@ "type": "tidelift" } ], - "time": "2026-04-10T16:19:22+00:00" + "time": "2024-09-09T11:45:10+00:00" }, { "name": "symfony/polyfill-php83", - "version": "v1.36.0", + "version": "v1.33.0", "source": { "type": "git", "url": "https://github.com/symfony/polyfill-php83.git", - "reference": "3600c2cb22399e25bb226e4a135ce91eeb2a6149" + "reference": "17f6f9a6b1735c0f163024d959f700cfbc5155e5" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/symfony/polyfill-php83/zipball/3600c2cb22399e25bb226e4a135ce91eeb2a6149", - "reference": "3600c2cb22399e25bb226e4a135ce91eeb2a6149", + "url": "https://api.github.com/repos/symfony/polyfill-php83/zipball/17f6f9a6b1735c0f163024d959f700cfbc5155e5", + "reference": "17f6f9a6b1735c0f163024d959f700cfbc5155e5", "shasum": "" }, "require": { @@ -1887,7 +1887,7 @@ "shim" ], "support": { - "source": "https://github.com/symfony/polyfill-php83/tree/v1.36.0" + "source": "https://github.com/symfony/polyfill-php83/tree/v1.33.0" }, "funding": [ { @@ -1907,20 +1907,20 @@ "type": "tidelift" } ], - "time": "2026-04-10T17:25:58+00:00" + "time": "2025-07-08T02:45:35+00:00" }, { "name": "symfony/polyfill-php85", - "version": "v1.36.0", + "version": "v1.33.0", "source": { "type": "git", "url": "https://github.com/symfony/polyfill-php85.git", - "reference": "2c408a6bb0313e6001a83628dc5506100474254e" + "reference": "d4e5fcd4ab3d998ab16c0db48e6cbb9a01993f91" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/symfony/polyfill-php85/zipball/2c408a6bb0313e6001a83628dc5506100474254e", - "reference": "2c408a6bb0313e6001a83628dc5506100474254e", + "url": "https://api.github.com/repos/symfony/polyfill-php85/zipball/d4e5fcd4ab3d998ab16c0db48e6cbb9a01993f91", + "reference": "d4e5fcd4ab3d998ab16c0db48e6cbb9a01993f91", "shasum": "" }, "require": { @@ -1967,7 +1967,7 @@ "shim" ], "support": { - "source": "https://github.com/symfony/polyfill-php85/tree/v1.36.0" + "source": "https://github.com/symfony/polyfill-php85/tree/v1.33.0" }, "funding": [ { @@ -1987,7 +1987,7 @@ "type": "tidelift" } ], - "time": "2026-04-10T16:50:15+00:00" + "time": "2025-06-23T16:12:55+00:00" }, { "name": "symfony/service-contracts", @@ -2130,16 +2130,16 @@ }, { "name": "utopia-php/cache", - "version": "1.0.1", + "version": "1.0.0", "source": { "type": "git", "url": "https://github.com/utopia-php/cache.git", - "reference": "05ceba981436a4022553f7aaa2a05fa049d0f71c" + "reference": "7068870c086a6aea16173563a26b93ef3e408439" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/cache/zipball/05ceba981436a4022553f7aaa2a05fa049d0f71c", - "reference": "05ceba981436a4022553f7aaa2a05fa049d0f71c", + "url": "https://api.github.com/repos/utopia-php/cache/zipball/7068870c086a6aea16173563a26b93ef3e408439", + "reference": "7068870c086a6aea16173563a26b93ef3e408439", "shasum": "" }, "require": { @@ -2176,9 +2176,9 @@ ], "support": { "issues": "https://github.com/utopia-php/cache/issues", - "source": "https://github.com/utopia-php/cache/tree/1.0.1" + "source": "https://github.com/utopia-php/cache/tree/1.0.0" }, - "time": "2026-03-12T03:39:09+00:00" + "time": "2026-01-28T10:55:44+00:00" }, { "name": "utopia-php/console", @@ -2336,16 +2336,16 @@ }, { "name": "utopia-php/mongo", - "version": "1.0.2", + "version": "1.0.0", "source": { "type": "git", "url": "https://github.com/utopia-php/mongo.git", - "reference": "677a21c53f7a1316c528b4b45b3fce886cee7223" + "reference": "45bedf36c2c946ec7a0a3e59b9f12f772de0b01d" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/mongo/zipball/677a21c53f7a1316c528b4b45b3fce886cee7223", - "reference": "677a21c53f7a1316c528b4b45b3fce886cee7223", + "url": "https://api.github.com/repos/utopia-php/mongo/zipball/45bedf36c2c946ec7a0a3e59b9f12f772de0b01d", + "reference": "45bedf36c2c946ec7a0a3e59b9f12f772de0b01d", "shasum": "" }, "require": { @@ -2391,22 +2391,22 @@ ], "support": { "issues": "https://github.com/utopia-php/mongo/issues", - "source": "https://github.com/utopia-php/mongo/tree/1.0.2" + "source": "https://github.com/utopia-php/mongo/tree/1.0.0" }, - "time": "2026-03-18T02:45:50+00:00" + "time": "2026-02-12T05:54:06+00:00" }, { "name": "utopia-php/pools", - "version": "1.0.3", + "version": "1.0.2", "source": { "type": "git", "url": "https://github.com/utopia-php/pools.git", - "reference": "74de7c5457a2c447f27e7ec4d72e8412a7d68c10" + "reference": "b7d8dd00306cdd8bf3ff6f1dc90caeaf27dabeb1" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/pools/zipball/74de7c5457a2c447f27e7ec4d72e8412a7d68c10", - "reference": "74de7c5457a2c447f27e7ec4d72e8412a7d68c10", + "url": "https://api.github.com/repos/utopia-php/pools/zipball/b7d8dd00306cdd8bf3ff6f1dc90caeaf27dabeb1", + "reference": "b7d8dd00306cdd8bf3ff6f1dc90caeaf27dabeb1", "shasum": "" }, "require": { @@ -2444,9 +2444,9 @@ ], "support": { "issues": "https://github.com/utopia-php/pools/issues", - "source": "https://github.com/utopia-php/pools/tree/1.0.3" + "source": "https://github.com/utopia-php/pools/tree/1.0.2" }, - "time": "2026-02-26T08:42:40+00:00" + "time": "2026-01-28T13:12:36+00:00" }, { "name": "utopia-php/storage", @@ -4649,16 +4649,16 @@ }, { "name": "symfony/polyfill-ctype", - "version": "v1.36.0", + "version": "v1.33.0", "source": { "type": "git", "url": "https://github.com/symfony/polyfill-ctype.git", - "reference": "141046a8f9477948ff284fa65be2095baafb94f2" + "reference": "a3cc8b044a6ea513310cbd48ef7333b384945638" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/symfony/polyfill-ctype/zipball/141046a8f9477948ff284fa65be2095baafb94f2", - "reference": "141046a8f9477948ff284fa65be2095baafb94f2", + "url": "https://api.github.com/repos/symfony/polyfill-ctype/zipball/a3cc8b044a6ea513310cbd48ef7333b384945638", + "reference": "a3cc8b044a6ea513310cbd48ef7333b384945638", "shasum": "" }, "require": { @@ -4708,7 +4708,7 @@ "portable" ], "support": { - "source": "https://github.com/symfony/polyfill-ctype/tree/v1.36.0" + "source": "https://github.com/symfony/polyfill-ctype/tree/v1.33.0" }, "funding": [ { @@ -4728,20 +4728,20 @@ "type": "tidelift" } ], - "time": "2026-04-10T16:19:22+00:00" + "time": "2024-09-09T11:45:10+00:00" }, { "name": "symfony/polyfill-php80", - "version": "v1.36.0", + "version": "v1.33.0", "source": { "type": "git", "url": "https://github.com/symfony/polyfill-php80.git", - "reference": "dfb55726c3a76ea3b6459fcfda1ec2d80a682411" + "reference": "0cc9dd0f17f61d8131e7df6b84bd344899fe2608" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/symfony/polyfill-php80/zipball/dfb55726c3a76ea3b6459fcfda1ec2d80a682411", - "reference": "dfb55726c3a76ea3b6459fcfda1ec2d80a682411", + "url": "https://api.github.com/repos/symfony/polyfill-php80/zipball/0cc9dd0f17f61d8131e7df6b84bd344899fe2608", + "reference": "0cc9dd0f17f61d8131e7df6b84bd344899fe2608", "shasum": "" }, "require": { @@ -4792,7 +4792,7 @@ "shim" ], "support": { - "source": "https://github.com/symfony/polyfill-php80/tree/v1.36.0" + "source": "https://github.com/symfony/polyfill-php80/tree/v1.33.0" }, "funding": [ { @@ -4812,7 +4812,7 @@ "type": "tidelift" } ], - "time": "2026-04-10T16:19:22+00:00" + "time": "2025-01-02T08:10:11+00:00" }, { "name": "theseer/tokenizer", @@ -4950,9 +4950,9 @@ } ], "aliases": [], - "minimum-stability": "dev", + "minimum-stability": "stable", "stability-flags": {}, - "prefer-stable": true, + "prefer-stable": false, "prefer-lowest": false, "platform": { "php": ">=8.1", From f3ae6a2daa7320725ce5b087510309707aee37e2 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Mon, 20 Apr 2026 11:11:24 +0100 Subject: [PATCH 15/91] Refactor onDuplicate from string constants to PHP 8.1 backed enum --- src/Migration/Destinations/Appwrite.php | 30 +++++-------------------- src/Migration/OnDuplicate.php | 21 +++++++++++++++++ 2 files changed, 27 insertions(+), 24 deletions(-) create mode 100644 src/Migration/OnDuplicate.php diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index bc5e01d46b..88de342bab 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -36,6 +36,7 @@ use Utopia\Database\Validator\Structure; use Utopia\Database\Validator\UID; use Utopia\Migration\Destination; use Utopia\Migration\Exception; +use Utopia\Migration\OnDuplicate; use Utopia\Migration\Resource; use Utopia\Migration\Resources\Auth\Hash; use Utopia\Migration\Resources\Auth\Membership; @@ -63,19 +64,6 @@ use Utopia\Migration\Transfer; class Appwrite extends Destination { - public const ON_DUPLICATE_FAIL = 'fail'; - public const ON_DUPLICATE_SKIP = 'skip'; - public const ON_DUPLICATE_UPSERT = 'upsert'; - - /** - * @var array - */ - public const ON_DUPLICATES = [ - self::ON_DUPLICATE_FAIL, - self::ON_DUPLICATE_SKIP, - self::ON_DUPLICATE_UPSERT, - ]; - protected Client $client; protected string $project; @@ -105,7 +93,7 @@ class Appwrite extends Destination * @param UtopiaDatabase $dbForProject * @param callable(UtopiaDocument $database):UtopiaDatabase $getDatabasesDB * @param array> $collectionStructure - * @param string $onDuplicate Behavior when a row with an existing $id is encountered. One of ON_DUPLICATE_FAIL (abort), ON_DUPLICATE_SKIP (silently ignore), ON_DUPLICATE_UPSERT (replace existing). + * @param OnDuplicate $onDuplicate Behavior when a row with an existing $id is encountered. */ public function __construct( string $project, @@ -114,14 +102,8 @@ class Appwrite extends Destination protected UtopiaDatabase $dbForProject, callable $getDatabasesDB, protected array $collectionStructure, - protected string $onDuplicate = self::ON_DUPLICATE_FAIL, + protected OnDuplicate $onDuplicate = OnDuplicate::Fail, ) { - if (!\in_array($onDuplicate, self::ON_DUPLICATES, true)) { - throw new \InvalidArgumentException( - "Invalid onDuplicate value '{$onDuplicate}'. Must be one of: " . \implode(', ', self::ON_DUPLICATES) - ); - } - $this->project = $project; $this->endpoint = $endpoint; $this->key = $key; @@ -1091,15 +1073,15 @@ class Appwrite extends Destination $collectionId = 'database_' . $databaseInternalId . '_collection_' . $tableInternalId; match ($this->onDuplicate) { - self::ON_DUPLICATE_UPSERT => $dbForDatabases->skipRelationshipsExistCheck( + OnDuplicate::Upsert => $dbForDatabases->skipRelationshipsExistCheck( fn () => $dbForDatabases->upsertDocuments($collectionId, $this->rowBuffer) ), - self::ON_DUPLICATE_SKIP => $dbForDatabases->skipDuplicates( + OnDuplicate::Skip => $dbForDatabases->skipDuplicates( fn () => $dbForDatabases->skipRelationshipsExistCheck( fn () => $dbForDatabases->createDocuments($collectionId, $this->rowBuffer) ) ), - self::ON_DUPLICATE_FAIL => $dbForDatabases->skipRelationshipsExistCheck( + OnDuplicate::Fail => $dbForDatabases->skipRelationshipsExistCheck( fn () => $dbForDatabases->createDocuments($collectionId, $this->rowBuffer) ), }; diff --git a/src/Migration/OnDuplicate.php b/src/Migration/OnDuplicate.php new file mode 100644 index 0000000000..1fb3e7bdc8 --- /dev/null +++ b/src/Migration/OnDuplicate.php @@ -0,0 +1,21 @@ + + */ + public static function values(): array + { + return \array_map(fn (self $case) => $case->value, self::cases()); + } +} From 74f166b680c5c654264c05207bddf94894babc9e Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Mon, 20 Apr 2026 11:20:47 +0100 Subject: [PATCH 16/91] Move OnDuplicate enum to Destinations namespace (co-locate with consumer) --- src/Migration/Destinations/Appwrite.php | 1 - src/Migration/{ => Destinations}/OnDuplicate.php | 2 +- 2 files changed, 1 insertion(+), 2 deletions(-) rename src/Migration/{ => Destinations}/OnDuplicate.php (89%) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index 88de342bab..893bf9879d 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -36,7 +36,6 @@ use Utopia\Database\Validator\Structure; use Utopia\Database\Validator\UID; use Utopia\Migration\Destination; use Utopia\Migration\Exception; -use Utopia\Migration\OnDuplicate; use Utopia\Migration\Resource; use Utopia\Migration\Resources\Auth\Hash; use Utopia\Migration\Resources\Auth\Membership; diff --git a/src/Migration/OnDuplicate.php b/src/Migration/Destinations/OnDuplicate.php similarity index 89% rename from src/Migration/OnDuplicate.php rename to src/Migration/Destinations/OnDuplicate.php index 1fb3e7bdc8..31a0e49f71 100644 --- a/src/Migration/OnDuplicate.php +++ b/src/Migration/Destinations/OnDuplicate.php @@ -1,6 +1,6 @@ Date: Tue, 21 Apr 2026 17:12:46 +0530 Subject: [PATCH 17/91] updated to TablesDB --- src/Migration/Sources/Appwrite.php | 4 +-- src/Migration/Sources/Appwrite/Reader/API.php | 33 +++++++------------ 2 files changed, 14 insertions(+), 23 deletions(-) diff --git a/src/Migration/Sources/Appwrite.php b/src/Migration/Sources/Appwrite.php index e5e57fa90d..355e40c1e7 100644 --- a/src/Migration/Sources/Appwrite.php +++ b/src/Migration/Sources/Appwrite.php @@ -5,11 +5,11 @@ namespace Utopia\Migration\Sources; use Appwrite\AppwriteException; use Appwrite\Client; use Appwrite\Query; -use Appwrite\Services\Databases; use Appwrite\Services\Functions; use Appwrite\Services\Messaging; use Appwrite\Services\Sites; use Appwrite\Services\Storage; +use Appwrite\Services\TablesDB; use Appwrite\Services\Teams; use Appwrite\Services\Users; use Utopia\Database\Database as UtopiaDatabase; @@ -127,7 +127,7 @@ class Appwrite extends Source switch ($this->source) { case static::SOURCE_API: - $this->reader = new APIReader(new Databases($this->client)); + $this->reader = new APIReader(new TablesDB($this->client)); break; case static::SOURCE_DATABASE: diff --git a/src/Migration/Sources/Appwrite/Reader/API.php b/src/Migration/Sources/Appwrite/Reader/API.php index b42835bd70..47a52f9dc6 100644 --- a/src/Migration/Sources/Appwrite/Reader/API.php +++ b/src/Migration/Sources/Appwrite/Reader/API.php @@ -4,8 +4,7 @@ namespace Utopia\Migration\Sources\Appwrite\Reader; use Appwrite\AppwriteException; use Appwrite\Query; -use Appwrite\Services\Databases; -/* use Appwrite\Services\Tables; */ +use Appwrite\Services\TablesDB; use Utopia\Migration\Resource; use Utopia\Migration\Resources\Database\Database; use Utopia\Migration\Resources\Database\Table; @@ -17,8 +16,7 @@ use Utopia\Migration\Sources\Appwrite\Reader; class API implements Reader { public function __construct( - private readonly Databases $database, - /* private readonly Tables $table, */ + private readonly TablesDB $database, ) { } @@ -73,13 +71,12 @@ class API implements Reader $lastTable = null; while (true) { - /* $currentTables = $this->tables->list(...); */ - $currentTables = $this->database->listCollections( + $currentTables = $this->database->listTables( $databaseId, $lastTable ? [Query::cursorAfter($lastTable)] : [Query::limit($pageLimit)] - )['collections']; /* ['tables'] */ + )['tables']; $tables = \array_merge($tables, $currentTables); $lastTable = $tables[count($tables) - 1]['$id'] ?? null; @@ -108,8 +105,7 @@ class API implements Reader } if (Resource::isSupported(Resource::TYPE_ROW, $resources)) { - /* $rowsResponse = $this->tables->listRows(...) */ - $rowsResponse = $this->database->listDocuments( + $rowsResponse = $this->database->listRows( $databaseId, $tableId, [Query::limit(1)] @@ -137,11 +133,10 @@ class API implements Reader */ public function listTables(Database $resource, array $queries = []): array { - /* $this->tables->list(...)['tables'] */ - return $this->database->listCollections( + return $this->database->listTables( $resource->getId(), $queries - )['collections']; + )['tables']; } /** @@ -152,12 +147,11 @@ class API implements Reader */ public function listColumns(Table $resource, array $queries = []): array { - /* $this->tables->listColumns(...)['columns'] */ - return $this->database->listAttributes( + return $this->database->listColumns( $resource->getDatabase()->getId(), $resource->getId(), $queries - )['attributes']; + )['columns']; } /** @@ -168,7 +162,6 @@ class API implements Reader */ public function listIndexes(Table $resource, array $queries = []): array { - /* $this->tables->listIndexes(...)['indexes'] */ return $this->database->listIndexes( $resource->getDatabase()->getId(), $resource->getId(), @@ -185,12 +178,11 @@ class API implements Reader */ public function listRows(Table $resource, array $queries = []): array { - /* $this->tables->listRows(...)['rows'] */ - return $this->database->listDocuments( + return $this->database->listRows( $resource->getDatabase()->getId(), $resource->getId(), $queries - )['documents']; + )['rows']; } /** @@ -202,8 +194,7 @@ class API implements Reader */ public function getRow(Table $resource, string $rowId, array $queries = []): array { - /* $this->tables->getRow(...) */ - return $this->database->getDocument( + return $this->database->getRow( $resource->getDatabase()->getId(), $resource->getId(), $rowId, From f3f8baca833475563d2437ad9df1f5cbd3f7fab2 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Tue, 21 Apr 2026 17:32:13 +0530 Subject: [PATCH 18/91] updated --- src/Migration/Resources/Database/Table.php | 2 +- src/Migration/Sources/Appwrite.php | 4 +++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/src/Migration/Resources/Database/Table.php b/src/Migration/Resources/Database/Table.php index 889d90fe1f..0ba04a5cda 100644 --- a/src/Migration/Resources/Database/Table.php +++ b/src/Migration/Resources/Database/Table.php @@ -53,7 +53,7 @@ class Table extends Resource Database::fromArray($array['database']), name: $array['name'], id: $array['id'], - rowSecurity: $array['rowSecurity'] ?? $array['documentSecurity'], + rowSecurity: (bool) ($array['rowSecurity'] ?? $array['documentSecurity'] ?? false), permissions: $array['permissions'] ?? [], createdAt: $array['createdAt'] ?? '', updatedAt: $array['updatedAt'] ?? '', diff --git a/src/Migration/Sources/Appwrite.php b/src/Migration/Sources/Appwrite.php index 355e40c1e7..6691c6a8ba 100644 --- a/src/Migration/Sources/Appwrite.php +++ b/src/Migration/Sources/Appwrite.php @@ -928,10 +928,12 @@ class Appwrite extends Source $response = $this->reader->listTables($database, $queries); foreach ($response as $table) { + $rowSecurity = $table['rowSecurity'] ?? $table['documentSecurity'] ?? false; $newTable = self::getEntity($databaseName, [ 'id' => $table['$id'], 'name' => $table['name'], - 'documentSecurity' => $table['documentSecurity'], + 'rowSecurity' => $rowSecurity, + 'documentSecurity' => $rowSecurity, 'permissions' => $table['$permissions'], 'createdAt' => $table['$createdAt'], 'updatedAt' => $table['$updatedAt'], From d8ad759751d5d089c4dc9378dff12a00eba1bfd5 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Tue, 21 Apr 2026 17:57:41 +0530 Subject: [PATCH 19/91] updated --- src/Migration/Sources/Appwrite.php | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/src/Migration/Sources/Appwrite.php b/src/Migration/Sources/Appwrite.php index 6691c6a8ba..e5eedaab81 100644 --- a/src/Migration/Sources/Appwrite.php +++ b/src/Migration/Sources/Appwrite.php @@ -1153,9 +1153,16 @@ class Appwrite extends Source $id = $row['$id']; $permissions = $row['$permissions']; + // TablesDB(API reader) returns `$tableId`, while downstream import cleanup still + // normalizes/removes legacy `$collectionId`. Mirror the value to keep + // compatibility across both shapes. + if (isset($row['$tableId']) && !isset($row['$collectionId'])) { + $row['$collectionId'] = $row['$tableId']; + } + unset($row['$id']); unset($row['$permissions']); - unset($row['$collectionId']); + unset($row['$tableId']); unset($row['$databaseId']); unset($row['$sequence']); unset($row['$collection']); From 325ea937951780192458db8d5a168140f2f4e4b0 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Tue, 21 Apr 2026 18:06:54 +0530 Subject: [PATCH 20/91] updated --- src/Migration/Sources/Appwrite.php | 7 ------- 1 file changed, 7 deletions(-) diff --git a/src/Migration/Sources/Appwrite.php b/src/Migration/Sources/Appwrite.php index e5eedaab81..e21f9b23a2 100644 --- a/src/Migration/Sources/Appwrite.php +++ b/src/Migration/Sources/Appwrite.php @@ -1153,13 +1153,6 @@ class Appwrite extends Source $id = $row['$id']; $permissions = $row['$permissions']; - // TablesDB(API reader) returns `$tableId`, while downstream import cleanup still - // normalizes/removes legacy `$collectionId`. Mirror the value to keep - // compatibility across both shapes. - if (isset($row['$tableId']) && !isset($row['$collectionId'])) { - $row['$collectionId'] = $row['$tableId']; - } - unset($row['$id']); unset($row['$permissions']); unset($row['$tableId']); From edc90215ae5ab669562d735a9bfed39abf9bf80b Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Tue, 21 Apr 2026 18:20:37 +0530 Subject: [PATCH 21/91] updated --- src/Migration/Sources/Appwrite.php | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/Migration/Sources/Appwrite.php b/src/Migration/Sources/Appwrite.php index e21f9b23a2..daf9b6a3f3 100644 --- a/src/Migration/Sources/Appwrite.php +++ b/src/Migration/Sources/Appwrite.php @@ -1155,10 +1155,11 @@ class Appwrite extends Source unset($row['$id']); unset($row['$permissions']); - unset($row['$tableId']); unset($row['$databaseId']); unset($row['$sequence']); unset($row['$collection']); + unset($row['$tableId']); + unset($row['$table']); $row = self::getRecord($table->getDatabase()->getType(), [ 'id' => $id, From abf95d500739878d5160962e2e59167aebec42eb Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Wed, 22 Apr 2026 11:51:12 +0100 Subject: [PATCH 22/91] Schema Skip/Upsert via pre-check + updatedAt gate on attribute/index MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Re-migration needs the destination to tolerate existing schema resources. The database library stays minimal — migration owns the reconciliation decision since it has both source and destination metadata in hand. Per-resource behavior: - Database: pre-check `databases` metadata. If exists, hydrate sequence from the existing document and return. Both Skip and Upsert tolerate unconditionally — databases contain the entire tree of collections + rows, dropping would destroy everything. - Table: pre-check `database_{sequence}` metadata. Same pattern — tolerate unconditionally, hydrate sequence, never drop. Attribute and index reconciliation happens per-resource at the lower layer. - Attribute: pre-check `attributes` metadata by composite id ({databaseSeq}_{tableSeq}_{key}). Skip tolerates. Upsert compares source's updatedAt vs destination's — if source is strictly newer the column is dropped (via `dbForDatabases->deleteAttribute`) and recreated so the spec matches source. Column data is wiped on drop; rows will be repopulated by the row-level Upsert path that follows. - Index: same pattern against `indexes` metadata. Drop is cheap because indexes carry no user data — only rebuild time. Approach is pre-check rather than try/catch for control flow: migration is sequential single-writer, so the race condition justification for try/catch doesn't apply, and pre-check reads top-to-bottom with no exception-as-control-flow. Row-level dispatch (unchanged, already committed): OnDuplicate::Upsert → $dbForDatabases->upsertDocuments(...) OnDuplicate::Skip → $dbForDatabases->skipDuplicates(fn () => createDocuments(...)) OnDuplicate::Fail → plain createDocuments Both row-level primitives are existing library APIs — no database-library changes are required for this feature. Helpers: shouldTolerateSchemaDuplicate() // onDuplicate !== Fail sourceSpecIsNewer($src, $dst) // strtotime compare, false on empty --- src/Migration/Destinations/Appwrite.php | 117 +++++++++++++++++++++++- 1 file changed, 116 insertions(+), 1 deletion(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index 893bf9879d..c18eb63c9b 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -422,6 +422,20 @@ class Appwrite extends Destination $createdAt = $this->normalizeDateTime($resource->getCreatedAt()); $updatedAt = $this->normalizeDateTime($resource->getUpdatedAt(), $createdAt); + // Skip/Upsert: pre-check an existing database. Databases contain the + // entire tree of collections + rows, so they are never destructively + // reconciled — both modes simply hydrate the sequence from the + // existing metadata document and return. Downstream resources + // (tables/columns/rows) locate the existing underlying schema via the + // hydrated sequence. + if ($this->shouldTolerateSchemaDuplicate()) { + $existing = $this->dbForProject->getDocument('databases', $resource->getId()); + if (!$existing->isEmpty()) { + $resource->setSequence($existing->getSequence()); + return true; + } + } + $database = $this->dbForProject->createDocument('databases', new UtopiaDocument([ '$id' => $resource->getId(), 'name' => $resource->getDatabaseName(), @@ -456,6 +470,32 @@ class Appwrite extends Destination return true; } + /** + * Skip/Upsert both tolerate an existing schema resource on re-migration. + * Upsert differs from Skip only for leaf resources (attributes, indexes) + * where the updatedAt comparison gates a drop+recreate — containers + * (databases, tables) are always tolerate-only because their data is + * preserved. + */ + private function shouldTolerateSchemaDuplicate(): bool + { + return $this->onDuplicate !== OnDuplicate::Fail; + } + + /** + * Upsert reconciliation: source's updatedAt strictly later than + * destination's signals the spec changed since last sync — leaf resource + * should be dropped + recreated. Equal or earlier: dest is up-to-date, + * tolerate. + */ + private function sourceSpecIsNewer(string $sourceUpdatedAt, string $destUpdatedAt): bool + { + if ($sourceUpdatedAt === '' || $destUpdatedAt === '') { + return false; + } + return \strtotime($sourceUpdatedAt) > \strtotime($destUpdatedAt); + } + /** * @throws AuthorizationException * @throws DatabaseException @@ -503,6 +543,21 @@ class Appwrite extends Destination $dbForDatabases->create(); } + // Skip/Upsert: pre-check an existing table. Like databases, tables + // contain user data (rows), so both modes simply hydrate the sequence + // from the existing metadata document. Attribute/index reconciliation + // happens per-resource at a lower layer. + if ($this->shouldTolerateSchemaDuplicate()) { + $existing = $this->dbForProject->getDocument( + 'database_' . $database->getSequence(), + $resource->getId() + ); + if (!$existing->isEmpty()) { + $resource->setSequence($existing->getSequence()); + return true; + } + } + $table = $this->dbForProject->createDocument('database_' . $database->getSequence(), new UtopiaDocument([ '$id' => $resource->getId(), 'databaseInternalId' => $database->getSequence(), @@ -642,9 +697,38 @@ class Appwrite extends Destination $createdAt = $this->normalizeDateTime($resource->getCreatedAt()); $updatedAt = $this->normalizeDateTime($resource->getUpdatedAt(), $createdAt); $dbForDatabases = ($this->getDatabasesDB)($database); + + // Skip/Upsert: pre-check against `attributes` metadata. Skip tolerates + // unconditionally; Upsert tolerates unless source's updatedAt is + // strictly newer — in which case the column is dropped + recreated so + // the spec matches source. Column data is wiped on drop; rows are + // repopulated via row-level Upsert below. + $attributeMetaId = $database->getSequence() . '_' . $table->getSequence() . '_' . $resource->getKey(); + if ($this->shouldTolerateSchemaDuplicate()) { + $existingAttr = $this->dbForProject->getDocument('attributes', $attributeMetaId); + if (!$existingAttr->isEmpty()) { + if ($this->onDuplicate === OnDuplicate::Skip + || !$this->sourceSpecIsNewer($updatedAt, $existingAttr->getUpdatedAt()) + ) { + // Destination already up-to-date; hydrate caches and skip. + $this->dbForProject->purgeCachedDocument('database_' . $database->getSequence(), $table->getId()); + $dbForDatabases->purgeCachedCollection('database_' . $database->getSequence() . '_collection_' . $table->getSequence()); + return true; + } + // Source spec newer: drop then recreate under the create flow. + $dbForDatabases->deleteAttribute( + 'database_' . $database->getSequence() . '_collection_' . $table->getSequence(), + $resource->getKey() + ); + $this->dbForProject->deleteDocument('attributes', $attributeMetaId); + $this->dbForProject->purgeCachedDocument('database_' . $database->getSequence(), $table->getId()); + $dbForDatabases->purgeCachedCollection('database_' . $database->getSequence() . '_collection_' . $table->getSequence()); + } + } + try { $column = new UtopiaDocument([ - '$id' => ID::custom($database->getSequence() . '_' . $table->getSequence() . '_' . $resource->getKey()), + '$id' => ID::custom($attributeMetaId), 'key' => $resource->getKey(), 'databaseInternalId' => $database->getSequence(), 'databaseId' => $database->getId(), @@ -920,6 +1004,37 @@ class Appwrite extends Destination ); } + // Skip/Upsert: pre-check against `indexes` metadata. Same rule as + // attributes — Skip tolerates unconditionally; Upsert tolerates unless + // source's updatedAt is strictly newer, in which case the index is + // dropped + recreated. Index drops are non-destructive (no row data + // lives in indexes) so rebuild cost is just the index build time. + $indexMetaId = $database->getSequence() . '_' . $table->getSequence() . '_' . $resource->getKey(); + if ($this->shouldTolerateSchemaDuplicate()) { + $existingIdx = $this->dbForProject->getDocument('indexes', $indexMetaId); + if (!$existingIdx->isEmpty()) { + if ($this->onDuplicate === OnDuplicate::Skip + || !$this->sourceSpecIsNewer($updatedAt, $existingIdx->getUpdatedAt()) + ) { + $this->dbForProject->purgeCachedDocument( + 'database_' . $database->getSequence(), + $table->getId() + ); + return true; + } + // Source spec newer: drop then recreate. + $dbForDatabases->deleteIndex( + 'database_' . $database->getSequence() . '_collection_' . $table->getSequence(), + $resource->getKey() + ); + $this->dbForProject->deleteDocument('indexes', $indexMetaId); + $this->dbForProject->purgeCachedDocument( + 'database_' . $database->getSequence(), + $table->getId() + ); + } + } + $index = $this->dbForProject->createDocument('indexes', $index); try { From fc6e5f7d0210c46aad168a863279bc8a8dd65011 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Wed, 22 Apr 2026 13:26:22 +0100 Subject: [PATCH 23/91] sourceSpecIsNewer: explicit false check on strtotime Guard against malformed datetime strings (e.g. "0000-00-00 00:00:00") that PHP's strtotime() returns false for. Without the explicit check, false gets loose-compared as 0 and the helper silently returns false, meaning a corrupted source updatedAt would always tolerate the existing destination entry and never trigger drop+recreate. Appwrite itself always emits parseable RFC 3339 timestamps, so this is mainly defensive for non-Appwrite sources (Supabase, NHost, CSV). Flagged by greptile P2. --- src/Migration/Destinations/Appwrite.php | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index c18eb63c9b..8ac8ca61a0 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -493,7 +493,16 @@ class Appwrite extends Destination if ($sourceUpdatedAt === '' || $destUpdatedAt === '') { return false; } - return \strtotime($sourceUpdatedAt) > \strtotime($destUpdatedAt); + $src = \strtotime($sourceUpdatedAt); + $dst = \strtotime($destUpdatedAt); + if ($src === false || $dst === false) { + // Conservative: any unparseable timestamp → don't drop+recreate. + // Matters for non-Appwrite sources that may emit malformed dates + // (e.g. "0000-00-00 00:00:00"); Appwrite itself always emits + // parseable RFC 3339. + return false; + } + return $src > $dst; } /** From 4e8100ab83471f9d69b9b1eea2cec3d81aa7b2c1 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Wed, 22 Apr 2026 13:50:24 +0100 Subject: [PATCH 24/91] Upsert drop: clean up child-side metadata for two-way relationships MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit On a first-run migration createField writes TWO metadata documents for a two-way relationship attribute: parent-side at {dbSeq}_{tableSeq}_{key} (line 763) and child-side at {dbSeq}_{relatedTableSeq}_{twoWayKey} (line 819). Migration operates directly on the database via $dbForProject — it doesn't rely on Appwrite's attribute-event workers to derive the child side — so both documents are physically written by migration itself. The Upsert drop block was only removing the parent-side document + column. On the recreate pass that followed, line 819 re-wrote the child-side document and immediately hit DuplicateException because the stale child doc from the previous migration run was still sitting there. The inner catch rolled back the parent and the whole attribute aborted with "Attribute already exists" — breaking Upsert re-migration for every two-way relationship whose source spec had changed. Fix: in the Upsert drop branch, when the resource is a two-way relationship, also delete the child-side metadata document and the child-side physical column on the related table, then purge caches. Both deletes are wrapped in try/catch to tolerate the case where a prior interrupted run (or utopia-php/database's relationship handling) already cleaned one side — the goal is to guarantee a clean slate for the downstream recreate, not to require both sides to still exist. Flagged by greptile P1. Reproducing scenario: - OnDuplicate::Upsert - Destination already contains the attribute - Source's two-way relationship spec was modified between runs (source.updatedAt > dest.updatedAt) --- src/Migration/Destinations/Appwrite.php | 31 +++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index 8ac8ca61a0..f01c77ea22 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -732,6 +732,37 @@ class Appwrite extends Destination $this->dbForProject->deleteDocument('attributes', $attributeMetaId); $this->dbForProject->purgeCachedDocument('database_' . $database->getSequence(), $table->getId()); $dbForDatabases->purgeCachedCollection('database_' . $database->getSequence() . '_collection_' . $table->getSequence()); + + // Two-way relationships: the first-run createField wrote TWO + // metadata docs (parent at line 763, child at line 819). The + // drop above only removed the parent; without cleaning up the + // child, the recreate path hits DuplicateException at line 819 + // and the whole attribute re-migration fails. + $resourceOptions = $resource->getOptions(); + if ($type === UtopiaDatabase::VAR_RELATIONSHIP && !empty($resourceOptions['twoWay'])) { + // $relatedTable was populated at the top of createField + // inside the same VAR_RELATIONSHIP branch. + $childTwoWayKey = $resourceOptions['twoWayKey'] ?? ''; + if ($childTwoWayKey !== '') { + $childMetaId = $database->getSequence() . '_' . $relatedTable->getSequence() . '_' . $childTwoWayKey; + try { + $this->dbForProject->deleteDocument('attributes', $childMetaId); + } catch (\Throwable) { + // Child metadata already gone — interrupted prior run, nothing to do. + } + try { + $dbForDatabases->deleteAttribute( + 'database_' . $database->getSequence() . '_collection_' . $relatedTable->getSequence(), + $childTwoWayKey + ); + } catch (\Throwable) { + // Child column already gone — the parent's deleteAttribute may + // have cascaded via utopia-php/database's relationship handling. + } + $this->dbForProject->purgeCachedDocument('database_' . $database->getSequence(), $relatedTable->getId()); + $dbForDatabases->purgeCachedCollection('database_' . $database->getSequence() . '_collection_' . $relatedTable->getSequence()); + } + } } } From cfd6b987af2e25ddaa41f38a3a39e2535e1b0337 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Wed, 22 Apr 2026 13:56:01 +0100 Subject: [PATCH 25/91] Move tolerate/reconcile logic onto OnDuplicate enum MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit DestinationAppwrite's shouldTolerateSchemaDuplicate() and sourceSpecIsNewer() were private helpers that encoded mode-specific behavior. Moving them onto OnDuplicate itself puts the behavior on the type that owns it and makes the call sites self-documenting: $this->onDuplicate->toleratesSchemaDuplicate() $this->onDuplicate->shouldReconcileSchema($src, $dst) shouldReconcileSchema() also subsumes the explicit Skip check at the call sites — it returns false for Skip and Fail, so the compound "`Skip || !sourceSpecIsNewer(...)`" condition collapses to a single "`!shouldReconcileSchema(...)`". No behavior change. Lint + PHPStan L3 clean. --- src/Migration/Destinations/Appwrite.php | 54 ++++------------------ src/Migration/Destinations/OnDuplicate.php | 31 +++++++++++++ 2 files changed, 39 insertions(+), 46 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index f01c77ea22..d68b6c4345 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -428,7 +428,7 @@ class Appwrite extends Destination // existing metadata document and return. Downstream resources // (tables/columns/rows) locate the existing underlying schema via the // hydrated sequence. - if ($this->shouldTolerateSchemaDuplicate()) { + if ($this->onDuplicate->toleratesSchemaDuplicate()) { $existing = $this->dbForProject->getDocument('databases', $resource->getId()); if (!$existing->isEmpty()) { $resource->setSequence($existing->getSequence()); @@ -470,41 +470,6 @@ class Appwrite extends Destination return true; } - /** - * Skip/Upsert both tolerate an existing schema resource on re-migration. - * Upsert differs from Skip only for leaf resources (attributes, indexes) - * where the updatedAt comparison gates a drop+recreate — containers - * (databases, tables) are always tolerate-only because their data is - * preserved. - */ - private function shouldTolerateSchemaDuplicate(): bool - { - return $this->onDuplicate !== OnDuplicate::Fail; - } - - /** - * Upsert reconciliation: source's updatedAt strictly later than - * destination's signals the spec changed since last sync — leaf resource - * should be dropped + recreated. Equal or earlier: dest is up-to-date, - * tolerate. - */ - private function sourceSpecIsNewer(string $sourceUpdatedAt, string $destUpdatedAt): bool - { - if ($sourceUpdatedAt === '' || $destUpdatedAt === '') { - return false; - } - $src = \strtotime($sourceUpdatedAt); - $dst = \strtotime($destUpdatedAt); - if ($src === false || $dst === false) { - // Conservative: any unparseable timestamp → don't drop+recreate. - // Matters for non-Appwrite sources that may emit malformed dates - // (e.g. "0000-00-00 00:00:00"); Appwrite itself always emits - // parseable RFC 3339. - return false; - } - return $src > $dst; - } - /** * @throws AuthorizationException * @throws DatabaseException @@ -556,7 +521,7 @@ class Appwrite extends Destination // contain user data (rows), so both modes simply hydrate the sequence // from the existing metadata document. Attribute/index reconciliation // happens per-resource at a lower layer. - if ($this->shouldTolerateSchemaDuplicate()) { + if ($this->onDuplicate->toleratesSchemaDuplicate()) { $existing = $this->dbForProject->getDocument( 'database_' . $database->getSequence(), $resource->getId() @@ -713,13 +678,11 @@ class Appwrite extends Destination // the spec matches source. Column data is wiped on drop; rows are // repopulated via row-level Upsert below. $attributeMetaId = $database->getSequence() . '_' . $table->getSequence() . '_' . $resource->getKey(); - if ($this->shouldTolerateSchemaDuplicate()) { + if ($this->onDuplicate->toleratesSchemaDuplicate()) { $existingAttr = $this->dbForProject->getDocument('attributes', $attributeMetaId); if (!$existingAttr->isEmpty()) { - if ($this->onDuplicate === OnDuplicate::Skip - || !$this->sourceSpecIsNewer($updatedAt, $existingAttr->getUpdatedAt()) - ) { - // Destination already up-to-date; hydrate caches and skip. + if (!$this->onDuplicate->shouldReconcileSchema($updatedAt, $existingAttr->getUpdatedAt())) { + // Skip, or Upsert with dest up-to-date — tolerate. $this->dbForProject->purgeCachedDocument('database_' . $database->getSequence(), $table->getId()); $dbForDatabases->purgeCachedCollection('database_' . $database->getSequence() . '_collection_' . $table->getSequence()); return true; @@ -1050,12 +1013,11 @@ class Appwrite extends Destination // dropped + recreated. Index drops are non-destructive (no row data // lives in indexes) so rebuild cost is just the index build time. $indexMetaId = $database->getSequence() . '_' . $table->getSequence() . '_' . $resource->getKey(); - if ($this->shouldTolerateSchemaDuplicate()) { + if ($this->onDuplicate->toleratesSchemaDuplicate()) { $existingIdx = $this->dbForProject->getDocument('indexes', $indexMetaId); if (!$existingIdx->isEmpty()) { - if ($this->onDuplicate === OnDuplicate::Skip - || !$this->sourceSpecIsNewer($updatedAt, $existingIdx->getUpdatedAt()) - ) { + if (!$this->onDuplicate->shouldReconcileSchema($updatedAt, $existingIdx->getUpdatedAt())) { + // Skip, or Upsert with dest up-to-date — tolerate. $this->dbForProject->purgeCachedDocument( 'database_' . $database->getSequence(), $table->getId() diff --git a/src/Migration/Destinations/OnDuplicate.php b/src/Migration/Destinations/OnDuplicate.php index 31a0e49f71..2e3918c4f9 100644 --- a/src/Migration/Destinations/OnDuplicate.php +++ b/src/Migration/Destinations/OnDuplicate.php @@ -18,4 +18,35 @@ enum OnDuplicate: string { return \array_map(fn (self $case) => $case->value, self::cases()); } + + /** + * Skip and Upsert tolerate an existing schema resource on re-migration; + * Fail rethrows. Callers gate their pre-check on this before issuing a + * `getDocument` against the destination metadata — on Fail mode the + * library's own `DuplicateException` surfaces from the create call below. + */ + public function toleratesSchemaDuplicate(): bool + { + return $this !== self::Fail; + } + + /** + * Upsert reconciliation trigger: true iff mode is Upsert AND source's + * updatedAt is strictly newer than destination's. Skip and Fail always + * return false (they don't reconcile). Unparseable timestamps → false + * (conservative: preserve the existing destination rather than risk a + * destructive drop on garbage input). + */ + public function shouldReconcileSchema(string $sourceUpdatedAt, string $destUpdatedAt): bool + { + if ($this !== self::Upsert) { + return false; + } + $src = \strtotime($sourceUpdatedAt); + $dst = \strtotime($destUpdatedAt); + if ($src === false || $dst === false) { + return false; + } + return $src > $dst; + } } From 001682168f7d87932c56635a0d0a45b927febc33 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Wed, 22 Apr 2026 14:15:22 +0100 Subject: [PATCH 26/91] Collapse tolerate/reconcile into one decision point: resolveSchemaAction MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit OnDuplicate previously exposed two methods (toleratesSchemaDuplicate + shouldReconcileSchema) that call sites had to combine. That split meant the decision was spread across two methods and the call site — adding a new mode later would require updating all three places in sync. Replace with a single resolveSchemaAction() that returns one of three SchemaAction enum cases (Create / Tolerate / DropAndRecreate). The SchemaAction enum lives in the same file as OnDuplicate so the complete decision surface is in one place. For data-preserving containers (databases, tables) the method accepts allowDrop=false so it can never return DropAndRecreate — callers that use that path don't need to worry about accidentally dropping the container. In practice the container call sites just use the inline `$this->onDuplicate !== OnDuplicate::Fail` gate and then a simple "is empty?" branch; resolveSchemaAction() is reserved for the leaves (attributes, indexes) that actually benefit from the three-way choice. Fail-mode short-circuit is preserved at every call site: no getDocument pre-check when onDuplicate is Fail, so first-time migrations (the common default-mode path) pay zero overhead. The short-circuit stays at the call site rather than inside the enum method so the "don't query on Fail" invariant is visible where the query is issued. Call sites: - createDatabase / createEntity: inline `!== Fail` gate, tolerate on existing. No drop ever. - createField: Fail short-circuit, else resolveSchemaAction + match. DropAndRecreate triggers the two-way relationship cleanup. - createIndex: same pattern, no two-way concern. --- src/Migration/Destinations/Appwrite.php | 80 +++++++++++++--------- src/Migration/Destinations/OnDuplicate.php | 65 +++++++++++++----- 2 files changed, 94 insertions(+), 51 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index d68b6c4345..992b0e2ee6 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -428,7 +428,11 @@ class Appwrite extends Destination // existing metadata document and return. Downstream resources // (tables/columns/rows) locate the existing underlying schema via the // hydrated sequence. - if ($this->onDuplicate->toleratesSchemaDuplicate()) { + // + // Fail mode short-circuits: no pre-check, let the create below throw + // DuplicateException as designed. Saves N metadata reads on the + // common first-time-migration path. + if ($this->onDuplicate !== OnDuplicate::Fail) { $existing = $this->dbForProject->getDocument('databases', $resource->getId()); if (!$existing->isEmpty()) { $resource->setSequence($existing->getSequence()); @@ -520,8 +524,8 @@ class Appwrite extends Destination // Skip/Upsert: pre-check an existing table. Like databases, tables // contain user data (rows), so both modes simply hydrate the sequence // from the existing metadata document. Attribute/index reconciliation - // happens per-resource at a lower layer. - if ($this->onDuplicate->toleratesSchemaDuplicate()) { + // happens per-resource at a lower layer. Fail short-circuits. + if ($this->onDuplicate !== OnDuplicate::Fail) { $existing = $this->dbForProject->getDocument( 'database_' . $database->getSequence(), $resource->getId() @@ -672,22 +676,26 @@ class Appwrite extends Destination $updatedAt = $this->normalizeDateTime($resource->getUpdatedAt(), $createdAt); $dbForDatabases = ($this->getDatabasesDB)($database); - // Skip/Upsert: pre-check against `attributes` metadata. Skip tolerates - // unconditionally; Upsert tolerates unless source's updatedAt is - // strictly newer — in which case the column is dropped + recreated so - // the spec matches source. Column data is wiped on drop; rows are - // repopulated via row-level Upsert below. + // Skip/Upsert: pre-check against `attributes` metadata via one + // resolveSchemaAction call. Fail mode short-circuits to preserve + // zero-overhead fresh-migration behavior. $attributeMetaId = $database->getSequence() . '_' . $table->getSequence() . '_' . $resource->getKey(); - if ($this->onDuplicate->toleratesSchemaDuplicate()) { + if ($this->onDuplicate !== OnDuplicate::Fail) { $existingAttr = $this->dbForProject->getDocument('attributes', $attributeMetaId); - if (!$existingAttr->isEmpty()) { - if (!$this->onDuplicate->shouldReconcileSchema($updatedAt, $existingAttr->getUpdatedAt())) { - // Skip, or Upsert with dest up-to-date — tolerate. - $this->dbForProject->purgeCachedDocument('database_' . $database->getSequence(), $table->getId()); - $dbForDatabases->purgeCachedCollection('database_' . $database->getSequence() . '_collection_' . $table->getSequence()); - return true; - } - // Source spec newer: drop then recreate under the create flow. + $action = $this->onDuplicate->resolveSchemaAction( + !$existingAttr->isEmpty(), + $updatedAt, + $existingAttr->getUpdatedAt(), + ); + + if ($action === SchemaAction::Tolerate) { + $this->dbForProject->purgeCachedDocument('database_' . $database->getSequence(), $table->getId()); + $dbForDatabases->purgeCachedCollection('database_' . $database->getSequence() . '_collection_' . $table->getSequence()); + return true; + } + + if ($action === SchemaAction::DropAndRecreate) { + // Drop then fall through to the normal create flow below. $dbForDatabases->deleteAttribute( 'database_' . $database->getSequence() . '_collection_' . $table->getSequence(), $resource->getKey() @@ -727,6 +735,7 @@ class Appwrite extends Destination } } } + // SchemaAction::Create → fall through to the normal create flow. } try { @@ -1007,24 +1016,28 @@ class Appwrite extends Destination ); } - // Skip/Upsert: pre-check against `indexes` metadata. Same rule as - // attributes — Skip tolerates unconditionally; Upsert tolerates unless - // source's updatedAt is strictly newer, in which case the index is - // dropped + recreated. Index drops are non-destructive (no row data - // lives in indexes) so rebuild cost is just the index build time. + // Skip/Upsert: pre-check against `indexes` metadata via one + // resolveSchemaAction call. Same rule as attributes, except that + // index drops are non-destructive (no row data lives in indexes) so + // rebuild cost is just the index build time. Fail short-circuits. $indexMetaId = $database->getSequence() . '_' . $table->getSequence() . '_' . $resource->getKey(); - if ($this->onDuplicate->toleratesSchemaDuplicate()) { + if ($this->onDuplicate !== OnDuplicate::Fail) { $existingIdx = $this->dbForProject->getDocument('indexes', $indexMetaId); - if (!$existingIdx->isEmpty()) { - if (!$this->onDuplicate->shouldReconcileSchema($updatedAt, $existingIdx->getUpdatedAt())) { - // Skip, or Upsert with dest up-to-date — tolerate. - $this->dbForProject->purgeCachedDocument( - 'database_' . $database->getSequence(), - $table->getId() - ); - return true; - } - // Source spec newer: drop then recreate. + $action = $this->onDuplicate->resolveSchemaAction( + !$existingIdx->isEmpty(), + $updatedAt, + $existingIdx->getUpdatedAt(), + ); + + if ($action === SchemaAction::Tolerate) { + $this->dbForProject->purgeCachedDocument( + 'database_' . $database->getSequence(), + $table->getId() + ); + return true; + } + + if ($action === SchemaAction::DropAndRecreate) { $dbForDatabases->deleteIndex( 'database_' . $database->getSequence() . '_collection_' . $table->getSequence(), $resource->getKey() @@ -1035,6 +1048,7 @@ class Appwrite extends Destination $table->getId() ); } + // SchemaAction::Create → fall through to the normal create flow. } $index = $this->dbForProject->createDocument('indexes', $index); diff --git a/src/Migration/Destinations/OnDuplicate.php b/src/Migration/Destinations/OnDuplicate.php index 2e3918c4f9..ddb3d7686e 100644 --- a/src/Migration/Destinations/OnDuplicate.php +++ b/src/Migration/Destinations/OnDuplicate.php @@ -2,6 +2,23 @@ namespace Utopia\Migration\Destinations; +/** + * Caller branches on one of these three outcomes after asking + * {@see OnDuplicate::resolveSchemaAction()} what to do with a possibly + * pre-existing schema resource on the destination. + */ +enum SchemaAction +{ + /** Resource doesn't exist — run the normal create flow. */ + case Create; + + /** Resource exists; leave it alone (Skip, or Upsert with dest up-to-date). */ + case Tolerate; + + /** Resource exists; Upsert mode + source strictly newer — drop + recreate. */ + case DropAndRecreate; +} + /** * Behavior when a destination row with an existing ID is encountered. */ @@ -20,30 +37,42 @@ enum OnDuplicate: string } /** - * Skip and Upsert tolerate an existing schema resource on re-migration; - * Fail rethrows. Callers gate their pre-check on this before issuing a - * `getDocument` against the destination metadata — on Fail mode the - * library's own `DuplicateException` surfaces from the create call below. + * Single decision point for schema-level reconciliation on re-migration. + * + * Callers typically short-circuit on Fail mode before invoking this (to + * avoid the destination metadata lookup entirely — the library's own + * DuplicateException surfaces from the create call as designed). + * + * For containers whose data must be preserved (databases, tables), + * callers pass $allowDrop = false so the method never returns + * DropAndRecreate — only Create or Tolerate. */ - public function toleratesSchemaDuplicate(): bool - { - return $this !== self::Fail; + public function resolveSchemaAction( + bool $exists, + string $sourceUpdatedAt = '', + string $destUpdatedAt = '', + bool $allowDrop = true, + ): SchemaAction { + if (!$exists) { + return SchemaAction::Create; + } + return match ($this) { + self::Fail => SchemaAction::Create, // caller's create flow will throw + self::Skip => SchemaAction::Tolerate, + self::Upsert => ($allowDrop && $this->sourceIsNewer($sourceUpdatedAt, $destUpdatedAt)) + ? SchemaAction::DropAndRecreate + : SchemaAction::Tolerate, + }; } /** - * Upsert reconciliation trigger: true iff mode is Upsert AND source's - * updatedAt is strictly newer than destination's. Skip and Fail always - * return false (they don't reconcile). Unparseable timestamps → false - * (conservative: preserve the existing destination rather than risk a - * destructive drop on garbage input). + * Unparseable timestamps → false (conservative: preserve the existing + * destination rather than risk a destructive drop on garbage input). */ - public function shouldReconcileSchema(string $sourceUpdatedAt, string $destUpdatedAt): bool + private function sourceIsNewer(string $source, string $dest): bool { - if ($this !== self::Upsert) { - return false; - } - $src = \strtotime($sourceUpdatedAt); - $dst = \strtotime($destUpdatedAt); + $src = \strtotime($source); + $dst = \strtotime($dest); if ($src === false || $dst === false) { return false; } From 6ee988247b186f03447191ef21bcd6ede740cb28 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Thu, 23 Apr 2026 00:00:57 +0100 Subject: [PATCH 27/91] Refactor: extract deleteAttributeCompletely, drop dead $allowDrop, behavioral comments MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three review improvements to the schema-tolerance work: 1. OnDuplicate::resolveSchemaAction — remove the $allowDrop parameter. No caller passes it; all four call sites rely on the default. Containers (databases, tables) bypass the method entirely with an inline "!== Fail" check. The parameter advertised tuning that wasn't real, confusing readers about what was actually gated. Docstring tightened to mention that this method is only safe for leaf resources. 2. Extract deleteAttributeCompletely() as a reusable primitive that fully removes an attribute from destination — both metadata documents AND physical columns, mirroring createField's two-document write for two-way relationships. The Upsert drop block in createField shrinks from ~40 nested lines to a single method call; the two-way cleanup is now a named concern that future non-Upsert paths (Merge mode, explicit rollback, etc.) can reuse without duplication. 3. Replace line-number comments ("the first-run createField wrote TWO metadata docs (parent at line 763, child at line 819)") with behavioral descriptions ("createField writes a second `attributes` document on the related table"). Line references rot on every edit; behavioral descriptions don't. Pure refactor — no functional change. Pint + PHPStan L3 clean. --- src/Migration/Destinations/Appwrite.php | 117 ++++++++++++++------- src/Migration/Destinations/OnDuplicate.php | 11 +- 2 files changed, 85 insertions(+), 43 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index 992b0e2ee6..079a948c1b 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -695,45 +695,14 @@ class Appwrite extends Destination } if ($action === SchemaAction::DropAndRecreate) { - // Drop then fall through to the normal create flow below. - $dbForDatabases->deleteAttribute( - 'database_' . $database->getSequence() . '_collection_' . $table->getSequence(), - $resource->getKey() + $this->deleteAttributeCompletely( + $database, + $table, + $resource, + $type, + $relatedTable ?? null, + $dbForDatabases, ); - $this->dbForProject->deleteDocument('attributes', $attributeMetaId); - $this->dbForProject->purgeCachedDocument('database_' . $database->getSequence(), $table->getId()); - $dbForDatabases->purgeCachedCollection('database_' . $database->getSequence() . '_collection_' . $table->getSequence()); - - // Two-way relationships: the first-run createField wrote TWO - // metadata docs (parent at line 763, child at line 819). The - // drop above only removed the parent; without cleaning up the - // child, the recreate path hits DuplicateException at line 819 - // and the whole attribute re-migration fails. - $resourceOptions = $resource->getOptions(); - if ($type === UtopiaDatabase::VAR_RELATIONSHIP && !empty($resourceOptions['twoWay'])) { - // $relatedTable was populated at the top of createField - // inside the same VAR_RELATIONSHIP branch. - $childTwoWayKey = $resourceOptions['twoWayKey'] ?? ''; - if ($childTwoWayKey !== '') { - $childMetaId = $database->getSequence() . '_' . $relatedTable->getSequence() . '_' . $childTwoWayKey; - try { - $this->dbForProject->deleteDocument('attributes', $childMetaId); - } catch (\Throwable) { - // Child metadata already gone — interrupted prior run, nothing to do. - } - try { - $dbForDatabases->deleteAttribute( - 'database_' . $database->getSequence() . '_collection_' . $relatedTable->getSequence(), - $childTwoWayKey - ); - } catch (\Throwable) { - // Child column already gone — the parent's deleteAttribute may - // have cascaded via utopia-php/database's relationship handling. - } - $this->dbForProject->purgeCachedDocument('database_' . $database->getSequence(), $relatedTable->getId()); - $dbForDatabases->purgeCachedCollection('database_' . $database->getSequence() . '_collection_' . $relatedTable->getSequence()); - } - } } // SchemaAction::Create → fall through to the normal create flow. } @@ -1225,6 +1194,78 @@ class Appwrite extends Destination return true; } + /** + * Fully remove an attribute from destination — both metadata documents + * and the physical column(s) — so the caller can create it fresh without + * colliding with any remnants. + * + * For plain attributes this is a parent-side cleanup. For two-way + * relationship attributes, createField writes a second `attributes` + * document on the related table (under {dbSeq}_{relatedTableSeq}_{twoWayKey}) + * in addition to the parent-side document. Dropping only the parent + * side leaves the child document dangling and a subsequent recreate + * collides on it with DuplicateException. This method mirrors + * createField's two-doc write so the "reconcile" path is symmetric. + * + * Physical cleanup on the related table is best-effort: the library's + * deleteAttribute on the parent side can cascade to the child column + * depending on relationship handling, so the second deleteAttribute may + * no-op or NotFoundException — both swallowed. + * + * @param UtopiaDocument|null $relatedTable null when the attribute isn't + * a two-way relationship; + * required otherwise. + */ + private function deleteAttributeCompletely( + UtopiaDocument $database, + UtopiaDocument $table, + Column|Attribute $resource, + string $type, + ?UtopiaDocument $relatedTable, + UtopiaDatabase $dbForDatabases, + ): void { + $collectionId = 'database_' . $database->getSequence() . '_collection_' . $table->getSequence(); + $attributeMetaId = $database->getSequence() . '_' . $table->getSequence() . '_' . $resource->getKey(); + + // Parent side. + $dbForDatabases->deleteAttribute($collectionId, $resource->getKey()); + $this->dbForProject->deleteDocument('attributes', $attributeMetaId); + $this->dbForProject->purgeCachedDocument('database_' . $database->getSequence(), $table->getId()); + $dbForDatabases->purgeCachedCollection($collectionId); + + // Child side, only for two-way relationships. createField writes a + // second `attributes` document keyed on the related table; mirror + // that write here. + if ($type !== UtopiaDatabase::VAR_RELATIONSHIP || $relatedTable === null) { + return; + } + $options = $resource->getOptions(); + if (empty($options['twoWay'])) { + return; + } + $twoWayKey = $options['twoWayKey'] ?? ''; + if ($twoWayKey === '') { + return; + } + + $childCollectionId = 'database_' . $database->getSequence() . '_collection_' . $relatedTable->getSequence(); + $childMetaId = $database->getSequence() . '_' . $relatedTable->getSequence() . '_' . $twoWayKey; + + try { + $this->dbForProject->deleteDocument('attributes', $childMetaId); + } catch (\Throwable) { + // Child metadata already gone — interrupted prior run. + } + try { + $dbForDatabases->deleteAttribute($childCollectionId, $twoWayKey); + } catch (\Throwable) { + // Physical column already gone — parent-side deleteAttribute may + // have cascaded via utopia-php/database relationship handling. + } + $this->dbForProject->purgeCachedDocument('database_' . $database->getSequence(), $relatedTable->getId()); + $dbForDatabases->purgeCachedCollection($childCollectionId); + } + /** * @throws \Exception */ diff --git a/src/Migration/Destinations/OnDuplicate.php b/src/Migration/Destinations/OnDuplicate.php index ddb3d7686e..84937a8a72 100644 --- a/src/Migration/Destinations/OnDuplicate.php +++ b/src/Migration/Destinations/OnDuplicate.php @@ -43,15 +43,16 @@ enum OnDuplicate: string * avoid the destination metadata lookup entirely — the library's own * DuplicateException surfaces from the create call as designed). * - * For containers whose data must be preserved (databases, tables), - * callers pass $allowDrop = false so the method never returns - * DropAndRecreate — only Create or Tolerate. + * Only safe to call for leaf resources (attributes, indexes) that can be + * dropped to reconcile. Containers whose data must be preserved + * (databases, tables) should use the simpler "tolerate existing" inline + * check instead — this method's DropAndRecreate outcome would destroy + * their user data. */ public function resolveSchemaAction( bool $exists, string $sourceUpdatedAt = '', string $destUpdatedAt = '', - bool $allowDrop = true, ): SchemaAction { if (!$exists) { return SchemaAction::Create; @@ -59,7 +60,7 @@ enum OnDuplicate: string return match ($this) { self::Fail => SchemaAction::Create, // caller's create flow will throw self::Skip => SchemaAction::Tolerate, - self::Upsert => ($allowDrop && $this->sourceIsNewer($sourceUpdatedAt, $destUpdatedAt)) + self::Upsert => $this->sourceIsNewer($sourceUpdatedAt, $destUpdatedAt) ? SchemaAction::DropAndRecreate : SchemaAction::Tolerate, }; From cfba224f73f00d236a748553d87381a4cf77d0f6 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Thu, 23 Apr 2026 00:09:03 +0100 Subject: [PATCH 28/91] Add unit tests for OnDuplicate::resolveSchemaAction; harden zero-date handling MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit resolveSchemaAction is the load-bearing decision point for re-migration tolerance. Unit test locks the full mode × existence × timestamp matrix so a future refactor can't silently shift the mapping. 14 tests, sub-millisecond to run, no destination spin-up required. Coverage: - Not-exists returns Create for all modes. - Fail + exists → Create (routed through create flow so library DuplicateException surfaces as designed, not silently tolerated). - Skip ignores timestamps entirely — "don't touch" contract enforced by verifying both timestamp orderings produce Tolerate. - Upsert with source strictly newer → DropAndRecreate. - Upsert with dest newer or equal timestamps → Tolerate (strict > gate avoids unnecessary destructive rebuild when nothing has changed). - Upsert with unparseable timestamps → Tolerate (conservative, dataset covers empty strings, '0000-00-00 00:00:00', and non-date garbage). - OnDuplicate::values() case ordering guarded against accidental rename/reorder that would break SDK param validators. Writing the test surfaced a real gap in sourceIsNewer: PHP's strtotime() accepts '0000-00-00 00:00:00' leniently and returns a large negative epoch (-62169984000) rather than false. The previous `=== false` check missed the MySQL zero-date sentinel and would have returned true when source was a valid date and dest was '0000-00-00', triggering a destructive drop on garbage input. Harden sourceIsNewer to additionally reject non-positive epochs (<= 0) — any legitimate Appwrite updatedAt is well past 1970-01-01. --- src/Migration/Destinations/OnDuplicate.php | 11 +- .../Unit/General/OnDuplicateTest.php | 140 ++++++++++++++++++ 2 files changed, 148 insertions(+), 3 deletions(-) create mode 100644 tests/Migration/Unit/General/OnDuplicateTest.php diff --git a/src/Migration/Destinations/OnDuplicate.php b/src/Migration/Destinations/OnDuplicate.php index 84937a8a72..19116b2426 100644 --- a/src/Migration/Destinations/OnDuplicate.php +++ b/src/Migration/Destinations/OnDuplicate.php @@ -67,14 +67,19 @@ enum OnDuplicate: string } /** - * Unparseable timestamps → false (conservative: preserve the existing - * destination rather than risk a destructive drop on garbage input). + * Unparseable or clearly-invalid timestamps → false (conservative: + * preserve the existing destination rather than risk a destructive drop + * on garbage input). PHP's strtotime() accepts some malformed dates + * leniently — '0000-00-00 00:00:00' for example parses to a large + * negative epoch rather than returning false — so we also reject + * non-positive epochs. Any legitimate Appwrite updatedAt is well past + * 1970-01-01. */ private function sourceIsNewer(string $source, string $dest): bool { $src = \strtotime($source); $dst = \strtotime($dest); - if ($src === false || $dst === false) { + if ($src === false || $dst === false || $src <= 0 || $dst <= 0) { return false; } return $src > $dst; diff --git a/tests/Migration/Unit/General/OnDuplicateTest.php b/tests/Migration/Unit/General/OnDuplicateTest.php new file mode 100644 index 0000000000..adebac1382 --- /dev/null +++ b/tests/Migration/Unit/General/OnDuplicateTest.php @@ -0,0 +1,140 @@ +assertSame( + SchemaAction::Create, + $mode->resolveSchemaAction(exists: false), + "{$mode->value} on non-existing resource must return Create", + ); + } + } + + public function testFailExistsReturnsCreateSoCallerDDLThrows(): void + { + // Fail is routed through Create (not Tolerate) so the caller's normal + // create flow runs and the library surfaces DuplicateException as + // designed. Returning Tolerate here would silently hide the error. + $this->assertSame( + SchemaAction::Create, + OnDuplicate::Fail->resolveSchemaAction(exists: true), + ); + } + + public function testSkipAlwaysToleratesExisting(): void + { + // Skip must ignore timestamps entirely — it's the "don't touch" + // contract. Exercise both orderings to prove the comparison isn't + // consulted. + $this->assertSame( + SchemaAction::Tolerate, + OnDuplicate::Skip->resolveSchemaAction( + exists: true, + sourceUpdatedAt: '2026-01-01T00:00:00.000+00:00', + destUpdatedAt: '2020-01-01T00:00:00.000+00:00', + ), + ); + $this->assertSame( + SchemaAction::Tolerate, + OnDuplicate::Skip->resolveSchemaAction( + exists: true, + sourceUpdatedAt: '2020-01-01T00:00:00.000+00:00', + destUpdatedAt: '2026-01-01T00:00:00.000+00:00', + ), + ); + } + + public function testUpsertSourceStrictlyNewerReconciles(): void + { + $this->assertSame( + SchemaAction::DropAndRecreate, + OnDuplicate::Upsert->resolveSchemaAction( + exists: true, + sourceUpdatedAt: '2026-04-23T10:00:00.000+00:00', + destUpdatedAt: '2026-04-23T09:59:59.000+00:00', + ), + ); + } + + public function testUpsertDestNewerTolerates(): void + { + $this->assertSame( + SchemaAction::Tolerate, + OnDuplicate::Upsert->resolveSchemaAction( + exists: true, + sourceUpdatedAt: '2026-04-23T09:00:00.000+00:00', + destUpdatedAt: '2026-04-23T10:00:00.000+00:00', + ), + ); + } + + public function testUpsertEqualTimestampsTolerates(): void + { + // Strict > comparison: equal means dest is already in sync, skip the + // drop. Avoids unnecessary destructive rebuild when the user hasn't + // touched source since the last migration. + $stamp = '2026-04-23T10:00:00.000+00:00'; + $this->assertSame( + SchemaAction::Tolerate, + OnDuplicate::Upsert->resolveSchemaAction( + exists: true, + sourceUpdatedAt: $stamp, + destUpdatedAt: $stamp, + ), + ); + } + + /** + * @return array + */ + public static function unparseableTimestampPairs(): array + { + return [ + 'both empty' => ['', ''], + 'source empty' => ['', '2026-04-23T10:00:00.000+00:00'], + 'dest empty' => ['2026-04-23T10:00:00.000+00:00', ''], + 'source zero-date' => ['0000-00-00 00:00:00', '2026-04-23T10:00:00.000+00:00'], + 'dest zero-date' => ['2026-04-23T10:00:00.000+00:00', '0000-00-00 00:00:00'], + 'source garbage' => ['not-a-date', '2026-04-23T10:00:00.000+00:00'], + 'dest garbage' => ['2026-04-23T10:00:00.000+00:00', 'not-a-date'], + ]; + } + + #[DataProvider('unparseableTimestampPairs')] + public function testUpsertUnparseableTimestampsTolerate(string $source, string $dest): void + { + // Conservative: unparseable timestamps preserve existing destination + // rather than risk a destructive drop on garbage input. Any + // non-Appwrite source that emits malformed dates gets handled safely. + $this->assertSame( + SchemaAction::Tolerate, + OnDuplicate::Upsert->resolveSchemaAction( + exists: true, + sourceUpdatedAt: $source, + destUpdatedAt: $dest, + ), + ); + } + + public function testValuesListsAllCasesInDeclarationOrder(): void + { + // The values() helper is consumed by API/SDK param validators; this + // tests protects against an accidental case-rename or reorder. + $this->assertSame(['fail', 'skip', 'upsert'], OnDuplicate::values()); + } +} From e08d531d7cab9c6aeed4fa28cfe326449b0dd3b0 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Thu, 23 Apr 2026 06:05:36 +0100 Subject: [PATCH 29/91] Upsert: update database/table metadata in-place when source is newer MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Extends the Upsert reconciliation to cover container metadata drift. Previously databases and tables always tolerated an existing destination under Upsert — source renames, enable toggles, and (for tables) permission changes silently never reached destination on re-migration. Now Upsert + source strictly newer triggers an updateDocument on the container's own metadata doc, leaving children (rows, sub-resources) untouched. Mechanism: - New SchemaAction::UpdateInPlace case alongside Create / Tolerate / DropAndRecreate. - OnDuplicate::resolveSchemaAction gains a canDrop parameter (default false — safer default, destructive reconciliation must be opt-in): canDrop: true → DropAndRecreate on Upsert-newer (attributes, indexes) canDrop: false → UpdateInPlace on Upsert-newer (databases, tables) - createField / createIndex pass canDrop: true. - createDatabase / createEntity rely on the default and handle SchemaAction::UpdateInPlace by calling updateDocument with a scoped field set: Database → name, search, enabled, type, originalId, database, $updatedAt Table → name, search, enabled, $permissions, documentSecurity, $updatedAt Immutable fields ($id, $createdAt, internal sequences) are never touched. Source-wins semantics for table permissions follow the full-Upsert contract: if the caller wants destination drift preserved across re-runs, they should pick Skip mode, not Upsert. Row Upsert already works this way; containers now match. Unit tests cover both canDrop branches and confirm Skip never returns UpdateInPlace regardless of timestamps (reinforcing the "don't touch" contract). 16 tests, pint + phpstan L3 clean. --- src/Migration/Destinations/Appwrite.php | 67 ++++++++++++++++--- src/Migration/Destinations/OnDuplicate.php | 36 +++++++--- .../Unit/General/OnDuplicateTest.php | 35 +++++++++- 3 files changed, 120 insertions(+), 18 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index 079a948c1b..0d4b076850 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -424,20 +424,40 @@ class Appwrite extends Destination // Skip/Upsert: pre-check an existing database. Databases contain the // entire tree of collections + rows, so they are never destructively - // reconciled — both modes simply hydrate the sequence from the - // existing metadata document and return. Downstream resources - // (tables/columns/rows) locate the existing underlying schema via the - // hydrated sequence. + // reconciled — under Upsert-newer the container metadata is updated + // in place (name, enabled, etc.) but children are untouched. // // Fail mode short-circuits: no pre-check, let the create below throw // DuplicateException as designed. Saves N metadata reads on the // common first-time-migration path. if ($this->onDuplicate !== OnDuplicate::Fail) { $existing = $this->dbForProject->getDocument('databases', $resource->getId()); - if (!$existing->isEmpty()) { + $action = $this->onDuplicate->resolveSchemaAction( + !$existing->isEmpty(), + $updatedAt, + $existing->getUpdatedAt(), + // canDrop: false by default — databases hold child tables + rows. + ); + + if ($action === SchemaAction::Tolerate) { $resource->setSequence($existing->getSequence()); return true; } + + if ($action === SchemaAction::UpdateInPlace) { + $this->dbForProject->updateDocument('databases', $existing->getId(), new UtopiaDocument([ + 'name' => $resource->getDatabaseName(), + 'search' => implode(' ', [$resource->getId(), $resource->getDatabaseName()]), + 'enabled' => $resource->getEnabled(), + 'type' => empty($resource->getType()) ? 'legacy' : $resource->getType(), + 'originalId' => empty($resource->getOriginalId()) ? null : $resource->getOriginalId(), + 'database' => $resource->getDatabase(), + '$updatedAt' => $updatedAt, + ])); + $resource->setSequence($existing->getSequence()); + return true; + } + // SchemaAction::Create → fall through to the normal create flow. } $database = $this->dbForProject->createDocument('databases', new UtopiaDocument([ @@ -522,18 +542,45 @@ class Appwrite extends Destination } // Skip/Upsert: pre-check an existing table. Like databases, tables - // contain user data (rows), so both modes simply hydrate the sequence - // from the existing metadata document. Attribute/index reconciliation - // happens per-resource at a lower layer. Fail short-circuits. + // contain user data (rows) so they are never destructively + // reconciled — under Upsert-newer the container metadata is + // updated in place (name, enabled, permissions, etc.) but child + // rows are untouched. Attribute/index reconciliation happens + // per-resource at a lower layer. Fail short-circuits. if ($this->onDuplicate !== OnDuplicate::Fail) { $existing = $this->dbForProject->getDocument( 'database_' . $database->getSequence(), $resource->getId() ); - if (!$existing->isEmpty()) { + $action = $this->onDuplicate->resolveSchemaAction( + !$existing->isEmpty(), + $updatedAt, + $existing->getUpdatedAt(), + // canDrop: false by default — tables hold child rows. + ); + + if ($action === SchemaAction::Tolerate) { $resource->setSequence($existing->getSequence()); return true; } + + if ($action === SchemaAction::UpdateInPlace) { + $this->dbForProject->updateDocument( + 'database_' . $database->getSequence(), + $existing->getId(), + new UtopiaDocument([ + 'name' => $resource->getTableName(), + 'search' => implode(' ', [$resource->getId(), $resource->getTableName()]), + 'enabled' => $resource->getEnabled(), + '$permissions' => Permission::aggregate($resource->getPermissions()), + 'documentSecurity' => $resource->getRowSecurity(), + '$updatedAt' => $updatedAt, + ]) + ); + $resource->setSequence($existing->getSequence()); + return true; + } + // SchemaAction::Create → fall through to the normal create flow. } $table = $this->dbForProject->createDocument('database_' . $database->getSequence(), new UtopiaDocument([ @@ -686,6 +733,7 @@ class Appwrite extends Destination !$existingAttr->isEmpty(), $updatedAt, $existingAttr->getUpdatedAt(), + canDrop: true, // attributes are leaves; column data repopulates via row Upsert ); if ($action === SchemaAction::Tolerate) { @@ -996,6 +1044,7 @@ class Appwrite extends Destination !$existingIdx->isEmpty(), $updatedAt, $existingIdx->getUpdatedAt(), + canDrop: true, // indexes are leaves; carry no user data ); if ($action === SchemaAction::Tolerate) { diff --git a/src/Migration/Destinations/OnDuplicate.php b/src/Migration/Destinations/OnDuplicate.php index 19116b2426..6e53218c6f 100644 --- a/src/Migration/Destinations/OnDuplicate.php +++ b/src/Migration/Destinations/OnDuplicate.php @@ -3,7 +3,7 @@ namespace Utopia\Migration\Destinations; /** - * Caller branches on one of these three outcomes after asking + * Caller branches on one of these outcomes after asking * {@see OnDuplicate::resolveSchemaAction()} what to do with a possibly * pre-existing schema resource on the destination. */ @@ -15,8 +15,22 @@ enum SchemaAction /** Resource exists; leave it alone (Skip, or Upsert with dest up-to-date). */ case Tolerate; - /** Resource exists; Upsert mode + source strictly newer — drop + recreate. */ + /** + * Resource exists; Upsert mode + source strictly newer + resource is a + * leaf (attribute/index) — drop + recreate. Data-preserving containers + * get {@see self::UpdateInPlace} instead. + */ case DropAndRecreate; + + /** + * Resource exists; Upsert mode + source strictly newer + resource is a + * container (database/table) — update metadata in place without + * touching children. Callers should only overwrite fields that are + * safe to source-wins (name, enabled, search, permissions, etc.) and + * must never touch immutable fields ($id, $createdAt, internal + * sequences). + */ + case UpdateInPlace; } /** @@ -43,16 +57,22 @@ enum OnDuplicate: string * avoid the destination metadata lookup entirely — the library's own * DuplicateException surfaces from the create call as designed). * - * Only safe to call for leaf resources (attributes, indexes) that can be - * dropped to reconcile. Containers whose data must be preserved - * (databases, tables) should use the simpler "tolerate existing" inline - * check instead — this method's DropAndRecreate outcome would destroy - * their user data. + * $canDrop picks the Upsert-newer reconciliation strategy; default + * false is the safe option — destructive reconciliation requires + * explicit opt-in at the call site: + * - true → DropAndRecreate (attributes, indexes; column data is + * repopulated by the follow-up row Upsert, or is pure + * metadata for indexes). + * - false → UpdateInPlace (databases, tables; their child rows and + * sub-resources must be preserved, so destructive + * reconciliation is replaced with an updateDocument on the + * container's own metadata document). */ public function resolveSchemaAction( bool $exists, string $sourceUpdatedAt = '', string $destUpdatedAt = '', + bool $canDrop = false, ): SchemaAction { if (!$exists) { return SchemaAction::Create; @@ -61,7 +81,7 @@ enum OnDuplicate: string self::Fail => SchemaAction::Create, // caller's create flow will throw self::Skip => SchemaAction::Tolerate, self::Upsert => $this->sourceIsNewer($sourceUpdatedAt, $destUpdatedAt) - ? SchemaAction::DropAndRecreate + ? ($canDrop ? SchemaAction::DropAndRecreate : SchemaAction::UpdateInPlace) : SchemaAction::Tolerate, }; } diff --git a/tests/Migration/Unit/General/OnDuplicateTest.php b/tests/Migration/Unit/General/OnDuplicateTest.php index adebac1382..a4f57c0a2a 100644 --- a/tests/Migration/Unit/General/OnDuplicateTest.php +++ b/tests/Migration/Unit/General/OnDuplicateTest.php @@ -59,14 +59,47 @@ class OnDuplicateTest extends TestCase ); } - public function testUpsertSourceStrictlyNewerReconciles(): void + public function testUpsertLeafSourceNewerDropsAndRecreates(): void { + // canDrop: true → leaf resource (attribute, index). Column data is + // repopulated by the follow-up row Upsert, or the resource is pure + // metadata (index) so destructive reconciliation is safe. $this->assertSame( SchemaAction::DropAndRecreate, OnDuplicate::Upsert->resolveSchemaAction( exists: true, sourceUpdatedAt: '2026-04-23T10:00:00.000+00:00', destUpdatedAt: '2026-04-23T09:59:59.000+00:00', + canDrop: true, + ), + ); + } + + public function testUpsertContainerSourceNewerUpdatesInPlace(): void + { + // Default canDrop: false → container resource (database, table). + // Container's metadata doc gets updateDocument; children (tables, + // rows) are preserved untouched. + $this->assertSame( + SchemaAction::UpdateInPlace, + OnDuplicate::Upsert->resolveSchemaAction( + exists: true, + sourceUpdatedAt: '2026-04-23T10:00:00.000+00:00', + destUpdatedAt: '2026-04-23T09:59:59.000+00:00', + ), + ); + } + + public function testSkipNeverUpdatesContainerEvenWhenSourceNewer(): void + { + // Skip is strict "don't touch" — must never return UpdateInPlace, + // only Tolerate, regardless of timestamps or resource kind. + $this->assertSame( + SchemaAction::Tolerate, + OnDuplicate::Skip->resolveSchemaAction( + exists: true, + sourceUpdatedAt: '2026-04-23T10:00:00.000+00:00', + destUpdatedAt: '2026-04-23T09:59:59.000+00:00', ), ); } From 2bf1c83283300595e1d26d4f81a6c551219c8bee Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Thu, 23 Apr 2026 07:00:58 +0100 Subject: [PATCH 30/91] Trim verbose comments, keep only essential 'why' explanations --- src/Migration/Destinations/Appwrite.php | 64 +++------------------- src/Migration/Destinations/OnDuplicate.php | 55 +++---------------- 2 files changed, 17 insertions(+), 102 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index 0d4b076850..7b06c729f5 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -422,21 +422,13 @@ class Appwrite extends Destination $createdAt = $this->normalizeDateTime($resource->getCreatedAt()); $updatedAt = $this->normalizeDateTime($resource->getUpdatedAt(), $createdAt); - // Skip/Upsert: pre-check an existing database. Databases contain the - // entire tree of collections + rows, so they are never destructively - // reconciled — under Upsert-newer the container metadata is updated - // in place (name, enabled, etc.) but children are untouched. - // - // Fail mode short-circuits: no pre-check, let the create below throw - // DuplicateException as designed. Saves N metadata reads on the - // common first-time-migration path. + // Fail mode skips the pre-check so library's DuplicateException surfaces on re-migration. if ($this->onDuplicate !== OnDuplicate::Fail) { $existing = $this->dbForProject->getDocument('databases', $resource->getId()); $action = $this->onDuplicate->resolveSchemaAction( !$existing->isEmpty(), $updatedAt, $existing->getUpdatedAt(), - // canDrop: false by default — databases hold child tables + rows. ); if ($action === SchemaAction::Tolerate) { @@ -457,7 +449,6 @@ class Appwrite extends Destination $resource->setSequence($existing->getSequence()); return true; } - // SchemaAction::Create → fall through to the normal create flow. } $database = $this->dbForProject->createDocument('databases', new UtopiaDocument([ @@ -541,12 +532,6 @@ class Appwrite extends Destination $dbForDatabases->create(); } - // Skip/Upsert: pre-check an existing table. Like databases, tables - // contain user data (rows) so they are never destructively - // reconciled — under Upsert-newer the container metadata is - // updated in place (name, enabled, permissions, etc.) but child - // rows are untouched. Attribute/index reconciliation happens - // per-resource at a lower layer. Fail short-circuits. if ($this->onDuplicate !== OnDuplicate::Fail) { $existing = $this->dbForProject->getDocument( 'database_' . $database->getSequence(), @@ -556,7 +541,6 @@ class Appwrite extends Destination !$existing->isEmpty(), $updatedAt, $existing->getUpdatedAt(), - // canDrop: false by default — tables hold child rows. ); if ($action === SchemaAction::Tolerate) { @@ -580,7 +564,6 @@ class Appwrite extends Destination $resource->setSequence($existing->getSequence()); return true; } - // SchemaAction::Create → fall through to the normal create flow. } $table = $this->dbForProject->createDocument('database_' . $database->getSequence(), new UtopiaDocument([ @@ -723,9 +706,6 @@ class Appwrite extends Destination $updatedAt = $this->normalizeDateTime($resource->getUpdatedAt(), $createdAt); $dbForDatabases = ($this->getDatabasesDB)($database); - // Skip/Upsert: pre-check against `attributes` metadata via one - // resolveSchemaAction call. Fail mode short-circuits to preserve - // zero-overhead fresh-migration behavior. $attributeMetaId = $database->getSequence() . '_' . $table->getSequence() . '_' . $resource->getKey(); if ($this->onDuplicate !== OnDuplicate::Fail) { $existingAttr = $this->dbForProject->getDocument('attributes', $attributeMetaId); @@ -733,7 +713,7 @@ class Appwrite extends Destination !$existingAttr->isEmpty(), $updatedAt, $existingAttr->getUpdatedAt(), - canDrop: true, // attributes are leaves; column data repopulates via row Upsert + canDrop: true, ); if ($action === SchemaAction::Tolerate) { @@ -752,7 +732,6 @@ class Appwrite extends Destination $dbForDatabases, ); } - // SchemaAction::Create → fall through to the normal create flow. } try { @@ -1033,10 +1012,6 @@ class Appwrite extends Destination ); } - // Skip/Upsert: pre-check against `indexes` metadata via one - // resolveSchemaAction call. Same rule as attributes, except that - // index drops are non-destructive (no row data lives in indexes) so - // rebuild cost is just the index build time. Fail short-circuits. $indexMetaId = $database->getSequence() . '_' . $table->getSequence() . '_' . $resource->getKey(); if ($this->onDuplicate !== OnDuplicate::Fail) { $existingIdx = $this->dbForProject->getDocument('indexes', $indexMetaId); @@ -1044,7 +1019,7 @@ class Appwrite extends Destination !$existingIdx->isEmpty(), $updatedAt, $existingIdx->getUpdatedAt(), - canDrop: true, // indexes are leaves; carry no user data + canDrop: true, ); if ($action === SchemaAction::Tolerate) { @@ -1066,7 +1041,6 @@ class Appwrite extends Destination $table->getId() ); } - // SchemaAction::Create → fall through to the normal create flow. } $index = $this->dbForProject->createDocument('indexes', $index); @@ -1244,26 +1218,11 @@ class Appwrite extends Destination } /** - * Fully remove an attribute from destination — both metadata documents - * and the physical column(s) — so the caller can create it fresh without - * colliding with any remnants. + * Drop an attribute (metadata doc + physical column) so it can be recreated. * - * For plain attributes this is a parent-side cleanup. For two-way - * relationship attributes, createField writes a second `attributes` - * document on the related table (under {dbSeq}_{relatedTableSeq}_{twoWayKey}) - * in addition to the parent-side document. Dropping only the parent - * side leaves the child document dangling and a subsequent recreate - * collides on it with DuplicateException. This method mirrors - * createField's two-doc write so the "reconcile" path is symmetric. - * - * Physical cleanup on the related table is best-effort: the library's - * deleteAttribute on the parent side can cascade to the child column - * depending on relationship handling, so the second deleteAttribute may - * no-op or NotFoundException — both swallowed. - * - * @param UtopiaDocument|null $relatedTable null when the attribute isn't - * a two-way relationship; - * required otherwise. + * Two-way relationships require mirroring: createField writes a second + * `attributes` document on the related table keyed by twoWayKey. Dropping + * only the parent leaves that child doc dangling and the recreate collides. */ private function deleteAttributeCompletely( UtopiaDocument $database, @@ -1276,15 +1235,11 @@ class Appwrite extends Destination $collectionId = 'database_' . $database->getSequence() . '_collection_' . $table->getSequence(); $attributeMetaId = $database->getSequence() . '_' . $table->getSequence() . '_' . $resource->getKey(); - // Parent side. $dbForDatabases->deleteAttribute($collectionId, $resource->getKey()); $this->dbForProject->deleteDocument('attributes', $attributeMetaId); $this->dbForProject->purgeCachedDocument('database_' . $database->getSequence(), $table->getId()); $dbForDatabases->purgeCachedCollection($collectionId); - // Child side, only for two-way relationships. createField writes a - // second `attributes` document keyed on the related table; mirror - // that write here. if ($type !== UtopiaDatabase::VAR_RELATIONSHIP || $relatedTable === null) { return; } @@ -1303,13 +1258,12 @@ class Appwrite extends Destination try { $this->dbForProject->deleteDocument('attributes', $childMetaId); } catch (\Throwable) { - // Child metadata already gone — interrupted prior run. + // already gone } try { $dbForDatabases->deleteAttribute($childCollectionId, $twoWayKey); } catch (\Throwable) { - // Physical column already gone — parent-side deleteAttribute may - // have cascaded via utopia-php/database relationship handling. + // parent-side delete may have cascaded } $this->dbForProject->purgeCachedDocument('database_' . $database->getSequence(), $relatedTable->getId()); $dbForDatabases->purgeCachedCollection($childCollectionId); diff --git a/src/Migration/Destinations/OnDuplicate.php b/src/Migration/Destinations/OnDuplicate.php index 6e53218c6f..1c90ec679e 100644 --- a/src/Migration/Destinations/OnDuplicate.php +++ b/src/Migration/Destinations/OnDuplicate.php @@ -3,39 +3,16 @@ namespace Utopia\Migration\Destinations; /** - * Caller branches on one of these outcomes after asking - * {@see OnDuplicate::resolveSchemaAction()} what to do with a possibly - * pre-existing schema resource on the destination. + * Outcome of {@see OnDuplicate::resolveSchemaAction()}. */ enum SchemaAction { - /** Resource doesn't exist — run the normal create flow. */ case Create; - - /** Resource exists; leave it alone (Skip, or Upsert with dest up-to-date). */ case Tolerate; - - /** - * Resource exists; Upsert mode + source strictly newer + resource is a - * leaf (attribute/index) — drop + recreate. Data-preserving containers - * get {@see self::UpdateInPlace} instead. - */ case DropAndRecreate; - - /** - * Resource exists; Upsert mode + source strictly newer + resource is a - * container (database/table) — update metadata in place without - * touching children. Callers should only overwrite fields that are - * safe to source-wins (name, enabled, search, permissions, etc.) and - * must never touch immutable fields ($id, $createdAt, internal - * sequences). - */ case UpdateInPlace; } -/** - * Behavior when a destination row with an existing ID is encountered. - */ enum OnDuplicate: string { case Fail = 'fail'; @@ -51,22 +28,11 @@ enum OnDuplicate: string } /** - * Single decision point for schema-level reconciliation on re-migration. + * Schema-level reconciliation decision. * - * Callers typically short-circuit on Fail mode before invoking this (to - * avoid the destination metadata lookup entirely — the library's own - * DuplicateException surfaces from the create call as designed). - * - * $canDrop picks the Upsert-newer reconciliation strategy; default - * false is the safe option — destructive reconciliation requires - * explicit opt-in at the call site: - * - true → DropAndRecreate (attributes, indexes; column data is - * repopulated by the follow-up row Upsert, or is pure - * metadata for indexes). - * - false → UpdateInPlace (databases, tables; their child rows and - * sub-resources must be preserved, so destructive - * reconciliation is replaced with an updateDocument on the - * container's own metadata document). + * $canDrop = true → leaves (attributes, indexes) get DropAndRecreate on Upsert-newer. + * $canDrop = false → containers (databases, tables) get UpdateInPlace on Upsert-newer. + * Default is false so destructive reconciliation requires explicit opt-in. */ public function resolveSchemaAction( bool $exists, @@ -78,7 +44,7 @@ enum OnDuplicate: string return SchemaAction::Create; } return match ($this) { - self::Fail => SchemaAction::Create, // caller's create flow will throw + self::Fail => SchemaAction::Create, self::Skip => SchemaAction::Tolerate, self::Upsert => $this->sourceIsNewer($sourceUpdatedAt, $destUpdatedAt) ? ($canDrop ? SchemaAction::DropAndRecreate : SchemaAction::UpdateInPlace) @@ -87,13 +53,8 @@ enum OnDuplicate: string } /** - * Unparseable or clearly-invalid timestamps → false (conservative: - * preserve the existing destination rather than risk a destructive drop - * on garbage input). PHP's strtotime() accepts some malformed dates - * leniently — '0000-00-00 00:00:00' for example parses to a large - * negative epoch rather than returning false — so we also reject - * non-positive epochs. Any legitimate Appwrite updatedAt is well past - * 1970-01-01. + * strtotime() accepts '0000-00-00' leniently (returns a large negative + * epoch, not false), so reject non-positive epochs too. */ private function sourceIsNewer(string $source, string $dest): bool { From bb21912e8cb501e5144b6bc6e1d0c9a6918a88d1 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Thu, 23 Apr 2026 16:35:27 +0100 Subject: [PATCH 31/91] Mark Tolerate outcomes as SKIPPED so counters reflect no-op re-migrations --- src/Migration/Destinations/Appwrite.php | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index 7b06c729f5..fdc70f14e6 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -433,7 +433,8 @@ class Appwrite extends Destination if ($action === SchemaAction::Tolerate) { $resource->setSequence($existing->getSequence()); - return true; + $resource->setStatus(Resource::STATUS_SKIPPED, 'Already exists on destination'); + return false; } if ($action === SchemaAction::UpdateInPlace) { @@ -545,7 +546,8 @@ class Appwrite extends Destination if ($action === SchemaAction::Tolerate) { $resource->setSequence($existing->getSequence()); - return true; + $resource->setStatus(Resource::STATUS_SKIPPED, 'Already exists on destination'); + return false; } if ($action === SchemaAction::UpdateInPlace) { @@ -719,7 +721,8 @@ class Appwrite extends Destination if ($action === SchemaAction::Tolerate) { $this->dbForProject->purgeCachedDocument('database_' . $database->getSequence(), $table->getId()); $dbForDatabases->purgeCachedCollection('database_' . $database->getSequence() . '_collection_' . $table->getSequence()); - return true; + $resource->setStatus(Resource::STATUS_SKIPPED, 'Already exists on destination'); + return false; } if ($action === SchemaAction::DropAndRecreate) { @@ -1027,7 +1030,8 @@ class Appwrite extends Destination 'database_' . $database->getSequence(), $table->getId() ); - return true; + $resource->setStatus(Resource::STATUS_SKIPPED, 'Already exists on destination'); + return false; } if ($action === SchemaAction::DropAndRecreate) { From 36fdf269fe1c6fac2a1d80f5b913493c18989727 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Fri, 24 Apr 2026 05:55:29 +0100 Subject: [PATCH 32/91] Upsert orphan cleanup + nullable timestamps + refactor MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Track attribute/index keys seen from source per (db, table); after rows land per table (and in a final sweep at end-of-run) drop destination attributes/indexes whose keys source did not emit. Source rename (delete+create) on source now propagates as a drop on destination without leaving the old column orphaned. Gated to Upsert mode only. - resolveSchemaAction now accepts nullable timestamps — attribute docs with missing $updatedAt no longer throw TypeError, they fall through to Tolerate (same conservative handling as zero-date/garbage input). - Tolerate branches mark resources as SKIPPED instead of implicit SUCCESS so re-migration counters reflect 'already exists' no-ops. - Internal refactor: consolidated 3 orphan-tracker state fields into one $orphanScopes map; extracted dropOrphansByKind(), tolerateMissing(), dropTwoWayMirror() helpers; renamed deleteAttributeCompletely to dropAttributeForRecreate. --- src/Migration/Destinations/Appwrite.php | 264 +++++++++++++++++- src/Migration/Destinations/OnDuplicate.php | 21 +- .../Unit/General/OnDuplicateTest.php | 5 +- 3 files changed, 271 insertions(+), 19 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index fdc70f14e6..4dbf091f41 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -85,6 +85,23 @@ class Appwrite extends Destination */ private array $rowBuffer = []; + /** + * Upsert-mode orphan tracking. For each (database, table) scope we saw + * during the migration, records the attribute + index keys that came + * from source plus the docs/handles needed to reach the destination. + * Scopes are removed from this map after their cleanup has run, so a + * final sweep at end-of-migration only visits tables that had no rows. + * + * @var array, + * indexKeys: list, + * }> + */ + private array $orphanScopes = []; + /** * @param string $project * @param string $endpoint @@ -122,6 +139,22 @@ class Appwrite extends Destination $this->getDatabasesDB = $getDatabasesDB; } + /** + * Upsert-mode orphan cleanup runs after a successful migration only. + * A thrown exception from the source/import loop short-circuits here + * so mid-migration failures preserve the destination as-is. + */ + #[Override] + public function run( + array $resources, + callable $callback, + string $rootResourceId = '', + string $rootResourceType = '', + ): void { + parent::run($resources, $callback, $rootResourceId, $rootResourceType); + $this->cleanupUpsertOrphans(); + } + public static function getName(): string { return 'Appwrite'; @@ -708,6 +741,8 @@ class Appwrite extends Destination $updatedAt = $this->normalizeDateTime($resource->getUpdatedAt(), $createdAt); $dbForDatabases = ($this->getDatabasesDB)($database); + $this->trackOrphanCandidate($database, $table, 'attributeKeys', $resource->getKey(), $dbForDatabases); + $attributeMetaId = $database->getSequence() . '_' . $table->getSequence() . '_' . $resource->getKey(); if ($this->onDuplicate !== OnDuplicate::Fail) { $existingAttr = $this->dbForProject->getDocument('attributes', $attributeMetaId); @@ -726,7 +761,7 @@ class Appwrite extends Destination } if ($action === SchemaAction::DropAndRecreate) { - $this->deleteAttributeCompletely( + $this->dropAttributeForRecreate( $database, $table, $resource, @@ -963,6 +998,8 @@ class Appwrite extends Destination $createdAt = $this->normalizeDateTime($resource->getCreatedAt()); $updatedAt = $this->normalizeDateTime($resource->getUpdatedAt(), $createdAt); + $this->trackOrphanCandidate($database, $table, 'indexKeys', $resource->getKey(), $dbForDatabases); + $index = new UtopiaDocument([ '$id' => ID::custom($database->getSequence() . '_' . $table->getSequence() . '_' . $resource->getKey()), 'key' => $resource->getKey(), @@ -1170,6 +1207,13 @@ class Appwrite extends Destination $databaseInternalId = $database->getSequence(); $tableInternalId = $table->getSequence(); $dbForDatabases = ($this->getDatabasesDB)($database); + + // Reconcile the destination SCHEMA before rows land: drops + // attributes/indexes source no longer declares so the + // Structure validator doesn't reject rows on orphan required + // columns. Distinct from the payload-shape pass below, which + // strips extra fields off the incoming ROW documents. + $this->cleanupUpsertOrphansForScope($this->orphanScopeKey($database, $table)); /** * This is in case an attribute was deleted from Appwrite attributes collection but was not deleted from the table * When creating an archive we select * which will include orphan attribute from the schema @@ -1228,7 +1272,7 @@ class Appwrite extends Destination * `attributes` document on the related table keyed by twoWayKey. Dropping * only the parent leaves that child doc dangling and the recreate collides. */ - private function deleteAttributeCompletely( + private function dropAttributeForRecreate( UtopiaDocument $database, UtopiaDocument $table, Column|Attribute $resource, @@ -1251,26 +1295,224 @@ class Appwrite extends Destination if (empty($options['twoWay'])) { return; } - $twoWayKey = $options['twoWayKey'] ?? ''; + $twoWayKey = (string) ($options['twoWayKey'] ?? ''); if ($twoWayKey === '') { return; } + $this->dropTwoWayMirror($database, $relatedTable, $twoWayKey, $dbForDatabases); + } + + /** + * Drop the child-side `attributes` metadata doc + physical column that + * createField writes for two-way relationships. Shared by the DropAndRecreate + * path (pre-fetched $relatedTable) and the orphan cleanup path. + */ + private function dropTwoWayMirror( + UtopiaDocument $database, + UtopiaDocument $relatedTable, + string $twoWayKey, + UtopiaDatabase $dbForDatabases, + ): void { + $childCollectionId = 'database_' . $database->getSequence() . '_collection_' . $relatedTable->getSequence(); + $childMetaId = $database->getSequence() . '_' . $relatedTable->getSequence() . '_' . $twoWayKey; + + $this->tolerateMissing(fn () => $this->dbForProject->deleteDocument('attributes', $childMetaId)); + $this->tolerateMissing(fn () => $dbForDatabases->deleteAttribute($childCollectionId, $twoWayKey)); + $this->dbForProject->purgeCachedDocument('database_' . $database->getSequence(), $relatedTable->getId()); + $dbForDatabases->purgeCachedCollection($childCollectionId); + } + + /** + * Deterministic per-(database, table) key used to index the orphan + * tracker. Built from sequences so it's stable across calls but unique + * within the run. + */ + private function orphanScopeKey(UtopiaDocument $database, UtopiaDocument $table): string + { + return $database->getSequence() . ':' . $table->getSequence(); + } + + /** + * Records that $key was seen for this (database, table) during the run. + * $kind selects the tracker bucket ('attributeKeys' or 'indexKeys'). Only + * Upsert mode accumulates; Skip/Fail short-circuit. + */ + private function trackOrphanCandidate( + UtopiaDocument $database, + UtopiaDocument $table, + string $kind, + string $key, + UtopiaDatabase $dbForDatabases, + ): void { + if ($this->onDuplicate !== OnDuplicate::Upsert) { + return; + } + $scopeKey = $this->orphanScopeKey($database, $table); + if (!isset($this->orphanScopes[$scopeKey])) { + $this->orphanScopes[$scopeKey] = [ + 'database' => $database, + 'table' => $table, + 'dbForDatabases' => $dbForDatabases, + 'attributeKeys' => [], + 'indexKeys' => [], + ]; + } + $this->orphanScopes[$scopeKey][$kind][] = $key; + } + + /** + * End-of-migration sweep: cleans up any scope not already handled by a + * per-table cleanup in createRecord (i.e. tables that had no rows). + * Skipped if the migration failed before run() completed. + */ + private function cleanupUpsertOrphans(): void + { + foreach (\array_keys($this->orphanScopes) as $scopeKey) { + $this->cleanupUpsertOrphansForScope($scopeKey); + } + } + + /** + * Drops destination attributes/indexes whose keys weren't observed from + * source for this scope. Called per-table from createRecord before rows + * land so the Structure validator sees the post-cleanup schema. After + * running, the scope is removed from the tracker so the end-of-run + * sweep doesn't re-do the work. + */ + private function cleanupUpsertOrphansForScope(string $scopeKey): void + { + if ($this->onDuplicate !== OnDuplicate::Upsert) { + return; + } + if (!isset($this->orphanScopes[$scopeKey])) { + return; + } + + $scope = $this->orphanScopes[$scopeKey]; + $database = $scope['database']; + $table = $scope['table']; + $dbForDatabases = $scope['dbForDatabases']; + + $this->dropOrphansByKind( + 'attributes', + $scope['attributeKeys'], + $database, + $table, + fn (UtopiaDocument $doc) => $this->dropOrphanAttribute($database, $table, $doc, $dbForDatabases), + ); + + $this->dropOrphansByKind( + 'indexes', + $scope['indexKeys'], + $database, + $table, + fn (UtopiaDocument $doc) => $this->dropOrphanIndex( + $database, + $table, + (string) $doc->getAttribute('key'), + $dbForDatabases, + ), + ); + + unset($this->orphanScopes[$scopeKey]); + } + + /** + * Finds destination metadata docs in $metaCollection belonging to this + * (database, table) and invokes $drop for each one whose key isn't in + * $processedKeys. Shared by the attribute and index cleanup paths. + * + * @param list $processedKeys + * @param callable(UtopiaDocument): void $drop + */ + private function dropOrphansByKind( + string $metaCollection, + array $processedKeys, + UtopiaDocument $database, + UtopiaDocument $table, + callable $drop, + ): void { + $destDocs = $this->dbForProject->find($metaCollection, [ + Query::equal('databaseInternalId', [$database->getSequence()]), + Query::equal('collectionInternalId', [$table->getSequence()]), + Query::limit(PHP_INT_MAX), + ]); + foreach ($destDocs as $destDoc) { + if (!\in_array($destDoc->getAttribute('key'), $processedKeys, true)) { + $drop($destDoc); + } + } + } + + /** + * Drop an orphan attribute (metadata doc + physical column). Uses the + * destination's own metadata document as the source of truth for type + * and relationship options, since there's no source resource to consult. + */ + private function dropOrphanAttribute( + UtopiaDocument $database, + UtopiaDocument $table, + UtopiaDocument $attrDoc, + UtopiaDatabase $dbForDatabases, + ): void { + $key = (string) $attrDoc->getAttribute('key'); + $type = (string) $attrDoc->getAttribute('type'); + $options = $attrDoc->getAttribute('options', []); + $collectionId = 'database_' . $database->getSequence() . '_collection_' . $table->getSequence(); + + $this->tolerateMissing(fn () => $dbForDatabases->deleteAttribute($collectionId, $key)); + $this->tolerateMissing(fn () => $this->dbForProject->deleteDocument('attributes', $attrDoc->getId())); + $this->dbForProject->purgeCachedDocument('database_' . $database->getSequence(), $table->getId()); + $dbForDatabases->purgeCachedCollection($collectionId); + + if ($type !== UtopiaDatabase::VAR_RELATIONSHIP || empty($options['twoWay'])) { + return; + } + $twoWayKey = (string) ($options['twoWayKey'] ?? ''); + $relatedTableId = (string) ($options['relatedCollection'] ?? ''); + if ($twoWayKey === '' || $relatedTableId === '') { + return; + } + $relatedTable = $this->dbForProject->getDocument('database_' . $database->getSequence(), $relatedTableId); + if ($relatedTable->isEmpty()) { + return; + } + $childCollectionId = 'database_' . $database->getSequence() . '_collection_' . $relatedTable->getSequence(); $childMetaId = $database->getSequence() . '_' . $relatedTable->getSequence() . '_' . $twoWayKey; + $this->tolerateMissing(fn () => $this->dbForProject->deleteDocument('attributes', $childMetaId)); + $this->tolerateMissing(fn () => $dbForDatabases->deleteAttribute($childCollectionId, $twoWayKey)); + $this->dbForProject->purgeCachedDocument('database_' . $database->getSequence(), $relatedTable->getId()); + $dbForDatabases->purgeCachedCollection($childCollectionId); + } + private function dropOrphanIndex( + UtopiaDocument $database, + UtopiaDocument $table, + string $indexKey, + UtopiaDatabase $dbForDatabases, + ): void { + $collectionId = 'database_' . $database->getSequence() . '_collection_' . $table->getSequence(); + $indexMetaId = $database->getSequence() . '_' . $table->getSequence() . '_' . $indexKey; + + $this->tolerateMissing(fn () => $dbForDatabases->deleteIndex($collectionId, $indexKey)); + $this->tolerateMissing(fn () => $this->dbForProject->deleteDocument('indexes', $indexMetaId)); + $this->dbForProject->purgeCachedDocument('database_' . $database->getSequence(), $table->getId()); + } + + /** + * Swallows deletion errors — a prior interrupted run (or parent-side + * cascade via utopia-php/database relationship handling) may already + * have removed the target. + */ + private function tolerateMissing(callable $fn): void + { try { - $this->dbForProject->deleteDocument('attributes', $childMetaId); + $fn(); } catch (\Throwable) { // already gone } - try { - $dbForDatabases->deleteAttribute($childCollectionId, $twoWayKey); - } catch (\Throwable) { - // parent-side delete may have cascaded - } - $this->dbForProject->purgeCachedDocument('database_' . $database->getSequence(), $relatedTable->getId()); - $dbForDatabases->purgeCachedCollection($childCollectionId); } /** diff --git a/src/Migration/Destinations/OnDuplicate.php b/src/Migration/Destinations/OnDuplicate.php index 1c90ec679e..a40b50e12c 100644 --- a/src/Migration/Destinations/OnDuplicate.php +++ b/src/Migration/Destinations/OnDuplicate.php @@ -3,7 +3,10 @@ namespace Utopia\Migration\Destinations; /** - * Outcome of {@see OnDuplicate::resolveSchemaAction()}. + * Outcome of {@see OnDuplicate::resolveSchemaAction()}. Declared alongside + * OnDuplicate because the two are designed together — any code that uses + * SchemaAction necessarily imports OnDuplicate (as the source of the + * decision), so the shared file satisfies autoloading in practice. */ enum SchemaAction { @@ -20,11 +23,11 @@ enum OnDuplicate: string case Upsert = 'upsert'; /** - * @return array + * @return list */ public static function values(): array { - return \array_map(fn (self $case) => $case->value, self::cases()); + return \array_values(\array_map(fn (self $case) => $case->value, self::cases())); } /** @@ -36,8 +39,8 @@ enum OnDuplicate: string */ public function resolveSchemaAction( bool $exists, - string $sourceUpdatedAt = '', - string $destUpdatedAt = '', + ?string $sourceUpdatedAt = null, + ?string $destUpdatedAt = null, bool $canDrop = false, ): SchemaAction { if (!$exists) { @@ -54,10 +57,14 @@ enum OnDuplicate: string /** * strtotime() accepts '0000-00-00' leniently (returns a large negative - * epoch, not false), so reject non-positive epochs too. + * epoch, not false), so reject non-positive epochs too. Null/empty are + * treated as unknown → tolerate rather than risk a destructive drop. */ - private function sourceIsNewer(string $source, string $dest): bool + private function sourceIsNewer(?string $source, ?string $dest): bool { + if ($source === null || $source === '' || $dest === null || $dest === '') { + return false; + } $src = \strtotime($source); $dst = \strtotime($dest); if ($src === false || $dst === false || $src <= 0 || $dst <= 0) { diff --git a/tests/Migration/Unit/General/OnDuplicateTest.php b/tests/Migration/Unit/General/OnDuplicateTest.php index a4f57c0a2a..42ffa29661 100644 --- a/tests/Migration/Unit/General/OnDuplicateTest.php +++ b/tests/Migration/Unit/General/OnDuplicateTest.php @@ -139,8 +139,11 @@ class OnDuplicateTest extends TestCase { return [ 'both empty' => ['', ''], + 'both null' => [null, null], 'source empty' => ['', '2026-04-23T10:00:00.000+00:00'], 'dest empty' => ['2026-04-23T10:00:00.000+00:00', ''], + 'source null' => [null, '2026-04-23T10:00:00.000+00:00'], + 'dest null' => ['2026-04-23T10:00:00.000+00:00', null], 'source zero-date' => ['0000-00-00 00:00:00', '2026-04-23T10:00:00.000+00:00'], 'dest zero-date' => ['2026-04-23T10:00:00.000+00:00', '0000-00-00 00:00:00'], 'source garbage' => ['not-a-date', '2026-04-23T10:00:00.000+00:00'], @@ -149,7 +152,7 @@ class OnDuplicateTest extends TestCase } #[DataProvider('unparseableTimestampPairs')] - public function testUpsertUnparseableTimestampsTolerate(string $source, string $dest): void + public function testUpsertUnparseableTimestampsTolerate(?string $source, ?string $dest): void { // Conservative: unparseable timestamps preserve existing destination // rather than risk a destructive drop on garbage input. Any From c2b871519bbdaf7b3a2d947baa4e88a4b407c85d Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Fri, 24 Apr 2026 07:24:44 +0100 Subject: [PATCH 33/91] Rename orphan-tracker identifiers to 'table' vocabulary - $orphanScopes -> $orphansByTable - orphanScopeKey() -> tableIdentity() - cleanupUpsertOrphansForScope() -> cleanupUpsertOrphansForTable() - $scopeKey local -> $tableId - $scope local -> $tracked (what source declared for this table) No behavior change. The old names were consumer-oriented jargon; the new names name the actual unit (one entry per table). --- src/Migration/Destinations/Appwrite.php | 58 +++++++++++++------------ 1 file changed, 30 insertions(+), 28 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index 4dbf091f41..eff802d214 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -86,11 +86,13 @@ class Appwrite extends Destination private array $rowBuffer = []; /** - * Upsert-mode orphan tracking. For each (database, table) scope we saw - * during the migration, records the attribute + index keys that came - * from source plus the docs/handles needed to reach the destination. - * Scopes are removed from this map after their cleanup has run, so a - * final sweep at end-of-migration only visits tables that had no rows. + * Upsert-mode orphan tracking, keyed by (database, table). Each entry + * holds the attribute + index keys source declared for that table plus + * the docs/handles needed to reach the destination at cleanup time. + * Orphans are the complement: anything the destination has whose key + * is NOT in this record. Entries are removed from the map after their + * cleanup has run, so the final sweep at end-of-migration only visits + * tables that had no rows. * * @var array, * }> */ - private array $orphanScopes = []; + private array $orphansByTable = []; /** * @param string $project @@ -1213,7 +1215,7 @@ class Appwrite extends Destination // Structure validator doesn't reject rows on orphan required // columns. Distinct from the payload-shape pass below, which // strips extra fields off the incoming ROW documents. - $this->cleanupUpsertOrphansForScope($this->orphanScopeKey($database, $table)); + $this->cleanupUpsertOrphansForTable($this->tableIdentity($database, $table)); /** * This is in case an attribute was deleted from Appwrite attributes collection but was not deleted from the table * When creating an archive we select * which will include orphan attribute from the schema @@ -1325,10 +1327,10 @@ class Appwrite extends Destination /** * Deterministic per-(database, table) key used to index the orphan - * tracker. Built from sequences so it's stable across calls but unique - * within the run. + * tracker (`$orphansByTable`). Built from sequences so it's stable + * across calls but unique within the run. */ - private function orphanScopeKey(UtopiaDocument $database, UtopiaDocument $table): string + private function tableIdentity(UtopiaDocument $database, UtopiaDocument $table): string { return $database->getSequence() . ':' . $table->getSequence(); } @@ -1348,9 +1350,9 @@ class Appwrite extends Destination if ($this->onDuplicate !== OnDuplicate::Upsert) { return; } - $scopeKey = $this->orphanScopeKey($database, $table); - if (!isset($this->orphanScopes[$scopeKey])) { - $this->orphanScopes[$scopeKey] = [ + $tableId = $this->tableIdentity($database, $table); + if (!isset($this->orphansByTable[$tableId])) { + $this->orphansByTable[$tableId] = [ 'database' => $database, 'table' => $table, 'dbForDatabases' => $dbForDatabases, @@ -1358,45 +1360,45 @@ class Appwrite extends Destination 'indexKeys' => [], ]; } - $this->orphanScopes[$scopeKey][$kind][] = $key; + $this->orphansByTable[$tableId][$kind][] = $key; } /** - * End-of-migration sweep: cleans up any scope not already handled by a + * End-of-migration sweep: cleans up any table not already handled by a * per-table cleanup in createRecord (i.e. tables that had no rows). * Skipped if the migration failed before run() completed. */ private function cleanupUpsertOrphans(): void { - foreach (\array_keys($this->orphanScopes) as $scopeKey) { - $this->cleanupUpsertOrphansForScope($scopeKey); + foreach (\array_keys($this->orphansByTable) as $tableId) { + $this->cleanupUpsertOrphansForTable($tableId); } } /** * Drops destination attributes/indexes whose keys weren't observed from - * source for this scope. Called per-table from createRecord before rows + * source for this table. Called per-table from createRecord before rows * land so the Structure validator sees the post-cleanup schema. After - * running, the scope is removed from the tracker so the end-of-run + * running, the entry is removed from the tracker so the end-of-run * sweep doesn't re-do the work. */ - private function cleanupUpsertOrphansForScope(string $scopeKey): void + private function cleanupUpsertOrphansForTable(string $tableId): void { if ($this->onDuplicate !== OnDuplicate::Upsert) { return; } - if (!isset($this->orphanScopes[$scopeKey])) { + if (!isset($this->orphansByTable[$tableId])) { return; } - $scope = $this->orphanScopes[$scopeKey]; - $database = $scope['database']; - $table = $scope['table']; - $dbForDatabases = $scope['dbForDatabases']; + $tracked = $this->orphansByTable[$tableId]; + $database = $tracked['database']; + $table = $tracked['table']; + $dbForDatabases = $tracked['dbForDatabases']; $this->dropOrphansByKind( 'attributes', - $scope['attributeKeys'], + $tracked['attributeKeys'], $database, $table, fn (UtopiaDocument $doc) => $this->dropOrphanAttribute($database, $table, $doc, $dbForDatabases), @@ -1404,7 +1406,7 @@ class Appwrite extends Destination $this->dropOrphansByKind( 'indexes', - $scope['indexKeys'], + $tracked['indexKeys'], $database, $table, fn (UtopiaDocument $doc) => $this->dropOrphanIndex( @@ -1415,7 +1417,7 @@ class Appwrite extends Destination ), ); - unset($this->orphanScopes[$scopeKey]); + unset($this->orphansByTable[$tableId]); } /** From 791dbb16d713bf51901273ce3775fb321c83eab6 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Fri, 24 Apr 2026 07:57:57 +0100 Subject: [PATCH 34/91] Two-way relationships: track processed pairs, skip partner side MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Processing one side of a two-way relationship already reconciles both metadata docs and both physical columns (via createRelationship on Create/DropAndRecreate, or via the mirror in dropTwoWayMirror on DropAndRecreate). Re-processing the partner side would either waste work or — worse — drop the mirror after the partner table's rows already migrated, destroying relationship data. Track a canonical pair-key (sorted (table, key) tuples scoped to the database) as soon as createField finishes a two-way attribute. On the partner's second pass the check at the top of createField sees the pair in $processedTwoWayPairs and short-circuits with STATUS_SKIPPED. Covers the scenario where one side's source _updatedAt is newer than the other: whichever side is processed first wins; the partner is SKIPPED regardless of its own timestamp. Data safety preferred over honoring a second, potentially-divergent schema decision. --- src/Migration/Destinations/Appwrite.php | 65 +++++++++++++++++++++++++ 1 file changed, 65 insertions(+) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index eff802d214..62a5556306 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -104,6 +104,18 @@ class Appwrite extends Destination */ private array $orphansByTable = []; + /** + * Set of two-way relationship pair identities already reconciled during + * this run. Keyed by a canonical pair-key independent of which side is + * being processed. Used by createField to short-circuit the partner's + * second pass — the first side's action already reconciled both sides + * (Tolerate no-ops, DropAndRecreate drops + recreates both via + * dropTwoWayMirror + createRelationship). + * + * @var array + */ + private array $processedTwoWayPairs = []; + /** * @param string $project * @param string $endpoint @@ -745,6 +757,20 @@ class Appwrite extends Destination $this->trackOrphanCandidate($database, $table, 'attributeKeys', $resource->getKey(), $dbForDatabases); + // Two-way relationships have mirrored metadata + columns on both + // tables. Processing one side already reconciles both (Tolerate + // no-ops, DropAndRecreate drops + recreates both via + // dropTwoWayMirror + createRelationship). When the partner side + // comes through, skip it — re-processing would either double-drop + // (destroying row data on tables whose rows already migrated) or + // waste work. The first side always wins; subsequent partner is + // idempotent from the orchestrator's perspective. + $twoWayPairKey = $this->twoWayPairKey($database, $table, $resource, $type); + if ($twoWayPairKey !== null && isset($this->processedTwoWayPairs[$twoWayPairKey])) { + $resource->setStatus(Resource::STATUS_SKIPPED, 'Two-way partner already reconciled'); + return false; + } + $attributeMetaId = $database->getSequence() . '_' . $table->getSequence() . '_' . $resource->getKey(); if ($this->onDuplicate !== OnDuplicate::Fail) { $existingAttr = $this->dbForProject->getDocument('attributes', $attributeMetaId); @@ -759,6 +785,9 @@ class Appwrite extends Destination $this->dbForProject->purgeCachedDocument('database_' . $database->getSequence(), $table->getId()); $dbForDatabases->purgeCachedCollection('database_' . $database->getSequence() . '_collection_' . $table->getSequence()); $resource->setStatus(Resource::STATUS_SKIPPED, 'Already exists on destination'); + if ($twoWayPairKey !== null) { + $this->processedTwoWayPairs[$twoWayPairKey] = true; + } return false; } @@ -940,6 +969,10 @@ class Appwrite extends Destination $this->dbForProject->purgeCachedDocument('database_' . $database->getSequence(), $table->getId()); $dbForDatabases->purgeCachedCollection('database_' . $database->getSequence() . '_collection_' . $table->getSequence()); + if ($twoWayPairKey !== null) { + $this->processedTwoWayPairs[$twoWayPairKey] = true; + } + return true; } @@ -1335,6 +1368,38 @@ class Appwrite extends Destination return $database->getSequence() . ':' . $table->getSequence(); } + /** + * Canonical identity for a two-way relationship pair — same string + * regardless of which side (parent or child) is being processed. + * Returns null when the resource isn't a two-way relationship (no + * pair-level tracking needed). + */ + private function twoWayPairKey( + UtopiaDocument $database, + UtopiaDocument $table, + Column|Attribute $resource, + string $type, + ): ?string { + if ($type !== UtopiaDatabase::VAR_RELATIONSHIP) { + return null; + } + $options = $resource->getOptions(); + if (empty($options['twoWay'])) { + return null; + } + $twoWayKey = (string) ($options['twoWayKey'] ?? ''); + $relatedTableId = (string) ($options['relatedCollection'] ?? ''); + if ($twoWayKey === '' || $relatedTableId === '') { + return null; + } + + $thisSide = $table->getId() . '::' . $resource->getKey(); + $partnerSide = $relatedTableId . '::' . $twoWayKey; + $pair = [$thisSide, $partnerSide]; + \sort($pair); + return $database->getSequence() . '@' . \implode('<->', $pair); + } + /** * Records that $key was seen for this (database, table) during the run. * $kind selects the tracker bucket ('attributeKeys' or 'indexKeys'). Only From 6e6f8255fa52c8053fa2b9ad877c7797d93e32c5 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Fri, 24 Apr 2026 11:33:58 +0100 Subject: [PATCH 35/91] Relationships: route to UpdateInPlace, delete dead drop-mirror code MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Relationships can't take the DropAndRecreate path cleanly: - utopia's deleteAttribute throws for VAR_RELATIONSHIP - Two-way drops cascade to the partner table's physical column and destroy its row data (partner's rows migrated earlier in the run won't get re-migrated) Route relationships through SchemaAction::UpdateInPlace instead: - canDrop: !$isRelationship on resolveSchemaAction - New updateRelationshipInPlace() helper calls $dbForDatabases->updateRelationship() for the fields utopia supports (newTwoWayKey, twoWay, onDelete) + updateDocument() on Appwrite's application-level doc - relationType changes can't be updated in place and would silently diverge utopia's internal metadata from Appwrite's doc; throw a clear error asking the caller to drop+recreate manually Each side of a two-way is authoritative for its own Appwrite-level doc. utopia's updateRelationship cascades internal metadata on both sides in one call and is idempotent for same-target writes, so neither side's pass stomps the other. Dead-code cleanup: delete dropTwoWayMirror() and the relationship branch of dropAttributeForRecreate — both were only reachable from paths that no longer fire. Simplifies dropAttributeForRecreate signature (drops unused $type and $relatedTable params). Fix dropOrphanAttribute for relationship orphans: deleteAttribute throws for VAR_RELATIONSHIP, so use deleteRelationship which cascades both sides' physical columns + utopia metadata. Clean the two Appwrite-level docs separately. All 34 unit tests pass, pint + phpstan L3 clean. --- src/Migration/Destinations/Appwrite.php | 207 ++++++++++++------------ 1 file changed, 102 insertions(+), 105 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index 62a5556306..d4cf2db24e 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -104,18 +104,6 @@ class Appwrite extends Destination */ private array $orphansByTable = []; - /** - * Set of two-way relationship pair identities already reconciled during - * this run. Keyed by a canonical pair-key independent of which side is - * being processed. Used by createField to short-circuit the partner's - * second pass — the first side's action already reconciled both sides - * (Tolerate no-ops, DropAndRecreate drops + recreates both via - * dropTwoWayMirror + createRelationship). - * - * @var array - */ - private array $processedTwoWayPairs = []; - /** * @param string $project * @param string $endpoint @@ -757,19 +745,11 @@ class Appwrite extends Destination $this->trackOrphanCandidate($database, $table, 'attributeKeys', $resource->getKey(), $dbForDatabases); - // Two-way relationships have mirrored metadata + columns on both - // tables. Processing one side already reconciles both (Tolerate - // no-ops, DropAndRecreate drops + recreates both via - // dropTwoWayMirror + createRelationship). When the partner side - // comes through, skip it — re-processing would either double-drop - // (destroying row data on tables whose rows already migrated) or - // waste work. The first side always wins; subsequent partner is - // idempotent from the orchestrator's perspective. - $twoWayPairKey = $this->twoWayPairKey($database, $table, $resource, $type); - if ($twoWayPairKey !== null && isset($this->processedTwoWayPairs[$twoWayPairKey])) { - $resource->setStatus(Resource::STATUS_SKIPPED, 'Two-way partner already reconciled'); - return false; - } + // Relationships route to UpdateInPlace, not DropAndRecreate: + // utopia's deleteAttribute throws for VAR_RELATIONSHIP, and + // two-way drops would cascade to the partner table's physical + // column. Non-relationship attrs keep DropAndRecreate. + $isRelationship = $type === UtopiaDatabase::VAR_RELATIONSHIP; $attributeMetaId = $database->getSequence() . '_' . $table->getSequence() . '_' . $resource->getKey(); if ($this->onDuplicate !== OnDuplicate::Fail) { @@ -778,28 +758,31 @@ class Appwrite extends Destination !$existingAttr->isEmpty(), $updatedAt, $existingAttr->getUpdatedAt(), - canDrop: true, + canDrop: !$isRelationship, ); if ($action === SchemaAction::Tolerate) { $this->dbForProject->purgeCachedDocument('database_' . $database->getSequence(), $table->getId()); $dbForDatabases->purgeCachedCollection('database_' . $database->getSequence() . '_collection_' . $table->getSequence()); $resource->setStatus(Resource::STATUS_SKIPPED, 'Already exists on destination'); - if ($twoWayPairKey !== null) { - $this->processedTwoWayPairs[$twoWayPairKey] = true; - } return false; } - if ($action === SchemaAction::DropAndRecreate) { - $this->dropAttributeForRecreate( + if ($action === SchemaAction::UpdateInPlace) { + $this->updateRelationshipInPlace( $database, $table, $resource, $type, - $relatedTable ?? null, + $updatedAt, + $existingAttr, $dbForDatabases, ); + return true; + } + + if ($action === SchemaAction::DropAndRecreate) { + $this->dropAttributeForRecreate($database, $table, $resource, $dbForDatabases); } } @@ -969,10 +952,6 @@ class Appwrite extends Destination $this->dbForProject->purgeCachedDocument('database_' . $database->getSequence(), $table->getId()); $dbForDatabases->purgeCachedCollection('database_' . $database->getSequence() . '_collection_' . $table->getSequence()); - if ($twoWayPairKey !== null) { - $this->processedTwoWayPairs[$twoWayPairKey] = true; - } - return true; } @@ -1301,18 +1280,16 @@ class Appwrite extends Destination } /** - * Drop an attribute (metadata doc + physical column) so it can be recreated. - * - * Two-way relationships require mirroring: createField writes a second - * `attributes` document on the related table keyed by twoWayKey. Dropping - * only the parent leaves that child doc dangling and the recreate collides. + * Drop a non-relationship attribute (metadata doc + physical column) so + * it can be recreated. Not used for relationships — those route through + * UpdateInPlace since utopia's deleteAttribute throws for VAR_RELATIONSHIP + * and dropping a relationship column would cascade data loss to the + * partner table's rows. */ private function dropAttributeForRecreate( UtopiaDocument $database, UtopiaDocument $table, Column|Attribute $resource, - string $type, - ?UtopiaDocument $relatedTable, UtopiaDatabase $dbForDatabases, ): void { $collectionId = 'database_' . $database->getSequence() . '_collection_' . $table->getSequence(); @@ -1322,40 +1299,79 @@ class Appwrite extends Destination $this->dbForProject->deleteDocument('attributes', $attributeMetaId); $this->dbForProject->purgeCachedDocument('database_' . $database->getSequence(), $table->getId()); $dbForDatabases->purgeCachedCollection($collectionId); - - if ($type !== UtopiaDatabase::VAR_RELATIONSHIP || $relatedTable === null) { - return; - } - $options = $resource->getOptions(); - if (empty($options['twoWay'])) { - return; - } - $twoWayKey = (string) ($options['twoWayKey'] ?? ''); - if ($twoWayKey === '') { - return; - } - - $this->dropTwoWayMirror($database, $relatedTable, $twoWayKey, $dbForDatabases); } /** - * Drop the child-side `attributes` metadata doc + physical column that - * createField writes for two-way relationships. Shared by the DropAndRecreate - * path (pre-fetched $relatedTable) and the orphan cleanup path. + * Reconcile a relationship attribute's metadata on destination without + * dropping its physical column — keeps row data intact. + * + * Two layers must stay in sync: utopia-php/database's internal + * `_metadata` collection (used for row validation) and Appwrite's + * application-level `attributes` doc (used by the Appwrite API). Each + * side's own pass is authoritative for its own Appwrite-level doc; + * utopia's updateRelationship cascades internal metadata on both sides + * in one call and is idempotent across passes for same-target writes. + * + * relationType changes aren't supported by updateRelationship (they'd + * require a physical schema change). Fail fast rather than silently + * diverge utopia's view from Appwrite's view. */ - private function dropTwoWayMirror( + private function updateRelationshipInPlace( UtopiaDocument $database, - UtopiaDocument $relatedTable, - string $twoWayKey, + UtopiaDocument $table, + Column|Attribute $resource, + string $type, + string $updatedAt, + UtopiaDocument $existingAttr, UtopiaDatabase $dbForDatabases, ): void { - $childCollectionId = 'database_' . $database->getSequence() . '_collection_' . $relatedTable->getSequence(); - $childMetaId = $database->getSequence() . '_' . $relatedTable->getSequence() . '_' . $twoWayKey; + $collectionId = 'database_' . $database->getSequence() . '_collection_' . $table->getSequence(); + $sourceOptions = $resource->getOptions(); + $destOptions = $existingAttr->getAttribute('options', []); - $this->tolerateMissing(fn () => $this->dbForProject->deleteDocument('attributes', $childMetaId)); - $this->tolerateMissing(fn () => $dbForDatabases->deleteAttribute($childCollectionId, $twoWayKey)); - $this->dbForProject->purgeCachedDocument('database_' . $database->getSequence(), $relatedTable->getId()); - $dbForDatabases->purgeCachedCollection($childCollectionId); + if ( + isset($sourceOptions['relationType'], $destOptions['relationType']) + && $sourceOptions['relationType'] !== $destOptions['relationType'] + ) { + throw new Exception( + resourceName: $resource->getName(), + resourceGroup: $resource->getGroup(), + resourceId: $resource->getId(), + message: 'Changing relationType on a migrated relationship is not supported; drop and recreate the relationship on the destination manually before re-running the migration.', + ); + } + + $dbForDatabases->updateRelationship( + collection: $collectionId, + id: $resource->getKey(), + newTwoWayKey: ($sourceOptions['twoWayKey'] ?? null) !== ($destOptions['twoWayKey'] ?? null) + ? (string) ($sourceOptions['twoWayKey'] ?? '') + : null, + twoWay: ($sourceOptions['twoWay'] ?? null) !== ($destOptions['twoWay'] ?? null) + ? (bool) ($sourceOptions['twoWay'] ?? false) + : null, + onDelete: ($sourceOptions['onDelete'] ?? null) !== ($destOptions['onDelete'] ?? null) + ? (string) ($sourceOptions['onDelete'] ?? '') + : null, + ); + + $this->dbForProject->updateDocument('attributes', $existingAttr->getId(), new UtopiaDocument([ + 'key' => $resource->getKey(), + 'type' => $type, + 'size' => $resource->getSize(), + 'required' => $resource->isRequired(), + 'signed' => $resource->isSigned(), + 'default' => $resource->getDefault(), + 'array' => $resource->isArray(), + 'format' => $resource->getFormat(), + 'formatOptions' => $resource->getFormatOptions(), + 'filters' => $resource->getFilters(), + 'options' => $sourceOptions, + '$updatedAt' => $updatedAt, + ])); + + $this->dbForProject->purgeCachedDocument('database_' . $database->getSequence(), $table->getId()); + $dbForDatabases->purgeCachedCollection($collectionId); } /** @@ -1368,38 +1384,6 @@ class Appwrite extends Destination return $database->getSequence() . ':' . $table->getSequence(); } - /** - * Canonical identity for a two-way relationship pair — same string - * regardless of which side (parent or child) is being processed. - * Returns null when the resource isn't a two-way relationship (no - * pair-level tracking needed). - */ - private function twoWayPairKey( - UtopiaDocument $database, - UtopiaDocument $table, - Column|Attribute $resource, - string $type, - ): ?string { - if ($type !== UtopiaDatabase::VAR_RELATIONSHIP) { - return null; - } - $options = $resource->getOptions(); - if (empty($options['twoWay'])) { - return null; - } - $twoWayKey = (string) ($options['twoWayKey'] ?? ''); - $relatedTableId = (string) ($options['relatedCollection'] ?? ''); - if ($twoWayKey === '' || $relatedTableId === '') { - return null; - } - - $thisSide = $table->getId() . '::' . $resource->getKey(); - $partnerSide = $relatedTableId . '::' . $twoWayKey; - $pair = [$thisSide, $partnerSide]; - \sort($pair); - return $database->getSequence() . '@' . \implode('<->', $pair); - } - /** * Records that $key was seen for this (database, table) during the run. * $kind selects the tracker bucket ('attributeKeys' or 'indexKeys'). Only @@ -1516,6 +1500,12 @@ class Appwrite extends Destination * Drop an orphan attribute (metadata doc + physical column). Uses the * destination's own metadata document as the source of truth for type * and relationship options, since there's no source resource to consult. + * + * Relationships use deleteRelationship (which cascades to both sides's + * physical columns + utopia's internal metadata) rather than + * deleteAttribute (which throws for relationship types). Appwrite's + * application-level `attributes` metadata docs on both sides are + * cleaned separately. */ private function dropOrphanAttribute( UtopiaDocument $database, @@ -1528,7 +1518,11 @@ class Appwrite extends Destination $options = $attrDoc->getAttribute('options', []); $collectionId = 'database_' . $database->getSequence() . '_collection_' . $table->getSequence(); - $this->tolerateMissing(fn () => $dbForDatabases->deleteAttribute($collectionId, $key)); + if ($type === UtopiaDatabase::VAR_RELATIONSHIP) { + $this->tolerateMissing(fn () => $dbForDatabases->deleteRelationship($collectionId, $key)); + } else { + $this->tolerateMissing(fn () => $dbForDatabases->deleteAttribute($collectionId, $key)); + } $this->tolerateMissing(fn () => $this->dbForProject->deleteDocument('attributes', $attrDoc->getId())); $this->dbForProject->purgeCachedDocument('database_' . $database->getSequence(), $table->getId()); $dbForDatabases->purgeCachedCollection($collectionId); @@ -1546,12 +1540,15 @@ class Appwrite extends Destination return; } - $childCollectionId = 'database_' . $database->getSequence() . '_collection_' . $relatedTable->getSequence(); + // Physical column on the related table was already dropped by + // deleteRelationship above. Only the Appwrite-level metadata doc + // remains to clean up. $childMetaId = $database->getSequence() . '_' . $relatedTable->getSequence() . '_' . $twoWayKey; $this->tolerateMissing(fn () => $this->dbForProject->deleteDocument('attributes', $childMetaId)); - $this->tolerateMissing(fn () => $dbForDatabases->deleteAttribute($childCollectionId, $twoWayKey)); $this->dbForProject->purgeCachedDocument('database_' . $database->getSequence(), $relatedTable->getId()); - $dbForDatabases->purgeCachedCollection($childCollectionId); + $dbForDatabases->purgeCachedCollection( + 'database_' . $database->getSequence() . '_collection_' . $relatedTable->getSequence(), + ); } private function dropOrphanIndex( From 786a27b596c5f67174f8649ea4ff7cb45720d0b7 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Mon, 27 Apr 2026 07:39:40 +0100 Subject: [PATCH 36/91] Schema reconciliation: createdAt-aware actions + SDK-aligned in-place updates MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit resolveSchemaAction now distinguishes 'source resource was deleted+ recreated' (createdAt diff) from 'source resource was edited' (updatedAt-newer with createdAt unchanged). The first triggers DropAndRecreate; the second triggers UpdateInPlace. Containers (databases, tables) get UpdateInPlace in both cases (canDrop=false) since dropping would cascade child loss. UpdateInPlace is now SDK-aligned. New helpers updateAttributeInPlace (non-relationships) and refactored updateRelationshipInPlace return bool: true if the source change maps to an SDK updateXAttribute endpoint (required, default, size, min/max, elements, newKey, onDelete), false to fall through to DropAndRecreate. Non-SDK fields (type, array, signed, format, formatOptions, filters) and structural relationship changes (relationType, twoWay toggle, twoWayKey, relatedCollection) automatically route to drop+recreate. Both relationship types (one-way and two-way) now use deleteRelationship on the DropAndRecreate path. One-way is a clean drop (no partner data to lose). Two-way drops both columns; partner row data is restored by the subsequent Upsert row pass. canDrop on attributes is now uniformly true. Indexes have no SDK in-place primitive, so UpdateInPlace consults indexSpecMatches: matching specs tolerate (filters phantom updatedAt drift), differing specs drop and recreate. Maintainability passes: extracted databaseCollectionId, tableCollectionId, attributeIndexMetaId, purgeTableCaches, arraysDifferOnKeys helpers. SDK-boundary fields lifted to ATTRIBUTE_NON_SDK_FIELDS and RELATIONSHIP_STRUCTURAL_FIELDS class constants — single point of change when SDK adds new endpoints. Test matrix expanded: createdAt diff × canDrop × mode × unparseable timestamp combinations. --- src/Migration/Destinations/Appwrite.php | 437 +++++++++++++----- src/Migration/Destinations/OnDuplicate.php | 63 ++- .../Unit/General/OnDuplicateTest.php | 212 ++++++--- 3 files changed, 516 insertions(+), 196 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index d4cf2db24e..62166ab781 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -63,6 +63,33 @@ use Utopia\Migration\Transfer; class Appwrite extends Destination { + /** + * Attribute fields not reachable via Appwrite SDK's per-type + * updateXAttribute endpoints. Source-side changes to any of these force + * DropAndRecreate because no in-place SDK call can express the change. + * Update if the SDK adds new endpoints (e.g. `array` toggle). + */ + private const ATTRIBUTE_NON_SDK_FIELDS = [ + 'type', + 'array', + 'signed', + 'format', + 'formatOptions', + 'filters', + ]; + + /** + * Relationship `options` fields the SDK's updateRelationshipAttribute + * does not expose (it allows only `onDelete` and `newKey`). Any change + * here is a structural relationship swap that requires drop+recreate. + */ + private const RELATIONSHIP_STRUCTURAL_FIELDS = [ + 'relationType', + 'twoWay', + 'twoWayKey', + 'relatedCollection', + ]; + protected Client $client; protected string $project; @@ -462,8 +489,12 @@ class Appwrite extends Destination $existing = $this->dbForProject->getDocument('databases', $resource->getId()); $action = $this->onDuplicate->resolveSchemaAction( !$existing->isEmpty(), + $createdAt, + $existing->getCreatedAt(), $updatedAt, $existing->getUpdatedAt(), + // Containers (databases) can't be dropped — children would be lost. + canDrop: false, ); if ($action === SchemaAction::Tolerate) { @@ -513,7 +544,7 @@ class Appwrite extends Destination ); $this->dbForProject->createCollection( - 'database_' . $database->getSequence(), + $this->databaseCollectionId($database), $columns, $indexes ); @@ -570,13 +601,17 @@ class Appwrite extends Destination if ($this->onDuplicate !== OnDuplicate::Fail) { $existing = $this->dbForProject->getDocument( - 'database_' . $database->getSequence(), + $this->databaseCollectionId($database), $resource->getId() ); $action = $this->onDuplicate->resolveSchemaAction( !$existing->isEmpty(), + $createdAt, + $existing->getCreatedAt(), $updatedAt, $existing->getUpdatedAt(), + // Containers (tables) can't be dropped — children would be lost. + canDrop: false, ); if ($action === SchemaAction::Tolerate) { @@ -587,7 +622,7 @@ class Appwrite extends Destination if ($action === SchemaAction::UpdateInPlace) { $this->dbForProject->updateDocument( - 'database_' . $database->getSequence(), + $this->databaseCollectionId($database), $existing->getId(), new UtopiaDocument([ 'name' => $resource->getTableName(), @@ -603,7 +638,7 @@ class Appwrite extends Destination } } - $table = $this->dbForProject->createDocument('database_' . $database->getSequence(), new UtopiaDocument([ + $table = $this->dbForProject->createDocument($this->databaseCollectionId($database), new UtopiaDocument([ '$id' => $resource->getId(), 'databaseInternalId' => $database->getSequence(), 'databaseId' => $resource->getDatabase()->getId(), @@ -619,7 +654,7 @@ class Appwrite extends Destination $resource->setSequence($table->getSequence()); $dbForDatabases->createCollection( - 'database_' . $database->getSequence() . '_collection_' . $resource->getSequence(), + $this->tableCollectionId($database, $table), permissions: $resource->getPermissions(), documentSecurity: $resource->getRowSecurity() ); @@ -681,7 +716,7 @@ class Appwrite extends Destination } $table = $this->dbForProject->getDocument( - 'database_' . $database->getSequence(), + $this->databaseCollectionId($database), $resource->getTable()->getId(), ); @@ -726,7 +761,7 @@ class Appwrite extends Destination if ($type === UtopiaDatabase::VAR_RELATIONSHIP) { $resource->getOptions()['side'] = UtopiaDatabase::RELATION_SIDE_PARENT; $relatedTable = $this->dbForProject->getDocument( - 'database_' . $database->getSequence(), + $this->databaseCollectionId($database), $resource->getOptions()['relatedCollection'] ); if ($relatedTable->isEmpty()) { @@ -745,10 +780,10 @@ class Appwrite extends Destination $this->trackOrphanCandidate($database, $table, 'attributeKeys', $resource->getKey(), $dbForDatabases); - // Relationships route to UpdateInPlace, not DropAndRecreate: - // utopia's deleteAttribute throws for VAR_RELATIONSHIP, and - // two-way drops would cascade to the partner table's physical - // column. Non-relationship attrs keep DropAndRecreate. + // Both relationship types use deleteRelationship (not deleteAttribute, + // which throws for VAR_RELATIONSHIP). One-way: clean drop. Two-way: + // drops both columns; partner row data is restored by the subsequent + // Upsert row pass. $isRelationship = $type === UtopiaDatabase::VAR_RELATIONSHIP; $attributeMetaId = $database->getSequence() . '_' . $table->getSequence() . '_' . $resource->getKey(); @@ -756,32 +791,34 @@ class Appwrite extends Destination $existingAttr = $this->dbForProject->getDocument('attributes', $attributeMetaId); $action = $this->onDuplicate->resolveSchemaAction( !$existingAttr->isEmpty(), + $createdAt, + $existingAttr->getCreatedAt(), $updatedAt, $existingAttr->getUpdatedAt(), - canDrop: !$isRelationship, + canDrop: true, ); if ($action === SchemaAction::Tolerate) { - $this->dbForProject->purgeCachedDocument('database_' . $database->getSequence(), $table->getId()); - $dbForDatabases->purgeCachedCollection('database_' . $database->getSequence() . '_collection_' . $table->getSequence()); + $this->purgeTableCaches($database, $table, $dbForDatabases); $resource->setStatus(Resource::STATUS_SKIPPED, 'Already exists on destination'); return false; } + // UpdateInPlace tries an SDK-equivalent update first; returns + // false if the source change isn't expressible in place (see + // ATTRIBUTE_NON_SDK_FIELDS / RELATIONSHIP_STRUCTURAL_FIELDS). + // Falls through to DropAndRecreate in that case. if ($action === SchemaAction::UpdateInPlace) { - $this->updateRelationshipInPlace( - $database, - $table, - $resource, - $type, - $updatedAt, - $existingAttr, - $dbForDatabases, - ); - return true; + $applied = $isRelationship + ? $this->updateRelationshipInPlace($database, $table, $resource, $type, $updatedAt, $existingAttr, $dbForDatabases) + : $this->updateAttributeInPlace($database, $table, $resource, $type, $updatedAt, $existingAttr, $dbForDatabases); + + if ($applied) { + return true; + } } - if ($action === SchemaAction::DropAndRecreate) { + if ($action === SchemaAction::DropAndRecreate || $action === SchemaAction::UpdateInPlace) { $this->dropAttributeForRecreate($database, $table, $resource, $dbForDatabases); } } @@ -827,13 +864,11 @@ class Appwrite extends Destination message: 'Attribute limit exceeded', ); } catch (\Throwable $e) { - $this->dbForProject->purgeCachedDocument('database_' . $database->getSequence(), $table->getId()); - $dbForDatabases->purgeCachedCollection('database_' . $database->getSequence() . '_collection_' . $table->getSequence()); + $this->purgeTableCaches($database, $table, $dbForDatabases); throw $e; } - $this->dbForProject->purgeCachedDocument('database_' . $database->getSequence(), $table->getId()); - $dbForDatabases->purgeCachedCollection('database_' . $database->getSequence() . '_collection_' . $table->getSequence()); + $this->purgeTableCaches($database, $table, $dbForDatabases); $options = $resource->getOptions(); $twoWayKey = null; @@ -887,8 +922,7 @@ class Appwrite extends Destination message: 'Column limit exceeded', ); } catch (\Throwable $e) { - $this->dbForProject->purgeCachedDocument('database_' . $database->getSequence(), $relatedTable->getId()); - $dbForDatabases->purgeCachedCollection('database_' . $database->getSequence() . '_collection_' . $relatedTable->getSequence()); + $this->purgeTableCaches($database, $relatedTable, $dbForDatabases); throw $e; } } @@ -897,8 +931,8 @@ class Appwrite extends Destination switch ($type) { case UtopiaDatabase::VAR_RELATIONSHIP: if (!$dbForDatabases->createRelationship( - collection: 'database_' . $database->getSequence() . '_collection_' . $table->getSequence(), - relatedCollection: 'database_' . $database->getSequence() . '_collection_' . $relatedTable->getSequence(), + collection: $this->tableCollectionId($database, $table), + relatedCollection: $this->tableCollectionId($database, $relatedTable), type: $options['relationType'], twoWay: $options['twoWay'], id: $resource->getKey(), @@ -915,7 +949,7 @@ class Appwrite extends Destination break; default: if (!$dbForDatabases->createAttribute( - 'database_' . $database->getSequence() . '_collection_' . $table->getSequence(), + $this->tableCollectionId($database, $table), $resource->getKey(), $type, $resource->getSize(), @@ -946,11 +980,10 @@ class Appwrite extends Destination } if ($type === UtopiaDatabase::VAR_RELATIONSHIP && $options['twoWay']) { - $this->dbForProject->purgeCachedDocument('database_' . $database->getSequence(), $relatedTable->getId()); + $this->dbForProject->purgeCachedDocument($this->databaseCollectionId($database), $relatedTable->getId()); } - $this->dbForProject->purgeCachedDocument('database_' . $database->getSequence(), $table->getId()); - $dbForDatabases->purgeCachedCollection('database_' . $database->getSequence() . '_collection_' . $table->getSequence()); + $this->purgeTableCaches($database, $table, $dbForDatabases); return true; } @@ -975,7 +1008,7 @@ class Appwrite extends Destination } $table = $this->dbForProject->getDocument( - 'database_' . $database->getSequence(), + $this->databaseCollectionId($database), $resource->getTable()->getId(), ); if ($table->isEmpty()) { @@ -1066,35 +1099,40 @@ class Appwrite extends Destination ); } - $indexMetaId = $database->getSequence() . '_' . $table->getSequence() . '_' . $resource->getKey(); + $indexMetaId = $this->attributeIndexMetaId($database, $table, $resource->getKey()); if ($this->onDuplicate !== OnDuplicate::Fail) { $existingIdx = $this->dbForProject->getDocument('indexes', $indexMetaId); $action = $this->onDuplicate->resolveSchemaAction( !$existingIdx->isEmpty(), + $createdAt, + $existingIdx->getCreatedAt(), $updatedAt, $existingIdx->getUpdatedAt(), canDrop: true, ); if ($action === SchemaAction::Tolerate) { - $this->dbForProject->purgeCachedDocument( - 'database_' . $database->getSequence(), - $table->getId() - ); + $this->dbForProject->purgeCachedDocument($this->databaseCollectionId($database), $table->getId()); $resource->setStatus(Resource::STATUS_SKIPPED, 'Already exists on destination'); return false; } - if ($action === SchemaAction::DropAndRecreate) { - $dbForDatabases->deleteIndex( - 'database_' . $database->getSequence() . '_collection_' . $table->getSequence(), - $resource->getKey() - ); + // Indexes have no SDK in-place update — utopia provides no + // updateIndex primitive, and the underlying DB requires drop+ + // recreate for any structural change. UpdateInPlace from + // resolveSchemaAction (createdAt-same + updatedAt-newer) is + // treated as a possibly-phantom edit; if the spec actually + // matches existing, tolerate; otherwise drop and recreate. + if ($action === SchemaAction::UpdateInPlace && $this->indexSpecMatches($existingIdx, $resource)) { + $this->dbForProject->purgeCachedDocument($this->databaseCollectionId($database), $table->getId()); + $resource->setStatus(Resource::STATUS_SKIPPED, 'Index spec unchanged'); + return false; + } + + if ($action === SchemaAction::DropAndRecreate || $action === SchemaAction::UpdateInPlace) { + $dbForDatabases->deleteIndex($this->tableCollectionId($database, $table), $resource->getKey()); $this->dbForProject->deleteDocument('indexes', $indexMetaId); - $this->dbForProject->purgeCachedDocument( - 'database_' . $database->getSequence(), - $table->getId() - ); + $this->dbForProject->purgeCachedDocument($this->databaseCollectionId($database), $table->getId()); } } @@ -1102,7 +1140,7 @@ class Appwrite extends Destination try { $result = $dbForDatabases->createIndex( - 'database_' . $database->getSequence() . '_collection_' . $table->getSequence(), + $this->tableCollectionId($database, $table), $resource->getKey(), $resource->getType(), $resource->getColumns(), @@ -1129,10 +1167,7 @@ class Appwrite extends Destination ); } - $this->dbForProject->purgeCachedDocument( - 'database_' . $database->getSequence(), - $table->getId() - ); + $this->dbForProject->purgeCachedDocument($this->databaseCollectionId($database), $table->getId()); return true; } @@ -1214,7 +1249,7 @@ class Appwrite extends Destination ); $table = $this->dbForProject->getDocument( - 'database_' . $database->getSequence(), + $this->databaseCollectionId($database), $resource->getTable()->getId(), ); @@ -1280,11 +1315,14 @@ class Appwrite extends Destination } /** - * Drop a non-relationship attribute (metadata doc + physical column) so - * it can be recreated. Not used for relationships — those route through - * UpdateInPlace since utopia's deleteAttribute throws for VAR_RELATIONSHIP - * and dropping a relationship column would cascade data loss to the - * partner table's rows. + * Drop an attribute (metadata doc + physical column) so it can be recreated. + * + * Branches by type because utopia's deleteAttribute throws for relationships; + * relationships use deleteRelationship, which handles both one-way (partner + * cleanup is a silent no-op since no partner attribute exists) and two-way + * (partner attribute and physical column both removed). For two-way, the + * partner-side Appwrite-level meta doc is also deleted here since + * deleteRelationship only touches utopia's internal metadata. */ private function dropAttributeForRecreate( UtopiaDocument $database, @@ -1292,31 +1330,49 @@ class Appwrite extends Destination Column|Attribute $resource, UtopiaDatabase $dbForDatabases, ): void { - $collectionId = 'database_' . $database->getSequence() . '_collection_' . $table->getSequence(); + $collectionId = $this->tableCollectionId($database, $table); $attributeMetaId = $database->getSequence() . '_' . $table->getSequence() . '_' . $resource->getKey(); + $isRelationship = $resource->getType() === Column::TYPE_RELATIONSHIP; + + if ($isRelationship) { + $dbForDatabases->deleteRelationship($collectionId, $resource->getKey()); + } else { + $dbForDatabases->deleteAttribute($collectionId, $resource->getKey()); + } - $dbForDatabases->deleteAttribute($collectionId, $resource->getKey()); $this->dbForProject->deleteDocument('attributes', $attributeMetaId); - $this->dbForProject->purgeCachedDocument('database_' . $database->getSequence(), $table->getId()); - $dbForDatabases->purgeCachedCollection($collectionId); + + // For two-way relationships, also remove the partner-side Appwrite meta + // doc — deleteRelationship only touches utopia's internal _metadata. + if ($isRelationship && ($resource->getOptions()['twoWay'] ?? false)) { + $relatedTableId = $resource->getOptions()['relatedCollection'] ?? null; + $twoWayKey = $resource->getOptions()['twoWayKey'] ?? null; + if ($relatedTableId !== null && $twoWayKey !== null) { + $relatedTable = $this->dbForProject->getDocument( + $this->databaseCollectionId($database), + $relatedTableId, + ); + if (!$relatedTable->isEmpty()) { + $partnerMetaId = $this->attributeIndexMetaId($database, $relatedTable, $twoWayKey); + $this->tolerateMissing(fn () => $this->dbForProject->deleteDocument('attributes', $partnerMetaId)); + } + } + } + + $this->purgeTableCaches($database, $table, $dbForDatabases); } /** - * Reconcile a relationship attribute's metadata on destination without - * dropping its physical column — keeps row data intact. + * Apply an SDK-equivalent in-place update for a non-relationship attribute. + * Returns true if applied, false if the source spec changed in a way the + * SDK can't update in place — caller falls through to DropAndRecreate. * - * Two layers must stay in sync: utopia-php/database's internal - * `_metadata` collection (used for row validation) and Appwrite's - * application-level `attributes` doc (used by the Appwrite API). Each - * side's own pass is authoritative for its own Appwrite-level doc; - * utopia's updateRelationship cascades internal metadata on both sides - * in one call and is idempotent across passes for same-target writes. - * - * relationType changes aren't supported by updateRelationship (they'd - * require a physical schema change). Fail fast rather than silently - * diverge utopia's view from Appwrite's view. + * SDK-updatable per `updateXAttribute` endpoints: required, default, size + * (string/varchar), min/max (integer/float), elements (enum), newKey rename. + * Anything else (type, array, signed, format, formatOptions, filters) + * requires drop+recreate and returns false. */ - private function updateRelationshipInPlace( + private function updateAttributeInPlace( UtopiaDocument $database, UtopiaDocument $table, Column|Attribute $resource, @@ -1324,35 +1380,40 @@ class Appwrite extends Destination string $updatedAt, UtopiaDocument $existingAttr, UtopiaDatabase $dbForDatabases, - ): void { - $collectionId = 'database_' . $database->getSequence() . '_collection_' . $table->getSequence(); - $sourceOptions = $resource->getOptions(); - $destOptions = $existingAttr->getAttribute('options', []); + ): bool { + $sourceFields = [ + 'type' => $type, + 'array' => $resource->isArray(), + 'signed' => $resource->isSigned(), + 'format' => $resource->getFormat(), + 'formatOptions' => $resource->getFormatOptions(), + 'filters' => $resource->getFilters(), + ]; - if ( - isset($sourceOptions['relationType'], $destOptions['relationType']) - && $sourceOptions['relationType'] !== $destOptions['relationType'] - ) { - throw new Exception( - resourceName: $resource->getName(), - resourceGroup: $resource->getGroup(), - resourceId: $resource->getId(), - message: 'Changing relationType on a migrated relationship is not supported; drop and recreate the relationship on the destination manually before re-running the migration.', - ); + $existingFields = []; + foreach (self::ATTRIBUTE_NON_SDK_FIELDS as $field) { + $existingFields[$field] = $existingAttr->getAttribute($field); } - $dbForDatabases->updateRelationship( - collection: $collectionId, + if ($this->arraysDifferOnKeys($sourceFields, $existingFields, self::ATTRIBUTE_NON_SDK_FIELDS)) { + return false; + } + + // Apply the SDK-updatable subset via utopia. Pass existing values for + // non-SDK fields explicitly so utopia doesn't trigger an ALTER for + // fields that haven't changed. + $dbForDatabases->updateAttribute( + collection: $this->tableCollectionId($database, $table), id: $resource->getKey(), - newTwoWayKey: ($sourceOptions['twoWayKey'] ?? null) !== ($destOptions['twoWayKey'] ?? null) - ? (string) ($sourceOptions['twoWayKey'] ?? '') - : null, - twoWay: ($sourceOptions['twoWay'] ?? null) !== ($destOptions['twoWay'] ?? null) - ? (bool) ($sourceOptions['twoWay'] ?? false) - : null, - onDelete: ($sourceOptions['onDelete'] ?? null) !== ($destOptions['onDelete'] ?? null) - ? (string) ($sourceOptions['onDelete'] ?? '') - : null, + type: $type, + size: $resource->getSize(), + required: $resource->isRequired(), + default: $resource->getDefault(), + signed: $existingAttr->getAttribute('signed'), + array: $existingAttr->getAttribute('array'), + format: $resource->getFormat(), + formatOptions: $resource->getFormatOptions(), + filters: $existingAttr->getAttribute('filters'), ); $this->dbForProject->updateDocument('attributes', $existingAttr->getId(), new UtopiaDocument([ @@ -1366,12 +1427,91 @@ class Appwrite extends Destination 'format' => $resource->getFormat(), 'formatOptions' => $resource->getFormatOptions(), 'filters' => $resource->getFilters(), - 'options' => $sourceOptions, '$updatedAt' => $updatedAt, ])); - $this->dbForProject->purgeCachedDocument('database_' . $database->getSequence(), $table->getId()); - $dbForDatabases->purgeCachedCollection($collectionId); + $this->purgeTableCaches($database, $table, $dbForDatabases); + return true; + } + + /** + * Apply an SDK-equivalent in-place update for a relationship attribute. + * Returns true if applied, false if the source spec changed in a way the + * SDK can't update in place — caller falls through to DropAndRecreate. + * + * SDK's updateRelationshipAttribute exposes only `onDelete` and `newKey`. + * Structural changes (relationType, twoWay toggle, twoWayKey, relatedCollection) + * require drop+recreate and return false. + * + * One-way relationships hit a utopia bug in updateRelationship's + * partner-cascade (`updateAttributeMeta` throws because no partner exists). + * For one-way + onDelete change → return false → DropAndRecreate handles + * it cleanly via deleteRelationship. + */ + private function updateRelationshipInPlace( + UtopiaDocument $database, + UtopiaDocument $table, + Column|Attribute $resource, + string $type, + string $updatedAt, + UtopiaDocument $existingAttr, + UtopiaDatabase $dbForDatabases, + ): bool { + $sourceOptions = $resource->getOptions(); + $destOptions = $existingAttr->getAttribute('options', []); + + if ($this->arraysDifferOnKeys($sourceOptions, $destOptions, self::RELATIONSHIP_STRUCTURAL_FIELDS)) { + return false; + } + + $isTwoWay = (bool) ($destOptions['twoWay'] ?? false); + $onDeleteChanged = ($sourceOptions['onDelete'] ?? null) !== ($destOptions['onDelete'] ?? null); + + // One-way + any actual change → utopia's partner-cascade throws. + // DropAndRecreate handles one-way cleanly. + if (!$isTwoWay && $onDeleteChanged) { + return false; + } + + if ($onDeleteChanged) { + $dbForDatabases->updateRelationship( + collection: $this->tableCollectionId($database, $table), + id: $resource->getKey(), + onDelete: (string) ($sourceOptions['onDelete'] ?? ''), + ); + } + + // Refresh source-side Appwrite-level meta. Options preserve dest's + // structural fields verbatim — they didn't change. + $this->dbForProject->updateDocument('attributes', $existingAttr->getId(), new UtopiaDocument([ + 'key' => $resource->getKey(), + 'type' => $type, + 'options' => array_merge($destOptions, [ + 'onDelete' => $sourceOptions['onDelete'] ?? $destOptions['onDelete'] ?? null, + ]), + '$updatedAt' => $updatedAt, + ])); + + $this->purgeTableCaches($database, $table, $dbForDatabases); + return true; + } + + /** + * True iff the destination's existing index spec matches what the source + * resource is asking for on the user-settable fields (type, indexed + * columns, sort orders). Used to detect phantom updatedAt drift on + * indexes (which have no in-place update primitive); when specs match we + * tolerate, otherwise fall through to DropAndRecreate. + * + * `lengths` is intentionally not compared: it's derived per-column from + * the adapter's index validator, not user-settable on the Index resource, + * so two equivalent specs always produce the same lengths array. + */ + private function indexSpecMatches(UtopiaDocument $existingIdx, Index $resource): bool + { + return $existingIdx->getAttribute('type') === $resource->getType() + && $existingIdx->getAttribute('attributes') === $resource->getColumns() + && $existingIdx->getAttribute('orders') === $resource->getOrders(); } /** @@ -1384,6 +1524,70 @@ class Appwrite extends Destination return $database->getSequence() . ':' . $table->getSequence(); } + /** + * utopia-php/database collection id for the database itself (lookup target + * for table documents inside this database). + */ + private function databaseCollectionId(UtopiaDocument $database): string + { + return 'database_' . $database->getSequence(); + } + + /** + * utopia-php/database collection id for a specific table (lookup target + * for row documents inside this table). Used as the `collection` argument + * to most `$dbForDatabases` calls. + */ + private function tableCollectionId(UtopiaDocument $database, UtopiaDocument $table): string + { + return $this->databaseCollectionId($database) . '_collection_' . $table->getSequence(); + } + + /** + * Composite id for an attribute or index meta document in the platform DB + * (`attributes` / `indexes` collections). Built deterministically from + * sequences + key, mirroring how Appwrite stores meta docs. + */ + private function attributeIndexMetaId(UtopiaDocument $database, UtopiaDocument $table, string $key): string + { + return $database->getSequence() . '_' . $table->getSequence() . '_' . $key; + } + + /** + * Invalidate platform + per-database caches for a table after any + * structural change (attribute/index/permissions). Required because the + * Appwrite UI reads cached collection metadata; stale cache shows the + * pre-change schema until evicted. Called after Tolerate, UpdateInPlace, + * and DropAndRecreate paths so subsequent reads see the current state. + */ + private function purgeTableCaches( + UtopiaDocument $database, + UtopiaDocument $table, + UtopiaDatabase $dbForDatabases, + ): void { + $this->dbForProject->purgeCachedDocument($this->databaseCollectionId($database), $table->getId()); + $dbForDatabases->purgeCachedCollection($this->tableCollectionId($database, $table)); + } + + /** + * True iff the two array-shaped specs disagree on any of the listed keys + * (treating missing as null). Used to detect "the SDK can't express this + * change in place" — caller falls through to DropAndRecreate when true. + * + * @param array $a + * @param array $b + * @param list $keys + */ + private function arraysDifferOnKeys(array $a, array $b, array $keys): bool + { + foreach ($keys as $key) { + if (($a[$key] ?? null) !== ($b[$key] ?? null)) { + return true; + } + } + return false; + } + /** * Records that $key was seen for this (database, table) during the run. * $kind selects the tracker bucket ('attributeKeys' or 'indexKeys'). Only @@ -1516,7 +1720,7 @@ class Appwrite extends Destination $key = (string) $attrDoc->getAttribute('key'); $type = (string) $attrDoc->getAttribute('type'); $options = $attrDoc->getAttribute('options', []); - $collectionId = 'database_' . $database->getSequence() . '_collection_' . $table->getSequence(); + $collectionId = $this->tableCollectionId($database, $table); if ($type === UtopiaDatabase::VAR_RELATIONSHIP) { $this->tolerateMissing(fn () => $dbForDatabases->deleteRelationship($collectionId, $key)); @@ -1524,7 +1728,7 @@ class Appwrite extends Destination $this->tolerateMissing(fn () => $dbForDatabases->deleteAttribute($collectionId, $key)); } $this->tolerateMissing(fn () => $this->dbForProject->deleteDocument('attributes', $attrDoc->getId())); - $this->dbForProject->purgeCachedDocument('database_' . $database->getSequence(), $table->getId()); + $this->dbForProject->purgeCachedDocument($this->databaseCollectionId($database), $table->getId()); $dbForDatabases->purgeCachedCollection($collectionId); if ($type !== UtopiaDatabase::VAR_RELATIONSHIP || empty($options['twoWay'])) { @@ -1535,7 +1739,7 @@ class Appwrite extends Destination if ($twoWayKey === '' || $relatedTableId === '') { return; } - $relatedTable = $this->dbForProject->getDocument('database_' . $database->getSequence(), $relatedTableId); + $relatedTable = $this->dbForProject->getDocument($this->databaseCollectionId($database), $relatedTableId); if ($relatedTable->isEmpty()) { return; } @@ -1543,12 +1747,9 @@ class Appwrite extends Destination // Physical column on the related table was already dropped by // deleteRelationship above. Only the Appwrite-level metadata doc // remains to clean up. - $childMetaId = $database->getSequence() . '_' . $relatedTable->getSequence() . '_' . $twoWayKey; + $childMetaId = $this->attributeIndexMetaId($database, $relatedTable, $twoWayKey); $this->tolerateMissing(fn () => $this->dbForProject->deleteDocument('attributes', $childMetaId)); - $this->dbForProject->purgeCachedDocument('database_' . $database->getSequence(), $relatedTable->getId()); - $dbForDatabases->purgeCachedCollection( - 'database_' . $database->getSequence() . '_collection_' . $relatedTable->getSequence(), - ); + $this->purgeTableCaches($database, $relatedTable, $dbForDatabases); } private function dropOrphanIndex( @@ -1557,12 +1758,12 @@ class Appwrite extends Destination string $indexKey, UtopiaDatabase $dbForDatabases, ): void { - $collectionId = 'database_' . $database->getSequence() . '_collection_' . $table->getSequence(); + $collectionId = $this->tableCollectionId($database, $table); $indexMetaId = $database->getSequence() . '_' . $table->getSequence() . '_' . $indexKey; $this->tolerateMissing(fn () => $dbForDatabases->deleteIndex($collectionId, $indexKey)); $this->tolerateMissing(fn () => $this->dbForProject->deleteDocument('indexes', $indexMetaId)); - $this->dbForProject->purgeCachedDocument('database_' . $database->getSequence(), $table->getId()); + $this->dbForProject->purgeCachedDocument($this->databaseCollectionId($database), $table->getId()); } /** diff --git a/src/Migration/Destinations/OnDuplicate.php b/src/Migration/Destinations/OnDuplicate.php index a40b50e12c..c709c71a9f 100644 --- a/src/Migration/Destinations/OnDuplicate.php +++ b/src/Migration/Destinations/OnDuplicate.php @@ -33,12 +33,22 @@ enum OnDuplicate: string /** * Schema-level reconciliation decision. * - * $canDrop = true → leaves (attributes, indexes) get DropAndRecreate on Upsert-newer. - * $canDrop = false → containers (databases, tables) get UpdateInPlace on Upsert-newer. - * Default is false so destructive reconciliation requires explicit opt-in. + * createdAt-different → the source-side resource was deleted+recreated, so + * it's a different physical incarnation. Destination should follow suit + * with DropAndRecreate (or UpdateInPlace if $canDrop is false — containers). + * + * Same createdAt + newer updatedAt → metadata-only edit on the same + * resource. UpdateInPlace; the caller checks whether the specific changed + * fields are SDK-updatable and falls back to DropAndRecreate if not. + * + * $canDrop = true → leaves (attributes, indexes) can be dropped. + * $canDrop = false → containers (databases, tables) get UpdateInPlace + * even on createdAt-different (drop would lose children). */ public function resolveSchemaAction( bool $exists, + ?string $sourceCreatedAt = null, + ?string $destCreatedAt = null, ?string $sourceUpdatedAt = null, ?string $destUpdatedAt = null, bool $canDrop = false, @@ -49,12 +59,53 @@ enum OnDuplicate: string return match ($this) { self::Fail => SchemaAction::Create, self::Skip => SchemaAction::Tolerate, - self::Upsert => $this->sourceIsNewer($sourceUpdatedAt, $destUpdatedAt) - ? ($canDrop ? SchemaAction::DropAndRecreate : SchemaAction::UpdateInPlace) - : SchemaAction::Tolerate, + self::Upsert => $this->resolveUpsertAction( + $sourceCreatedAt, + $destCreatedAt, + $sourceUpdatedAt, + $destUpdatedAt, + $canDrop, + ), }; } + private function resolveUpsertAction( + ?string $sourceCreatedAt, + ?string $destCreatedAt, + ?string $sourceUpdatedAt, + ?string $destUpdatedAt, + bool $canDrop, + ): SchemaAction { + if ($this->createdAtDiffers($sourceCreatedAt, $destCreatedAt)) { + return $canDrop ? SchemaAction::DropAndRecreate : SchemaAction::UpdateInPlace; + } + + if ($this->sourceIsNewer($sourceUpdatedAt, $destUpdatedAt)) { + return SchemaAction::UpdateInPlace; + } + + return SchemaAction::Tolerate; + } + + /** + * Detect whether the source-side resource has a different physical + * createdAt than the destination — i.e., the source resource was deleted + * and recreated since the last migration. Null/empty/zero-date treated as + * unknown → false (don't trigger destructive action on uncertain input). + */ + private function createdAtDiffers(?string $source, ?string $dest): bool + { + if ($source === null || $source === '' || $dest === null || $dest === '') { + return false; + } + $src = \strtotime($source); + $dst = \strtotime($dest); + if ($src === false || $dst === false || $src <= 0 || $dst <= 0) { + return false; + } + return $src !== $dst; + } + /** * strtotime() accepts '0000-00-00' leniently (returns a large negative * epoch, not false), so reject non-positive epochs too. Null/empty are diff --git a/tests/Migration/Unit/General/OnDuplicateTest.php b/tests/Migration/Unit/General/OnDuplicateTest.php index 42ffa29661..c8b10e1a4a 100644 --- a/tests/Migration/Unit/General/OnDuplicateTest.php +++ b/tests/Migration/Unit/General/OnDuplicateTest.php @@ -9,8 +9,19 @@ use Utopia\Migration\Destinations\SchemaAction; /** * OnDuplicate::resolveSchemaAction is the load-bearing decision point for - * re-migration tolerance. These tests lock the mode × existence × timestamp - * matrix so a future refactor can't silently shift the mapping. + * re-migration tolerance. These tests lock the mode × existence × createdAt × + * updatedAt × canDrop matrix so a future refactor can't silently shift the + * mapping. + * + * Decision rules under Upsert (with $exists = true): + * - createdAt differs → resource was deleted+recreated on source. Caller can + * drop and recreate (canDrop=true) or update in place (canDrop=false; for + * containers like databases/tables which would lose children on drop). + * - createdAt same + updatedAt newer → metadata-only edit. UpdateInPlace. + * The caller checks whether changed fields are SDK-updatable; if not it + * falls through to DropAndRecreate. + * - createdAt same + updatedAt equal/older → Tolerate. + * - Unparseable createdAt or updatedAt → conservative; treat as if no diff. */ class OnDuplicateTest extends TestCase { @@ -38,13 +49,15 @@ class OnDuplicateTest extends TestCase public function testSkipAlwaysToleratesExisting(): void { - // Skip must ignore timestamps entirely — it's the "don't touch" - // contract. Exercise both orderings to prove the comparison isn't - // consulted. + // Skip must ignore createdAt/updatedAt entirely — it's the "don't + // touch" contract. Exercise both source-newer and dest-newer to prove + // comparisons aren't consulted. $this->assertSame( SchemaAction::Tolerate, OnDuplicate::Skip->resolveSchemaAction( exists: true, + sourceCreatedAt: '2020-01-01T00:00:00.000+00:00', + destCreatedAt: '2026-01-01T00:00:00.000+00:00', sourceUpdatedAt: '2026-01-01T00:00:00.000+00:00', destUpdatedAt: '2020-01-01T00:00:00.000+00:00', ), @@ -59,13 +72,109 @@ class OnDuplicateTest extends TestCase ); } - public function testUpsertLeafSourceNewerDropsAndRecreates(): void + public function testUpsertCreatedAtDiffersOnLeafDropsAndRecreates(): void { - // canDrop: true → leaf resource (attribute, index). Column data is - // repopulated by the follow-up row Upsert, or the resource is pure - // metadata (index) so destructive reconciliation is safe. + // canDrop: true + createdAt differs → leaf was deleted/recreated on + // source. Drop the destination's incarnation and create fresh. $this->assertSame( SchemaAction::DropAndRecreate, + OnDuplicate::Upsert->resolveSchemaAction( + exists: true, + sourceCreatedAt: '2026-04-23T10:00:00.000+00:00', + destCreatedAt: '2026-04-20T10:00:00.000+00:00', + canDrop: true, + ), + ); + } + + public function testUpsertCreatedAtDiffersOnContainerUpdatesInPlace(): void + { + // Default canDrop: false (containers like databases/tables). Even on + // createdAt diff, drop is forbidden — children would be lost. Fall + // back to UpdateInPlace. + $this->assertSame( + SchemaAction::UpdateInPlace, + OnDuplicate::Upsert->resolveSchemaAction( + exists: true, + sourceCreatedAt: '2026-04-23T10:00:00.000+00:00', + destCreatedAt: '2026-04-20T10:00:00.000+00:00', + ), + ); + } + + public function testUpsertCreatedAtSameUpdatedAtNewerUpdatesInPlace(): void + { + // Same createdAt + newer updatedAt → metadata-only edit on the same + // physical resource. UpdateInPlace; caller checks whether the changed + // fields are SDK-updatable and falls back to DropAndRecreate if not. + $this->assertSame( + SchemaAction::UpdateInPlace, + OnDuplicate::Upsert->resolveSchemaAction( + exists: true, + sourceCreatedAt: '2026-04-20T10:00:00.000+00:00', + destCreatedAt: '2026-04-20T10:00:00.000+00:00', + sourceUpdatedAt: '2026-04-23T10:00:00.000+00:00', + destUpdatedAt: '2026-04-23T09:59:59.000+00:00', + canDrop: true, + ), + ); + } + + public function testUpsertCreatedAtSameUpdatedAtEqualTolerates(): void + { + // Same createdAt + same updatedAt → nothing changed. Skip the work. + $created = '2026-04-20T10:00:00.000+00:00'; + $updated = '2026-04-23T10:00:00.000+00:00'; + $this->assertSame( + SchemaAction::Tolerate, + OnDuplicate::Upsert->resolveSchemaAction( + exists: true, + sourceCreatedAt: $created, + destCreatedAt: $created, + sourceUpdatedAt: $updated, + destUpdatedAt: $updated, + canDrop: true, + ), + ); + } + + public function testUpsertCreatedAtSameUpdatedAtOlderTolerates(): void + { + // Dest is ahead — don't roll back. Avoids overwriting newer + // destination edits with stale source data. + $this->assertSame( + SchemaAction::Tolerate, + OnDuplicate::Upsert->resolveSchemaAction( + exists: true, + sourceCreatedAt: '2026-04-20T10:00:00.000+00:00', + destCreatedAt: '2026-04-20T10:00:00.000+00:00', + sourceUpdatedAt: '2026-04-23T09:00:00.000+00:00', + destUpdatedAt: '2026-04-23T10:00:00.000+00:00', + canDrop: true, + ), + ); + } + + public function testUpsertNoTimestampsTolerates(): void + { + // No timestamps provided at all → no information to act on. Conservative: + // Tolerate rather than risk destructive action on uncertain input. + $this->assertSame( + SchemaAction::Tolerate, + OnDuplicate::Upsert->resolveSchemaAction( + exists: true, + canDrop: true, + ), + ); + } + + public function testUpsertOnlyUpdatedAtNewerWithoutCreatedAtUpdatesInPlace(): void + { + // CreatedAt missing on either side (e.g. older Appwrite versions, CSV + // sources): can't detect "recreated", so the only signal is updatedAt. + // Newer source → UpdateInPlace path (caller validates SDK-updatability). + $this->assertSame( + SchemaAction::UpdateInPlace, OnDuplicate::Upsert->resolveSchemaAction( exists: true, sourceUpdatedAt: '2026-04-23T10:00:00.000+00:00', @@ -75,65 +184,8 @@ class OnDuplicateTest extends TestCase ); } - public function testUpsertContainerSourceNewerUpdatesInPlace(): void - { - // Default canDrop: false → container resource (database, table). - // Container's metadata doc gets updateDocument; children (tables, - // rows) are preserved untouched. - $this->assertSame( - SchemaAction::UpdateInPlace, - OnDuplicate::Upsert->resolveSchemaAction( - exists: true, - sourceUpdatedAt: '2026-04-23T10:00:00.000+00:00', - destUpdatedAt: '2026-04-23T09:59:59.000+00:00', - ), - ); - } - - public function testSkipNeverUpdatesContainerEvenWhenSourceNewer(): void - { - // Skip is strict "don't touch" — must never return UpdateInPlace, - // only Tolerate, regardless of timestamps or resource kind. - $this->assertSame( - SchemaAction::Tolerate, - OnDuplicate::Skip->resolveSchemaAction( - exists: true, - sourceUpdatedAt: '2026-04-23T10:00:00.000+00:00', - destUpdatedAt: '2026-04-23T09:59:59.000+00:00', - ), - ); - } - - public function testUpsertDestNewerTolerates(): void - { - $this->assertSame( - SchemaAction::Tolerate, - OnDuplicate::Upsert->resolveSchemaAction( - exists: true, - sourceUpdatedAt: '2026-04-23T09:00:00.000+00:00', - destUpdatedAt: '2026-04-23T10:00:00.000+00:00', - ), - ); - } - - public function testUpsertEqualTimestampsTolerates(): void - { - // Strict > comparison: equal means dest is already in sync, skip the - // drop. Avoids unnecessary destructive rebuild when the user hasn't - // touched source since the last migration. - $stamp = '2026-04-23T10:00:00.000+00:00'; - $this->assertSame( - SchemaAction::Tolerate, - OnDuplicate::Upsert->resolveSchemaAction( - exists: true, - sourceUpdatedAt: $stamp, - destUpdatedAt: $stamp, - ), - ); - } - /** - * @return array + * @return array */ public static function unparseableTimestampPairs(): array { @@ -152,11 +204,27 @@ class OnDuplicateTest extends TestCase } #[DataProvider('unparseableTimestampPairs')] - public function testUpsertUnparseableTimestampsTolerate(?string $source, ?string $dest): void + public function testUpsertUnparseableCreatedAtDoesNotTriggerDrop(?string $source, ?string $dest): void { - // Conservative: unparseable timestamps preserve existing destination - // rather than risk a destructive drop on garbage input. Any - // non-Appwrite source that emits malformed dates gets handled safely. + // Unparseable createdAt → don't trigger DropAndRecreate. With + // updatedAt also absent, falls through to Tolerate. Safety net for + // sources that emit malformed timestamps. + $this->assertSame( + SchemaAction::Tolerate, + OnDuplicate::Upsert->resolveSchemaAction( + exists: true, + sourceCreatedAt: $source, + destCreatedAt: $dest, + canDrop: true, + ), + ); + } + + #[DataProvider('unparseableTimestampPairs')] + public function testUpsertUnparseableUpdatedAtTolerates(?string $source, ?string $dest): void + { + // Conservative: unparseable updatedAt preserves existing destination + // rather than risk a destructive update on garbage input. $this->assertSame( SchemaAction::Tolerate, OnDuplicate::Upsert->resolveSchemaAction( @@ -170,7 +238,7 @@ class OnDuplicateTest extends TestCase public function testValuesListsAllCasesInDeclarationOrder(): void { // The values() helper is consumed by API/SDK param validators; this - // tests protects against an accidental case-rename or reorder. + // protects against an accidental case-rename or reorder. $this->assertSame(['fail', 'skip', 'upsert'], OnDuplicate::values()); } } From d7f56b03b8743e2a1998a140130fbfd0a5cfd40b Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Mon, 27 Apr 2026 11:30:28 +0100 Subject: [PATCH 37/91] Replace inline meta-id and collection-id literals with helpers --- src/Migration/Destinations/Appwrite.php | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index 62166ab781..f97423e908 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -786,7 +786,7 @@ class Appwrite extends Destination // Upsert row pass. $isRelationship = $type === UtopiaDatabase::VAR_RELATIONSHIP; - $attributeMetaId = $database->getSequence() . '_' . $table->getSequence() . '_' . $resource->getKey(); + $attributeMetaId = $this->attributeIndexMetaId($database, $table, $resource->getKey()); if ($this->onDuplicate !== OnDuplicate::Fail) { $existingAttr = $this->dbForProject->getDocument('attributes', $attributeMetaId); $action = $this->onDuplicate->resolveSchemaAction( @@ -881,7 +881,7 @@ class Appwrite extends Destination try { $twoWayAttribute = new UtopiaDocument([ - '$id' => ID::custom($database->getSequence() . '_' . $relatedTable->getSequence() . '_' . $twoWayKey), + '$id' => ID::custom($this->attributeIndexMetaId($database, $relatedTable, $twoWayKey)), 'key' => $twoWayKey, 'databaseInternalId' => $database->getSequence(), 'databaseId' => $database->getId(), @@ -1048,7 +1048,7 @@ class Appwrite extends Destination $this->trackOrphanCandidate($database, $table, 'indexKeys', $resource->getKey(), $dbForDatabases); $index = new UtopiaDocument([ - '$id' => ID::custom($database->getSequence() . '_' . $table->getSequence() . '_' . $resource->getKey()), + '$id' => ID::custom($this->attributeIndexMetaId($database, $table, $resource->getKey())), 'key' => $resource->getKey(), 'status' => 'available', // processing, available, failed, deleting, stuck 'databaseInternalId' => $database->getSequence(), @@ -1253,8 +1253,6 @@ class Appwrite extends Destination $resource->getTable()->getId(), ); - $databaseInternalId = $database->getSequence(); - $tableInternalId = $table->getSequence(); $dbForDatabases = ($this->getDatabasesDB)($database); // Reconcile the destination SCHEMA before rows land: drops @@ -1289,7 +1287,7 @@ class Appwrite extends Destination } } } - $collectionId = 'database_' . $databaseInternalId . '_collection_' . $tableInternalId; + $collectionId = $this->tableCollectionId($database, $table); match ($this->onDuplicate) { OnDuplicate::Upsert => $dbForDatabases->skipRelationshipsExistCheck( @@ -1331,7 +1329,7 @@ class Appwrite extends Destination UtopiaDatabase $dbForDatabases, ): void { $collectionId = $this->tableCollectionId($database, $table); - $attributeMetaId = $database->getSequence() . '_' . $table->getSequence() . '_' . $resource->getKey(); + $attributeMetaId = $this->attributeIndexMetaId($database, $table, $resource->getKey()); $isRelationship = $resource->getType() === Column::TYPE_RELATIONSHIP; if ($isRelationship) { @@ -1759,7 +1757,7 @@ class Appwrite extends Destination UtopiaDatabase $dbForDatabases, ): void { $collectionId = $this->tableCollectionId($database, $table); - $indexMetaId = $database->getSequence() . '_' . $table->getSequence() . '_' . $indexKey; + $indexMetaId = $this->attributeIndexMetaId($database, $table, $indexKey); $this->tolerateMissing(fn () => $dbForDatabases->deleteIndex($collectionId, $indexKey)); $this->tolerateMissing(fn () => $this->dbForProject->deleteDocument('indexes', $indexMetaId)); From 2cd053471e3580c339b29c7640b6e449d48ac6d1 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Mon, 27 Apr 2026 11:35:43 +0100 Subject: [PATCH 38/91] OnDuplicate: extract parseTimestamp() helper --- src/Migration/Destinations/OnDuplicate.php | 48 +++++++++++----------- 1 file changed, 25 insertions(+), 23 deletions(-) diff --git a/src/Migration/Destinations/OnDuplicate.php b/src/Migration/Destinations/OnDuplicate.php index c709c71a9f..5c9b7fa411 100644 --- a/src/Migration/Destinations/OnDuplicate.php +++ b/src/Migration/Destinations/OnDuplicate.php @@ -88,39 +88,41 @@ enum OnDuplicate: string } /** - * Detect whether the source-side resource has a different physical - * createdAt than the destination — i.e., the source resource was deleted - * and recreated since the last migration. Null/empty/zero-date treated as - * unknown → false (don't trigger destructive action on uncertain input). + * Whether source and destination have different physical createdAt values. + * Unknown (null/empty/zero-date) on either side → false. */ private function createdAtDiffers(?string $source, ?string $dest): bool { - if ($source === null || $source === '' || $dest === null || $dest === '') { - return false; - } - $src = \strtotime($source); - $dst = \strtotime($dest); - if ($src === false || $dst === false || $src <= 0 || $dst <= 0) { - return false; - } - return $src !== $dst; + $src = $this->parseTimestamp($source); + $dst = $this->parseTimestamp($dest); + return $src !== null && $dst !== null && $src !== $dst; } /** - * strtotime() accepts '0000-00-00' leniently (returns a large negative - * epoch, not false), so reject non-positive epochs too. Null/empty are - * treated as unknown → tolerate rather than risk a destructive drop. + * Whether source's timestamp is strictly newer than destination's. + * Unknown (null/empty/zero-date) on either side → false. */ private function sourceIsNewer(?string $source, ?string $dest): bool { - if ($source === null || $source === '' || $dest === null || $dest === '') { - return false; + $src = $this->parseTimestamp($source); + $dst = $this->parseTimestamp($dest); + return $src !== null && $dst !== null && $src > $dst; + } + + /** + * strtotime accepts '0000-00-00' leniently (returns a large negative epoch, + * not false), so non-positive epochs are rejected too. Null/empty/garbage + * → null so callers treat the comparison as unknown. + */ + private function parseTimestamp(?string $value): ?int + { + if ($value === null || $value === '') { + return null; } - $src = \strtotime($source); - $dst = \strtotime($dest); - if ($src === false || $dst === false || $src <= 0 || $dst <= 0) { - return false; + $epoch = \strtotime($value); + if ($epoch === false || $epoch <= 0) { + return null; } - return $src > $dst; + return $epoch; } } From 7c43d6ace9d214e39566175ff83292c79f4e904e Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Mon, 27 Apr 2026 12:21:05 +0100 Subject: [PATCH 39/91] Use match() for SchemaAction dispatch in 4 create methods --- src/Migration/Destinations/Appwrite.php | 154 +++++++++++++----------- 1 file changed, 86 insertions(+), 68 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index f97423e908..4fe0bea268 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -497,24 +497,29 @@ class Appwrite extends Destination canDrop: false, ); - if ($action === SchemaAction::Tolerate) { - $resource->setSequence($existing->getSequence()); - $resource->setStatus(Resource::STATUS_SKIPPED, 'Already exists on destination'); - return false; - } - - if ($action === SchemaAction::UpdateInPlace) { - $this->dbForProject->updateDocument('databases', $existing->getId(), new UtopiaDocument([ - 'name' => $resource->getDatabaseName(), - 'search' => implode(' ', [$resource->getId(), $resource->getDatabaseName()]), - 'enabled' => $resource->getEnabled(), - 'type' => empty($resource->getType()) ? 'legacy' : $resource->getType(), - 'originalId' => empty($resource->getOriginalId()) ? null : $resource->getOriginalId(), - 'database' => $resource->getDatabase(), - '$updatedAt' => $updatedAt, - ])); - $resource->setSequence($existing->getSequence()); - return true; + $earlyReturn = match ($action) { + SchemaAction::Tolerate => (function () use ($resource, $existing): bool { + $resource->setSequence($existing->getSequence()); + $resource->setStatus(Resource::STATUS_SKIPPED, 'Already exists on destination'); + return false; + })(), + SchemaAction::UpdateInPlace => (function () use ($resource, $existing, $updatedAt): bool { + $this->dbForProject->updateDocument('databases', $existing->getId(), new UtopiaDocument([ + 'name' => $resource->getDatabaseName(), + 'search' => implode(' ', [$resource->getId(), $resource->getDatabaseName()]), + 'enabled' => $resource->getEnabled(), + 'type' => empty($resource->getType()) ? 'legacy' : $resource->getType(), + 'originalId' => empty($resource->getOriginalId()) ? null : $resource->getOriginalId(), + 'database' => $resource->getDatabase(), + '$updatedAt' => $updatedAt, + ])); + $resource->setSequence($existing->getSequence()); + return true; + })(), + SchemaAction::Create, SchemaAction::DropAndRecreate => null, + }; + if ($earlyReturn !== null) { + return $earlyReturn; } } @@ -614,27 +619,32 @@ class Appwrite extends Destination canDrop: false, ); - if ($action === SchemaAction::Tolerate) { - $resource->setSequence($existing->getSequence()); - $resource->setStatus(Resource::STATUS_SKIPPED, 'Already exists on destination'); - return false; - } - - if ($action === SchemaAction::UpdateInPlace) { - $this->dbForProject->updateDocument( - $this->databaseCollectionId($database), - $existing->getId(), - new UtopiaDocument([ - 'name' => $resource->getTableName(), - 'search' => implode(' ', [$resource->getId(), $resource->getTableName()]), - 'enabled' => $resource->getEnabled(), - '$permissions' => Permission::aggregate($resource->getPermissions()), - 'documentSecurity' => $resource->getRowSecurity(), - '$updatedAt' => $updatedAt, - ]) - ); - $resource->setSequence($existing->getSequence()); - return true; + $earlyReturn = match ($action) { + SchemaAction::Tolerate => (function () use ($resource, $existing): bool { + $resource->setSequence($existing->getSequence()); + $resource->setStatus(Resource::STATUS_SKIPPED, 'Already exists on destination'); + return false; + })(), + SchemaAction::UpdateInPlace => (function () use ($resource, $existing, $database, $updatedAt): bool { + $this->dbForProject->updateDocument( + $this->databaseCollectionId($database), + $existing->getId(), + new UtopiaDocument([ + 'name' => $resource->getTableName(), + 'search' => implode(' ', [$resource->getId(), $resource->getTableName()]), + 'enabled' => $resource->getEnabled(), + '$permissions' => Permission::aggregate($resource->getPermissions()), + 'documentSecurity' => $resource->getRowSecurity(), + '$updatedAt' => $updatedAt, + ]) + ); + $resource->setSequence($existing->getSequence()); + return true; + })(), + SchemaAction::Create, SchemaAction::DropAndRecreate => null, + }; + if ($earlyReturn !== null) { + return $earlyReturn; } } @@ -798,24 +808,25 @@ class Appwrite extends Destination canDrop: true, ); - if ($action === SchemaAction::Tolerate) { - $this->purgeTableCaches($database, $table, $dbForDatabases); - $resource->setStatus(Resource::STATUS_SKIPPED, 'Already exists on destination'); - return false; - } - - // UpdateInPlace tries an SDK-equivalent update first; returns - // false if the source change isn't expressible in place (see - // ATTRIBUTE_NON_SDK_FIELDS / RELATIONSHIP_STRUCTURAL_FIELDS). - // Falls through to DropAndRecreate in that case. - if ($action === SchemaAction::UpdateInPlace) { - $applied = $isRelationship + // UpdateInPlace tries an SDK-equivalent update first; returns null + // when the source change isn't expressible in place (see + // ATTRIBUTE_NON_SDK_FIELDS / RELATIONSHIP_STRUCTURAL_FIELDS) so it + // falls through to the DropAndRecreate drop step below. + $earlyReturn = match ($action) { + SchemaAction::Tolerate => (function () use ($resource, $database, $table, $dbForDatabases): bool { + $this->purgeTableCaches($database, $table, $dbForDatabases); + $resource->setStatus(Resource::STATUS_SKIPPED, 'Already exists on destination'); + return false; + })(), + SchemaAction::UpdateInPlace => ($isRelationship ? $this->updateRelationshipInPlace($database, $table, $resource, $type, $updatedAt, $existingAttr, $dbForDatabases) - : $this->updateAttributeInPlace($database, $table, $resource, $type, $updatedAt, $existingAttr, $dbForDatabases); - - if ($applied) { - return true; - } + : $this->updateAttributeInPlace($database, $table, $resource, $type, $updatedAt, $existingAttr, $dbForDatabases)) + ? true + : null, + SchemaAction::DropAndRecreate, SchemaAction::Create => null, + }; + if ($earlyReturn !== null) { + return $earlyReturn; } if ($action === SchemaAction::DropAndRecreate || $action === SchemaAction::UpdateInPlace) { @@ -1111,22 +1122,29 @@ class Appwrite extends Destination canDrop: true, ); - if ($action === SchemaAction::Tolerate) { - $this->dbForProject->purgeCachedDocument($this->databaseCollectionId($database), $table->getId()); - $resource->setStatus(Resource::STATUS_SKIPPED, 'Already exists on destination'); - return false; - } - // Indexes have no SDK in-place update — utopia provides no // updateIndex primitive, and the underlying DB requires drop+ // recreate for any structural change. UpdateInPlace from // resolveSchemaAction (createdAt-same + updatedAt-newer) is - // treated as a possibly-phantom edit; if the spec actually - // matches existing, tolerate; otherwise drop and recreate. - if ($action === SchemaAction::UpdateInPlace && $this->indexSpecMatches($existingIdx, $resource)) { - $this->dbForProject->purgeCachedDocument($this->databaseCollectionId($database), $table->getId()); - $resource->setStatus(Resource::STATUS_SKIPPED, 'Index spec unchanged'); - return false; + // treated as a possibly-phantom edit; if the spec matches + // existing, tolerate; otherwise drop and recreate. + $earlyReturn = match ($action) { + SchemaAction::Tolerate => (function () use ($resource, $database, $table): bool { + $this->dbForProject->purgeCachedDocument($this->databaseCollectionId($database), $table->getId()); + $resource->setStatus(Resource::STATUS_SKIPPED, 'Already exists on destination'); + return false; + })(), + SchemaAction::UpdateInPlace => $this->indexSpecMatches($existingIdx, $resource) + ? (function () use ($resource, $database, $table): bool { + $this->dbForProject->purgeCachedDocument($this->databaseCollectionId($database), $table->getId()); + $resource->setStatus(Resource::STATUS_SKIPPED, 'Index spec unchanged'); + return false; + })() + : null, + SchemaAction::DropAndRecreate, SchemaAction::Create => null, + }; + if ($earlyReturn !== null) { + return $earlyReturn; } if ($action === SchemaAction::DropAndRecreate || $action === SchemaAction::UpdateInPlace) { From a36d95f86d24b4f024a419191e69c3c034a593eb Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Mon, 27 Apr 2026 12:29:25 +0100 Subject: [PATCH 40/91] =?UTF-8?q?Trim=20verbose=20code=20comments=20?= =?UTF-8?q?=E2=80=94=20keep=20only=20WHY=20content?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/Migration/Destinations/Appwrite.php | 189 +++------------------ src/Migration/Destinations/OnDuplicate.php | 32 +--- 2 files changed, 30 insertions(+), 191 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index 4fe0bea268..80b22c711f 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -63,12 +63,7 @@ use Utopia\Migration\Transfer; class Appwrite extends Destination { - /** - * Attribute fields not reachable via Appwrite SDK's per-type - * updateXAttribute endpoints. Source-side changes to any of these force - * DropAndRecreate because no in-place SDK call can express the change. - * Update if the SDK adds new endpoints (e.g. `array` toggle). - */ + /** Fields the SDK's per-type updateXAttribute endpoints don't expose; a change here forces DropAndRecreate. */ private const ATTRIBUTE_NON_SDK_FIELDS = [ 'type', 'array', @@ -78,11 +73,7 @@ class Appwrite extends Destination 'filters', ]; - /** - * Relationship `options` fields the SDK's updateRelationshipAttribute - * does not expose (it allows only `onDelete` and `newKey`). Any change - * here is a structural relationship swap that requires drop+recreate. - */ + /** Fields the SDK's updateRelationshipAttribute doesn't expose (only onDelete/newKey are SDK-reachable). */ private const RELATIONSHIP_STRUCTURAL_FIELDS = [ 'relationType', 'twoWay', @@ -113,13 +104,10 @@ class Appwrite extends Destination private array $rowBuffer = []; /** - * Upsert-mode orphan tracking, keyed by (database, table). Each entry - * holds the attribute + index keys source declared for that table plus - * the docs/handles needed to reach the destination at cleanup time. - * Orphans are the complement: anything the destination has whose key - * is NOT in this record. Entries are removed from the map after their - * cleanup has run, so the final sweep at end-of-migration only visits - * tables that had no rows. + * Upsert-mode orphan tracking, keyed by (database, table). Orphans are + * destination keys not in `attributeKeys` / `indexKeys`. Entries removed + * after their cleanup runs so the end-of-run sweep only visits tables + * that had no rows. * * @var arraygetDatabasesDB = $getDatabasesDB; } - /** - * Upsert-mode orphan cleanup runs after a successful migration only. - * A thrown exception from the source/import loop short-circuits here - * so mid-migration failures preserve the destination as-is. - */ + /** Orphan cleanup runs only after a successful migration — a mid-run throw preserves the destination as-is. */ #[Override] public function run( array $resources, @@ -484,7 +468,6 @@ class Appwrite extends Destination $createdAt = $this->normalizeDateTime($resource->getCreatedAt()); $updatedAt = $this->normalizeDateTime($resource->getUpdatedAt(), $createdAt); - // Fail mode skips the pre-check so library's DuplicateException surfaces on re-migration. if ($this->onDuplicate !== OnDuplicate::Fail) { $existing = $this->dbForProject->getDocument('databases', $resource->getId()); $action = $this->onDuplicate->resolveSchemaAction( @@ -493,7 +476,6 @@ class Appwrite extends Destination $existing->getCreatedAt(), $updatedAt, $existing->getUpdatedAt(), - // Containers (databases) can't be dropped — children would be lost. canDrop: false, ); @@ -615,7 +597,6 @@ class Appwrite extends Destination $existing->getCreatedAt(), $updatedAt, $existing->getUpdatedAt(), - // Containers (tables) can't be dropped — children would be lost. canDrop: false, ); @@ -790,10 +771,8 @@ class Appwrite extends Destination $this->trackOrphanCandidate($database, $table, 'attributeKeys', $resource->getKey(), $dbForDatabases); - // Both relationship types use deleteRelationship (not deleteAttribute, - // which throws for VAR_RELATIONSHIP). One-way: clean drop. Two-way: - // drops both columns; partner row data is restored by the subsequent - // Upsert row pass. + // Both rel types route through deleteRelationship — deleteAttribute throws for VAR_RELATIONSHIP. + // Two-way drop loses partner row data, restored by the subsequent Upsert row pass. $isRelationship = $type === UtopiaDatabase::VAR_RELATIONSHIP; $attributeMetaId = $this->attributeIndexMetaId($database, $table, $resource->getKey()); @@ -808,10 +787,7 @@ class Appwrite extends Destination canDrop: true, ); - // UpdateInPlace tries an SDK-equivalent update first; returns null - // when the source change isn't expressible in place (see - // ATTRIBUTE_NON_SDK_FIELDS / RELATIONSHIP_STRUCTURAL_FIELDS) so it - // falls through to the DropAndRecreate drop step below. + // UpdateInPlace returns null when the source change isn't SDK-expressible — falls through to the drop step below. $earlyReturn = match ($action) { SchemaAction::Tolerate => (function () use ($resource, $database, $table, $dbForDatabases): bool { $this->purgeTableCaches($database, $table, $dbForDatabases); @@ -1122,12 +1098,7 @@ class Appwrite extends Destination canDrop: true, ); - // Indexes have no SDK in-place update — utopia provides no - // updateIndex primitive, and the underlying DB requires drop+ - // recreate for any structural change. UpdateInPlace from - // resolveSchemaAction (createdAt-same + updatedAt-newer) is - // treated as a possibly-phantom edit; if the spec matches - // existing, tolerate; otherwise drop and recreate. + // Indexes have no in-place primitive — UpdateInPlace tolerates if spec matches, else drop+recreate. $earlyReturn = match ($action) { SchemaAction::Tolerate => (function () use ($resource, $database, $table): bool { $this->dbForProject->purgeCachedDocument($this->databaseCollectionId($database), $table->getId()); @@ -1273,11 +1244,7 @@ class Appwrite extends Destination $dbForDatabases = ($this->getDatabasesDB)($database); - // Reconcile the destination SCHEMA before rows land: drops - // attributes/indexes source no longer declares so the - // Structure validator doesn't reject rows on orphan required - // columns. Distinct from the payload-shape pass below, which - // strips extra fields off the incoming ROW documents. + // Drop schema-level orphans before rows land so the Structure validator doesn't reject on orphan required columns. $this->cleanupUpsertOrphansForTable($this->tableIdentity($database, $table)); /** * This is in case an attribute was deleted from Appwrite attributes collection but was not deleted from the table @@ -1331,14 +1298,8 @@ class Appwrite extends Destination } /** - * Drop an attribute (metadata doc + physical column) so it can be recreated. - * - * Branches by type because utopia's deleteAttribute throws for relationships; - * relationships use deleteRelationship, which handles both one-way (partner - * cleanup is a silent no-op since no partner attribute exists) and two-way - * (partner attribute and physical column both removed). For two-way, the - * partner-side Appwrite-level meta doc is also deleted here since - * deleteRelationship only touches utopia's internal metadata. + * Drop attribute (meta doc + physical column). Relationships route through + * deleteRelationship since deleteAttribute throws for VAR_RELATIONSHIP. */ private function dropAttributeForRecreate( UtopiaDocument $database, @@ -1358,8 +1319,7 @@ class Appwrite extends Destination $this->dbForProject->deleteDocument('attributes', $attributeMetaId); - // For two-way relationships, also remove the partner-side Appwrite meta - // doc — deleteRelationship only touches utopia's internal _metadata. + // deleteRelationship only touches utopia's _metadata; clear the Appwrite-level partner meta doc too. if ($isRelationship && ($resource->getOptions()['twoWay'] ?? false)) { $relatedTableId = $resource->getOptions()['relatedCollection'] ?? null; $twoWayKey = $resource->getOptions()['twoWayKey'] ?? null; @@ -1378,16 +1338,7 @@ class Appwrite extends Destination $this->purgeTableCaches($database, $table, $dbForDatabases); } - /** - * Apply an SDK-equivalent in-place update for a non-relationship attribute. - * Returns true if applied, false if the source spec changed in a way the - * SDK can't update in place — caller falls through to DropAndRecreate. - * - * SDK-updatable per `updateXAttribute` endpoints: required, default, size - * (string/varchar), min/max (integer/float), elements (enum), newKey rename. - * Anything else (type, array, signed, format, formatOptions, filters) - * requires drop+recreate and returns false. - */ + /** Returns false when the source change isn't SDK-expressible — caller falls through to DropAndRecreate. */ private function updateAttributeInPlace( UtopiaDocument $database, UtopiaDocument $table, @@ -1415,9 +1366,7 @@ class Appwrite extends Destination return false; } - // Apply the SDK-updatable subset via utopia. Pass existing values for - // non-SDK fields explicitly so utopia doesn't trigger an ALTER for - // fields that haven't changed. + // Pass existing values for non-SDK fields so utopia doesn't trigger an ALTER for unchanged fields. $dbForDatabases->updateAttribute( collection: $this->tableCollectionId($database, $table), id: $resource->getKey(), @@ -1451,18 +1400,8 @@ class Appwrite extends Destination } /** - * Apply an SDK-equivalent in-place update for a relationship attribute. - * Returns true if applied, false if the source spec changed in a way the - * SDK can't update in place — caller falls through to DropAndRecreate. - * - * SDK's updateRelationshipAttribute exposes only `onDelete` and `newKey`. - * Structural changes (relationType, twoWay toggle, twoWayKey, relatedCollection) - * require drop+recreate and return false. - * - * One-way relationships hit a utopia bug in updateRelationship's - * partner-cascade (`updateAttributeMeta` throws because no partner exists). - * For one-way + onDelete change → return false → DropAndRecreate handles - * it cleanly via deleteRelationship. + * Returns false when the source change isn't SDK-expressible — caller falls through to DropAndRecreate. + * One-way + onDelete change is also rejected: utopia's updateRelationship partner-cascade throws on one-way. */ private function updateRelationshipInPlace( UtopiaDocument $database, @@ -1483,8 +1422,6 @@ class Appwrite extends Destination $isTwoWay = (bool) ($destOptions['twoWay'] ?? false); $onDeleteChanged = ($sourceOptions['onDelete'] ?? null) !== ($destOptions['onDelete'] ?? null); - // One-way + any actual change → utopia's partner-cascade throws. - // DropAndRecreate handles one-way cleanly. if (!$isTwoWay && $onDeleteChanged) { return false; } @@ -1497,8 +1434,6 @@ class Appwrite extends Destination ); } - // Refresh source-side Appwrite-level meta. Options preserve dest's - // structural fields verbatim — they didn't change. $this->dbForProject->updateDocument('attributes', $existingAttr->getId(), new UtopiaDocument([ 'key' => $resource->getKey(), 'type' => $type, @@ -1513,15 +1448,8 @@ class Appwrite extends Destination } /** - * True iff the destination's existing index spec matches what the source - * resource is asking for on the user-settable fields (type, indexed - * columns, sort orders). Used to detect phantom updatedAt drift on - * indexes (which have no in-place update primitive); when specs match we - * tolerate, otherwise fall through to DropAndRecreate. - * * `lengths` is intentionally not compared: it's derived per-column from - * the adapter's index validator, not user-settable on the Index resource, - * so two equivalent specs always produce the same lengths array. + * the adapter's index validator and not settable on the Index resource. */ private function indexSpecMatches(UtopiaDocument $existingIdx, Index $resource): bool { @@ -1530,52 +1458,27 @@ class Appwrite extends Destination && $existingIdx->getAttribute('orders') === $resource->getOrders(); } - /** - * Deterministic per-(database, table) key used to index the orphan - * tracker (`$orphansByTable`). Built from sequences so it's stable - * across calls but unique within the run. - */ private function tableIdentity(UtopiaDocument $database, UtopiaDocument $table): string { return $database->getSequence() . ':' . $table->getSequence(); } - /** - * utopia-php/database collection id for the database itself (lookup target - * for table documents inside this database). - */ private function databaseCollectionId(UtopiaDocument $database): string { return 'database_' . $database->getSequence(); } - /** - * utopia-php/database collection id for a specific table (lookup target - * for row documents inside this table). Used as the `collection` argument - * to most `$dbForDatabases` calls. - */ private function tableCollectionId(UtopiaDocument $database, UtopiaDocument $table): string { return $this->databaseCollectionId($database) . '_collection_' . $table->getSequence(); } - /** - * Composite id for an attribute or index meta document in the platform DB - * (`attributes` / `indexes` collections). Built deterministically from - * sequences + key, mirroring how Appwrite stores meta docs. - */ private function attributeIndexMetaId(UtopiaDocument $database, UtopiaDocument $table, string $key): string { return $database->getSequence() . '_' . $table->getSequence() . '_' . $key; } - /** - * Invalidate platform + per-database caches for a table after any - * structural change (attribute/index/permissions). Required because the - * Appwrite UI reads cached collection metadata; stale cache shows the - * pre-change schema until evicted. Called after Tolerate, UpdateInPlace, - * and DropAndRecreate paths so subsequent reads see the current state. - */ + /** Stale platform/per-database cache shows the pre-change schema; evict after every structural change. */ private function purgeTableCaches( UtopiaDocument $database, UtopiaDocument $table, @@ -1586,10 +1489,6 @@ class Appwrite extends Destination } /** - * True iff the two array-shaped specs disagree on any of the listed keys - * (treating missing as null). Used to detect "the SDK can't express this - * change in place" — caller falls through to DropAndRecreate when true. - * * @param array $a * @param array $b * @param list $keys @@ -1604,11 +1503,7 @@ class Appwrite extends Destination return false; } - /** - * Records that $key was seen for this (database, table) during the run. - * $kind selects the tracker bucket ('attributeKeys' or 'indexKeys'). Only - * Upsert mode accumulates; Skip/Fail short-circuit. - */ + /** $kind is 'attributeKeys' or 'indexKeys'. */ private function trackOrphanCandidate( UtopiaDocument $database, UtopiaDocument $table, @@ -1632,11 +1527,7 @@ class Appwrite extends Destination $this->orphansByTable[$tableId][$kind][] = $key; } - /** - * End-of-migration sweep: cleans up any table not already handled by a - * per-table cleanup in createRecord (i.e. tables that had no rows). - * Skipped if the migration failed before run() completed. - */ + /** End-of-migration sweep — only visits tables that had no rows (rest were cleaned per-table in createRecord). */ private function cleanupUpsertOrphans(): void { foreach (\array_keys($this->orphansByTable) as $tableId) { @@ -1644,13 +1535,7 @@ class Appwrite extends Destination } } - /** - * Drops destination attributes/indexes whose keys weren't observed from - * source for this table. Called per-table from createRecord before rows - * land so the Structure validator sees the post-cleanup schema. After - * running, the entry is removed from the tracker so the end-of-run - * sweep doesn't re-do the work. - */ + /** Called per-table from createRecord before rows land so Structure validator sees the post-cleanup schema. */ private function cleanupUpsertOrphansForTable(string $tableId): void { if ($this->onDuplicate !== OnDuplicate::Upsert) { @@ -1690,10 +1575,6 @@ class Appwrite extends Destination } /** - * Finds destination metadata docs in $metaCollection belonging to this - * (database, table) and invokes $drop for each one whose key isn't in - * $processedKeys. Shared by the attribute and index cleanup paths. - * * @param list $processedKeys * @param callable(UtopiaDocument): void $drop */ @@ -1716,17 +1597,7 @@ class Appwrite extends Destination } } - /** - * Drop an orphan attribute (metadata doc + physical column). Uses the - * destination's own metadata document as the source of truth for type - * and relationship options, since there's no source resource to consult. - * - * Relationships use deleteRelationship (which cascades to both sides's - * physical columns + utopia's internal metadata) rather than - * deleteAttribute (which throws for relationship types). Appwrite's - * application-level `attributes` metadata docs on both sides are - * cleaned separately. - */ + /** Reads dest's own meta doc as source of truth — there's no source resource for an orphan. */ private function dropOrphanAttribute( UtopiaDocument $database, UtopiaDocument $table, @@ -1760,9 +1631,7 @@ class Appwrite extends Destination return; } - // Physical column on the related table was already dropped by - // deleteRelationship above. Only the Appwrite-level metadata doc - // remains to clean up. + // deleteRelationship already dropped the partner physical column; only the Appwrite-level meta doc remains. $childMetaId = $this->attributeIndexMetaId($database, $relatedTable, $twoWayKey); $this->tolerateMissing(fn () => $this->dbForProject->deleteDocument('attributes', $childMetaId)); $this->purgeTableCaches($database, $relatedTable, $dbForDatabases); @@ -1782,11 +1651,7 @@ class Appwrite extends Destination $this->dbForProject->purgeCachedDocument($this->databaseCollectionId($database), $table->getId()); } - /** - * Swallows deletion errors — a prior interrupted run (or parent-side - * cascade via utopia-php/database relationship handling) may already - * have removed the target. - */ + /** Swallows deletion errors — a prior run or relationship cascade may have already removed the target. */ private function tolerateMissing(callable $fn): void { try { diff --git a/src/Migration/Destinations/OnDuplicate.php b/src/Migration/Destinations/OnDuplicate.php index 5c9b7fa411..744b2e1561 100644 --- a/src/Migration/Destinations/OnDuplicate.php +++ b/src/Migration/Destinations/OnDuplicate.php @@ -2,12 +2,6 @@ namespace Utopia\Migration\Destinations; -/** - * Outcome of {@see OnDuplicate::resolveSchemaAction()}. Declared alongside - * OnDuplicate because the two are designed together — any code that uses - * SchemaAction necessarily imports OnDuplicate (as the source of the - * decision), so the shared file satisfies autoloading in practice. - */ enum SchemaAction { case Create; @@ -31,19 +25,8 @@ enum OnDuplicate: string } /** - * Schema-level reconciliation decision. - * - * createdAt-different → the source-side resource was deleted+recreated, so - * it's a different physical incarnation. Destination should follow suit - * with DropAndRecreate (or UpdateInPlace if $canDrop is false — containers). - * - * Same createdAt + newer updatedAt → metadata-only edit on the same - * resource. UpdateInPlace; the caller checks whether the specific changed - * fields are SDK-updatable and falls back to DropAndRecreate if not. - * - * $canDrop = true → leaves (attributes, indexes) can be dropped. - * $canDrop = false → containers (databases, tables) get UpdateInPlace - * even on createdAt-different (drop would lose children). + * $canDrop = false (containers like databases/tables) forces UpdateInPlace + * even on createdAt-different — dropping would orphan children. */ public function resolveSchemaAction( bool $exists, @@ -87,10 +70,6 @@ enum OnDuplicate: string return SchemaAction::Tolerate; } - /** - * Whether source and destination have different physical createdAt values. - * Unknown (null/empty/zero-date) on either side → false. - */ private function createdAtDiffers(?string $source, ?string $dest): bool { $src = $this->parseTimestamp($source); @@ -98,10 +77,6 @@ enum OnDuplicate: string return $src !== null && $dst !== null && $src !== $dst; } - /** - * Whether source's timestamp is strictly newer than destination's. - * Unknown (null/empty/zero-date) on either side → false. - */ private function sourceIsNewer(?string $source, ?string $dest): bool { $src = $this->parseTimestamp($source); @@ -111,8 +86,7 @@ enum OnDuplicate: string /** * strtotime accepts '0000-00-00' leniently (returns a large negative epoch, - * not false), so non-positive epochs are rejected too. Null/empty/garbage - * → null so callers treat the comparison as unknown. + * not false), so non-positive epochs are rejected too. */ private function parseTimestamp(?string $value): ?int { From 75a1418f68035d0d73d944316854b876d0998d9f Mon Sep 17 00:00:00 2001 From: Torsten Dittmann Date: Mon, 27 Apr 2026 16:15:59 +0400 Subject: [PATCH 41/91] Downgrade utopia-php/storage to 0.* for compatibility --- composer.json | 2 +- composer.lock | 436 ++++++++++++++++++++++++++++++++++---------------- 2 files changed, 296 insertions(+), 142 deletions(-) diff --git a/composer.json b/composer.json index 5585f2a53f..72d4a7a068 100644 --- a/composer.json +++ b/composer.json @@ -27,7 +27,7 @@ "ext-openssl": "*", "appwrite/appwrite": "19.*", "utopia-php/database": "5.*", - "utopia-php/storage": "1.0.*", + "utopia-php/storage": "0.*", "utopia-php/dsn": "0.2.*", "halaxa/json-machine": "^1.2" }, diff --git a/composer.lock b/composer.lock index 1df76054f6..1ea510e148 100644 --- a/composer.lock +++ b/composer.lock @@ -4,7 +4,7 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "37980b9001fbbd4f213f3102c1332727", + "content-hash": "21b3b0c90a7d5ac554486cd4e54edfff", "packages": [ { "name": "appwrite/appwrite", @@ -187,23 +187,23 @@ }, { "name": "google/protobuf", - "version": "v4.33.5", + "version": "v4.33.6", "source": { "type": "git", "url": "https://github.com/protocolbuffers/protobuf-php.git", - "reference": "ebe8010a61b2ae0cff0d246fe1c4d44e9f7dfa6d" + "reference": "84b008c23915ed94536737eae46f41ba3bccfe67" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/protocolbuffers/protobuf-php/zipball/ebe8010a61b2ae0cff0d246fe1c4d44e9f7dfa6d", - "reference": "ebe8010a61b2ae0cff0d246fe1c4d44e9f7dfa6d", + "url": "https://api.github.com/repos/protocolbuffers/protobuf-php/zipball/84b008c23915ed94536737eae46f41ba3bccfe67", + "reference": "84b008c23915ed94536737eae46f41ba3bccfe67", "shasum": "" }, "require": { "php": ">=8.1.0" }, "require-dev": { - "phpunit/phpunit": ">=5.0.0 <8.5.27" + "phpunit/phpunit": ">=10.5.62 <11.0.0" }, "suggest": { "ext-bcmath": "Need to support JSON deserialization" @@ -225,9 +225,9 @@ "proto" ], "support": { - "source": "https://github.com/protocolbuffers/protobuf-php/tree/v4.33.5" + "source": "https://github.com/protocolbuffers/protobuf-php/tree/v4.33.6" }, - "time": "2026-01-29T20:49:00+00:00" + "time": "2026-03-18T17:32:05+00:00" }, { "name": "halaxa/json-machine", @@ -514,16 +514,16 @@ }, { "name": "open-telemetry/api", - "version": "1.8.0", + "version": "1.9.0", "source": { "type": "git", "url": "https://github.com/opentelemetry-php/api.git", - "reference": "df5197c6fd0ddd8e9883b87de042d9341300e2ad" + "reference": "6f8d237ce2c304ca85f31970f788e7f074d147be" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/opentelemetry-php/api/zipball/df5197c6fd0ddd8e9883b87de042d9341300e2ad", - "reference": "df5197c6fd0ddd8e9883b87de042d9341300e2ad", + "url": "https://api.github.com/repos/opentelemetry-php/api/zipball/6f8d237ce2c304ca85f31970f788e7f074d147be", + "reference": "6f8d237ce2c304ca85f31970f788e7f074d147be", "shasum": "" }, "require": { @@ -580,20 +580,20 @@ "issues": "https://github.com/open-telemetry/opentelemetry-php/issues", "source": "https://github.com/open-telemetry/opentelemetry-php" }, - "time": "2026-01-21T04:14:03+00:00" + "time": "2026-02-25T13:24:05+00:00" }, { "name": "open-telemetry/context", - "version": "1.4.0", + "version": "1.5.0", "source": { "type": "git", "url": "https://github.com/opentelemetry-php/context.git", - "reference": "d4c4470b541ce72000d18c339cfee633e4c8e0cf" + "reference": "3c414b246e0dabb7d6145404e6a5e4536ca18d07" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/opentelemetry-php/context/zipball/d4c4470b541ce72000d18c339cfee633e4c8e0cf", - "reference": "d4c4470b541ce72000d18c339cfee633e4c8e0cf", + "url": "https://api.github.com/repos/opentelemetry-php/context/zipball/3c414b246e0dabb7d6145404e6a5e4536ca18d07", + "reference": "3c414b246e0dabb7d6145404e6a5e4536ca18d07", "shasum": "" }, "require": { @@ -635,11 +635,11 @@ ], "support": { "chat": "https://app.slack.com/client/T08PSQ7BQ/C01NFPCV44V", - "docs": "https://opentelemetry.io/docs/php", + "docs": "https://opentelemetry.io/docs/languages/php", "issues": "https://github.com/open-telemetry/opentelemetry-php/issues", "source": "https://github.com/open-telemetry/opentelemetry-php" }, - "time": "2025-09-19T00:05:49+00:00" + "time": "2025-10-19T06:44:33+00:00" }, { "name": "open-telemetry/exporter-otlp", @@ -707,16 +707,16 @@ }, { "name": "open-telemetry/gen-otlp-protobuf", - "version": "1.8.0", + "version": "1.9.0", "source": { "type": "git", "url": "https://github.com/opentelemetry-php/gen-otlp-protobuf.git", - "reference": "673af5b06545b513466081884b47ef15a536edde" + "reference": "a229cf161d42001d64c8f21e8f678581fe1c66b9" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/opentelemetry-php/gen-otlp-protobuf/zipball/673af5b06545b513466081884b47ef15a536edde", - "reference": "673af5b06545b513466081884b47ef15a536edde", + "url": "https://api.github.com/repos/opentelemetry-php/gen-otlp-protobuf/zipball/a229cf161d42001d64c8f21e8f678581fe1c66b9", + "reference": "a229cf161d42001d64c8f21e8f678581fe1c66b9", "shasum": "" }, "require": { @@ -762,30 +762,30 @@ ], "support": { "chat": "https://app.slack.com/client/T08PSQ7BQ/C01NFPCV44V", - "docs": "https://opentelemetry.io/docs/php", + "docs": "https://opentelemetry.io/docs/languages/php", "issues": "https://github.com/open-telemetry/opentelemetry-php/issues", "source": "https://github.com/open-telemetry/opentelemetry-php" }, - "time": "2025-09-17T23:10:12+00:00" + "time": "2025-10-19T06:44:33+00:00" }, { "name": "open-telemetry/sdk", - "version": "1.13.0", + "version": "1.14.0", "source": { "type": "git", "url": "https://github.com/opentelemetry-php/sdk.git", - "reference": "c76f91203bf7ef98ab3f4e0a82ca21699af185e1" + "reference": "6e3d0ce93e76555dd5e2f1d19443ff45b990e410" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/opentelemetry-php/sdk/zipball/c76f91203bf7ef98ab3f4e0a82ca21699af185e1", - "reference": "c76f91203bf7ef98ab3f4e0a82ca21699af185e1", + "url": "https://api.github.com/repos/opentelemetry-php/sdk/zipball/6e3d0ce93e76555dd5e2f1d19443ff45b990e410", + "reference": "6e3d0ce93e76555dd5e2f1d19443ff45b990e410", "shasum": "" }, "require": { "ext-json": "*", "nyholm/psr7-server": "^1.1", - "open-telemetry/api": "^1.7", + "open-telemetry/api": "^1.8", "open-telemetry/context": "^1.4", "open-telemetry/sem-conv": "^1.0", "php": "^8.1", @@ -863,7 +863,7 @@ "issues": "https://github.com/open-telemetry/opentelemetry-php/issues", "source": "https://github.com/open-telemetry/opentelemetry-php" }, - "time": "2026-01-28T11:38:11+00:00" + "time": "2026-03-21T11:50:01+00:00" }, { "name": "open-telemetry/sem-conv", @@ -1487,16 +1487,16 @@ }, { "name": "symfony/http-client", - "version": "v7.4.5", + "version": "v7.4.8", "source": { "type": "git", "url": "https://github.com/symfony/http-client.git", - "reference": "84bb634857a893cc146cceb467e31b3f02c5fe9f" + "reference": "01933e626c3de76bea1e22641e205e78f6a34342" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/symfony/http-client/zipball/84bb634857a893cc146cceb467e31b3f02c5fe9f", - "reference": "84bb634857a893cc146cceb467e31b3f02c5fe9f", + "url": "https://api.github.com/repos/symfony/http-client/zipball/01933e626c3de76bea1e22641e205e78f6a34342", + "reference": "01933e626c3de76bea1e22641e205e78f6a34342", "shasum": "" }, "require": { @@ -1564,7 +1564,7 @@ "http" ], "support": { - "source": "https://github.com/symfony/http-client/tree/v7.4.5" + "source": "https://github.com/symfony/http-client/tree/v7.4.8" }, "funding": [ { @@ -1584,7 +1584,7 @@ "type": "tidelift" } ], - "time": "2026-01-27T16:16:02+00:00" + "time": "2026-03-30T12:55:43+00:00" }, { "name": "symfony/http-client-contracts", @@ -1666,16 +1666,16 @@ }, { "name": "symfony/polyfill-mbstring", - "version": "v1.33.0", + "version": "v1.37.0", "source": { "type": "git", "url": "https://github.com/symfony/polyfill-mbstring.git", - "reference": "6d857f4d76bd4b343eac26d6b539585d2bc56493" + "reference": "6a21eb99c6973357967f6ce3708cd55a6bec6315" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/symfony/polyfill-mbstring/zipball/6d857f4d76bd4b343eac26d6b539585d2bc56493", - "reference": "6d857f4d76bd4b343eac26d6b539585d2bc56493", + "url": "https://api.github.com/repos/symfony/polyfill-mbstring/zipball/6a21eb99c6973357967f6ce3708cd55a6bec6315", + "reference": "6a21eb99c6973357967f6ce3708cd55a6bec6315", "shasum": "" }, "require": { @@ -1727,7 +1727,7 @@ "shim" ], "support": { - "source": "https://github.com/symfony/polyfill-mbstring/tree/v1.33.0" + "source": "https://github.com/symfony/polyfill-mbstring/tree/v1.37.0" }, "funding": [ { @@ -1747,20 +1747,20 @@ "type": "tidelift" } ], - "time": "2024-12-23T08:48:59+00:00" + "time": "2026-04-10T17:25:58+00:00" }, { "name": "symfony/polyfill-php82", - "version": "v1.33.0", + "version": "v1.37.0", "source": { "type": "git", "url": "https://github.com/symfony/polyfill-php82.git", - "reference": "5d2ed36f7734637dacc025f179698031951b1692" + "reference": "34808efe3e68f69685796f7c253a2f1d8ea9df59" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/symfony/polyfill-php82/zipball/5d2ed36f7734637dacc025f179698031951b1692", - "reference": "5d2ed36f7734637dacc025f179698031951b1692", + "url": "https://api.github.com/repos/symfony/polyfill-php82/zipball/34808efe3e68f69685796f7c253a2f1d8ea9df59", + "reference": "34808efe3e68f69685796f7c253a2f1d8ea9df59", "shasum": "" }, "require": { @@ -1807,7 +1807,7 @@ "shim" ], "support": { - "source": "https://github.com/symfony/polyfill-php82/tree/v1.33.0" + "source": "https://github.com/symfony/polyfill-php82/tree/v1.37.0" }, "funding": [ { @@ -1827,20 +1827,20 @@ "type": "tidelift" } ], - "time": "2024-09-09T11:45:10+00:00" + "time": "2026-04-10T16:19:22+00:00" }, { "name": "symfony/polyfill-php83", - "version": "v1.33.0", + "version": "v1.37.0", "source": { "type": "git", "url": "https://github.com/symfony/polyfill-php83.git", - "reference": "17f6f9a6b1735c0f163024d959f700cfbc5155e5" + "reference": "3600c2cb22399e25bb226e4a135ce91eeb2a6149" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/symfony/polyfill-php83/zipball/17f6f9a6b1735c0f163024d959f700cfbc5155e5", - "reference": "17f6f9a6b1735c0f163024d959f700cfbc5155e5", + "url": "https://api.github.com/repos/symfony/polyfill-php83/zipball/3600c2cb22399e25bb226e4a135ce91eeb2a6149", + "reference": "3600c2cb22399e25bb226e4a135ce91eeb2a6149", "shasum": "" }, "require": { @@ -1887,7 +1887,7 @@ "shim" ], "support": { - "source": "https://github.com/symfony/polyfill-php83/tree/v1.33.0" + "source": "https://github.com/symfony/polyfill-php83/tree/v1.37.0" }, "funding": [ { @@ -1907,20 +1907,20 @@ "type": "tidelift" } ], - "time": "2025-07-08T02:45:35+00:00" + "time": "2026-04-10T17:25:58+00:00" }, { "name": "symfony/polyfill-php85", - "version": "v1.33.0", + "version": "v1.37.0", "source": { "type": "git", "url": "https://github.com/symfony/polyfill-php85.git", - "reference": "d4e5fcd4ab3d998ab16c0db48e6cbb9a01993f91" + "reference": "fcfa4973a9917cef23f2e38774da74a2b7d115ee" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/symfony/polyfill-php85/zipball/d4e5fcd4ab3d998ab16c0db48e6cbb9a01993f91", - "reference": "d4e5fcd4ab3d998ab16c0db48e6cbb9a01993f91", + "url": "https://api.github.com/repos/symfony/polyfill-php85/zipball/fcfa4973a9917cef23f2e38774da74a2b7d115ee", + "reference": "fcfa4973a9917cef23f2e38774da74a2b7d115ee", "shasum": "" }, "require": { @@ -1967,7 +1967,7 @@ "shim" ], "support": { - "source": "https://github.com/symfony/polyfill-php85/tree/v1.33.0" + "source": "https://github.com/symfony/polyfill-php85/tree/v1.37.0" }, "funding": [ { @@ -1987,7 +1987,7 @@ "type": "tidelift" } ], - "time": "2025-06-23T16:12:55+00:00" + "time": "2026-04-26T13:10:57+00:00" }, { "name": "symfony/service-contracts", @@ -2130,16 +2130,16 @@ }, { "name": "utopia-php/cache", - "version": "1.0.0", + "version": "1.0.1", "source": { "type": "git", "url": "https://github.com/utopia-php/cache.git", - "reference": "7068870c086a6aea16173563a26b93ef3e408439" + "reference": "05ceba981436a4022553f7aaa2a05fa049d0f71c" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/cache/zipball/7068870c086a6aea16173563a26b93ef3e408439", - "reference": "7068870c086a6aea16173563a26b93ef3e408439", + "url": "https://api.github.com/repos/utopia-php/cache/zipball/05ceba981436a4022553f7aaa2a05fa049d0f71c", + "reference": "05ceba981436a4022553f7aaa2a05fa049d0f71c", "shasum": "" }, "require": { @@ -2176,9 +2176,9 @@ ], "support": { "issues": "https://github.com/utopia-php/cache/issues", - "source": "https://github.com/utopia-php/cache/tree/1.0.0" + "source": "https://github.com/utopia-php/cache/tree/1.0.1" }, - "time": "2026-01-28T10:55:44+00:00" + "time": "2026-03-12T03:39:09+00:00" }, { "name": "utopia-php/console", @@ -2287,6 +2287,54 @@ }, "time": "2026-04-20T07:12:46+00:00" }, + { + "name": "utopia-php/di", + "version": "0.1.0", + "source": { + "type": "git", + "url": "https://github.com/utopia-php/di.git", + "reference": "22490c95f7ac3898ed1c33f1b1b5dd577305ee31" + }, + "dist": { + "type": "zip", + "url": "https://api.github.com/repos/utopia-php/di/zipball/22490c95f7ac3898ed1c33f1b1b5dd577305ee31", + "reference": "22490c95f7ac3898ed1c33f1b1b5dd577305ee31", + "shasum": "" + }, + "require": { + "php": ">=8.2" + }, + "require-dev": { + "laravel/pint": "^1.2", + "phpbench/phpbench": "^1.2", + "phpstan/phpstan": "^1.10", + "phpunit/phpunit": "^9.5.25", + "swoole/ide-helper": "4.8.3" + }, + "type": "library", + "autoload": { + "psr-4": { + "Utopia\\": "src/", + "Tests\\E2E\\": "tests/e2e" + } + }, + "notification-url": "https://packagist.org/downloads/", + "license": [ + "MIT" + ], + "description": "A simple and lite library for managing dependency injections", + "keywords": [ + "framework", + "http", + "php", + "upf" + ], + "support": { + "issues": "https://github.com/utopia-php/di/issues", + "source": "https://github.com/utopia-php/di/tree/0.1.0" + }, + "time": "2024-08-08T14:35:19+00:00" + }, { "name": "utopia-php/dsn", "version": "0.2.1", @@ -2335,17 +2383,67 @@ "time": "2024-05-07T02:01:25+00:00" }, { - "name": "utopia-php/mongo", - "version": "1.0.0", + "name": "utopia-php/framework", + "version": "1.0.2", "source": { "type": "git", - "url": "https://github.com/utopia-php/mongo.git", - "reference": "45bedf36c2c946ec7a0a3e59b9f12f772de0b01d" + "url": "https://github.com/utopia-php/http.git", + "reference": "fc63ec61c720190a5ea5bb484c615145850951e6" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/mongo/zipball/45bedf36c2c946ec7a0a3e59b9f12f772de0b01d", - "reference": "45bedf36c2c946ec7a0a3e59b9f12f772de0b01d", + "url": "https://api.github.com/repos/utopia-php/http/zipball/fc63ec61c720190a5ea5bb484c615145850951e6", + "reference": "fc63ec61c720190a5ea5bb484c615145850951e6", + "shasum": "" + }, + "require": { + "ext-swoole": "*", + "php": ">=8.0", + "utopia-php/servers": "0.1.*" + }, + "require-dev": { + "ext-xdebug": "*", + "laravel/pint": "^1.2", + "phpbench/phpbench": "^1.2", + "phpstan/phpstan": "^1.10", + "phpunit/phpunit": "^9.5.25", + "swoole/ide-helper": "4.8.3" + }, + "type": "library", + "autoload": { + "psr-4": { + "Utopia\\": "src/" + } + }, + "notification-url": "https://packagist.org/downloads/", + "license": [ + "MIT" + ], + "description": "A simple, light and advanced PHP HTTP framework", + "keywords": [ + "framework", + "http", + "php", + "upf" + ], + "support": { + "issues": "https://github.com/utopia-php/http/issues", + "source": "https://github.com/utopia-php/http/tree/1.0.2" + }, + "time": "2024-09-10T09:04:19+00:00" + }, + { + "name": "utopia-php/mongo", + "version": "1.1.0", + "source": { + "type": "git", + "url": "https://github.com/utopia-php/mongo.git", + "reference": "73593682deee4696525a04e26524c1c1226e1530" + }, + "dist": { + "type": "zip", + "url": "https://api.github.com/repos/utopia-php/mongo/zipball/73593682deee4696525a04e26524c1c1226e1530", + "reference": "73593682deee4696525a04e26524c1c1226e1530", "shasum": "" }, "require": { @@ -2391,22 +2489,22 @@ ], "support": { "issues": "https://github.com/utopia-php/mongo/issues", - "source": "https://github.com/utopia-php/mongo/tree/1.0.0" + "source": "https://github.com/utopia-php/mongo/tree/1.1.0" }, - "time": "2026-02-12T05:54:06+00:00" + "time": "2026-04-24T06:15:10+00:00" }, { "name": "utopia-php/pools", - "version": "1.0.2", + "version": "1.0.3", "source": { "type": "git", "url": "https://github.com/utopia-php/pools.git", - "reference": "b7d8dd00306cdd8bf3ff6f1dc90caeaf27dabeb1" + "reference": "74de7c5457a2c447f27e7ec4d72e8412a7d68c10" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/pools/zipball/b7d8dd00306cdd8bf3ff6f1dc90caeaf27dabeb1", - "reference": "b7d8dd00306cdd8bf3ff6f1dc90caeaf27dabeb1", + "url": "https://api.github.com/repos/utopia-php/pools/zipball/74de7c5457a2c447f27e7ec4d72e8412a7d68c10", + "reference": "74de7c5457a2c447f27e7ec4d72e8412a7d68c10", "shasum": "" }, "require": { @@ -2444,33 +2542,88 @@ ], "support": { "issues": "https://github.com/utopia-php/pools/issues", - "source": "https://github.com/utopia-php/pools/tree/1.0.2" + "source": "https://github.com/utopia-php/pools/tree/1.0.3" }, - "time": "2026-01-28T13:12:36+00:00" + "time": "2026-02-26T08:42:40+00:00" }, { - "name": "utopia-php/storage", - "version": "1.0.0", + "name": "utopia-php/servers", + "version": "0.1.1", "source": { "type": "git", - "url": "https://github.com/utopia-php/storage.git", - "reference": "f672e8865938e5d1d6dc3bd149ceba4e5582199e" + "url": "https://github.com/utopia-php/servers.git", + "reference": "fd5c8d32778f265256c1936372a071b944f5ba8a" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/storage/zipball/f672e8865938e5d1d6dc3bd149ceba4e5582199e", - "reference": "f672e8865938e5d1d6dc3bd149ceba4e5582199e", + "url": "https://api.github.com/repos/utopia-php/servers/zipball/fd5c8d32778f265256c1936372a071b944f5ba8a", + "reference": "fd5c8d32778f265256c1936372a071b944f5ba8a", "shasum": "" }, "require": { - "ext-curl": "*", + "php": ">=8.0", + "utopia-php/di": "0.1.*" + }, + "require-dev": { + "laravel/pint": "^0.2.3", + "phpstan/phpstan": "^1.8", + "phpunit/phpunit": "^9.5.5" + }, + "type": "library", + "autoload": { + "psr-4": { + "Utopia\\Servers\\": "src/Servers" + } + }, + "notification-url": "https://packagist.org/downloads/", + "license": [ + "MIT" + ], + "authors": [ + { + "name": "Team Appwrite", + "email": "team@appwrite.io" + } + ], + "description": "A base library for building Utopia style servers.", + "keywords": [ + "framework", + "php", + "servers", + "upf", + "utopia" + ], + "support": { + "issues": "https://github.com/utopia-php/servers/issues", + "source": "https://github.com/utopia-php/servers/tree/0.1.1" + }, + "time": "2024-09-06T02:25:56+00:00" + }, + { + "name": "utopia-php/storage", + "version": "0.19.2", + "source": { + "type": "git", + "url": "https://github.com/utopia-php/storage.git", + "reference": "fdae7bf8d01c1ad735e45ae519bd65970becbde8" + }, + "dist": { + "type": "zip", + "url": "https://api.github.com/repos/utopia-php/storage/zipball/fdae7bf8d01c1ad735e45ae519bd65970becbde8", + "reference": "fdae7bf8d01c1ad735e45ae519bd65970becbde8", + "shasum": "" + }, + "require": { + "ext-brotli": "*", "ext-fileinfo": "*", - "ext-simplexml": "*", + "ext-lz4": "*", + "ext-snappy": "*", + "ext-xz": "*", "ext-zlib": "*", - "php": ">=8.1", - "utopia-php/system": "0.*.*", - "utopia-php/telemetry": "0.2.*", - "utopia-php/validators": "0.2.*" + "ext-zstd": "*", + "php": ">=8.0", + "utopia-php/framework": "1.0.*", + "utopia-php/system": "0.9.*" }, "require-dev": { "laravel/pint": "1.2.*", @@ -2497,22 +2650,22 @@ ], "support": { "issues": "https://github.com/utopia-php/storage/issues", - "source": "https://github.com/utopia-php/storage/tree/1.0.0" + "source": "https://github.com/utopia-php/storage/tree/0.19.2" }, - "time": "2026-02-17T04:37:10+00:00" + "time": "2024-11-06T09:34:30+00:00" }, { "name": "utopia-php/system", - "version": "0.10.0", + "version": "0.9.0", "source": { "type": "git", "url": "https://github.com/utopia-php/system.git", - "reference": "6441a9c180958a373e5ddb330264dd638539dfdb" + "reference": "8e4a7edaf2dfeb4c9524e9f766d27754f2c4b64d" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/system/zipball/6441a9c180958a373e5ddb330264dd638539dfdb", - "reference": "6441a9c180958a373e5ddb330264dd638539dfdb", + "url": "https://api.github.com/repos/utopia-php/system/zipball/8e4a7edaf2dfeb4c9524e9f766d27754f2c4b64d", + "reference": "8e4a7edaf2dfeb4c9524e9f766d27754f2c4b64d", "shasum": "" }, "require": { @@ -2520,7 +2673,7 @@ }, "require-dev": { "laravel/pint": "1.13.*", - "phpstan/phpstan": "1.12.*", + "phpstan/phpstan": "1.10.*", "phpunit/phpunit": "9.6.*" }, "type": "library", @@ -2553,22 +2706,22 @@ ], "support": { "issues": "https://github.com/utopia-php/system/issues", - "source": "https://github.com/utopia-php/system/tree/0.10.0" + "source": "https://github.com/utopia-php/system/tree/0.9.0" }, - "time": "2025-10-15T19:12:00+00:00" + "time": "2024-10-09T14:44:01+00:00" }, { "name": "utopia-php/telemetry", - "version": "0.2.0", + "version": "0.3.0", "source": { "type": "git", "url": "https://github.com/utopia-php/telemetry.git", - "reference": "9997ebf59bb77920a7223ad73d834a76b09152c3" + "reference": "62bbadad03e593b071b8ca63fac2c117c1900991" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/telemetry/zipball/9997ebf59bb77920a7223ad73d834a76b09152c3", - "reference": "9997ebf59bb77920a7223ad73d834a76b09152c3", + "url": "https://api.github.com/repos/utopia-php/telemetry/zipball/62bbadad03e593b071b8ca63fac2c117c1900991", + "reference": "62bbadad03e593b071b8ca63fac2c117c1900991", "shasum": "" }, "require": { @@ -2608,9 +2761,9 @@ ], "support": { "issues": "https://github.com/utopia-php/telemetry/issues", - "source": "https://github.com/utopia-php/telemetry/tree/0.2.0" + "source": "https://github.com/utopia-php/telemetry/tree/0.3.0" }, - "time": "2025-12-17T07:56:38+00:00" + "time": "2026-04-01T13:52:56+00:00" }, { "name": "utopia-php/validators", @@ -2723,16 +2876,16 @@ }, { "name": "laravel/pint", - "version": "v1.27.1", + "version": "v1.29.1", "source": { "type": "git", "url": "https://github.com/laravel/pint.git", - "reference": "54cca2de13790570c7b6f0f94f37896bee4abcb5" + "reference": "0770e9b7fafd50d4586881d456d6eb41c9247a80" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/laravel/pint/zipball/54cca2de13790570c7b6f0f94f37896bee4abcb5", - "reference": "54cca2de13790570c7b6f0f94f37896bee4abcb5", + "url": "https://api.github.com/repos/laravel/pint/zipball/0770e9b7fafd50d4586881d456d6eb41c9247a80", + "reference": "0770e9b7fafd50d4586881d456d6eb41c9247a80", "shasum": "" }, "require": { @@ -2743,13 +2896,14 @@ "php": "^8.2.0" }, "require-dev": { - "friendsofphp/php-cs-fixer": "^3.93.1", - "illuminate/view": "^12.51.0", - "larastan/larastan": "^3.9.2", - "laravel-zero/framework": "^12.0.5", + "friendsofphp/php-cs-fixer": "^3.95.1", + "illuminate/view": "^12.56.0", + "larastan/larastan": "^3.9.6", + "laravel-zero/framework": "^12.1.0", "mockery/mockery": "^1.6.12", - "nunomaduro/termwind": "^2.3.3", - "pestphp/pest": "^3.8.5" + "nunomaduro/termwind": "^2.4.0", + "pestphp/pest": "^3.8.6", + "shipfastlabs/agent-detector": "^1.1.3" }, "bin": [ "builds/pint" @@ -2786,7 +2940,7 @@ "issues": "https://github.com/laravel/pint/issues", "source": "https://github.com/laravel/pint" }, - "time": "2026-02-10T20:00:20+00:00" + "time": "2026-04-20T15:26:14+00:00" }, { "name": "myclabs/deep-copy", @@ -3101,11 +3255,11 @@ }, { "name": "phpstan/phpstan", - "version": "1.12.32", + "version": "1.12.33", "dist": { "type": "zip", - "url": "https://api.github.com/repos/phpstan/phpstan/zipball/2770dcdf5078d0b0d53f94317e06affe88419aa8", - "reference": "2770dcdf5078d0b0d53f94317e06affe88419aa8", + "url": "https://api.github.com/repos/phpstan/phpstan/zipball/37982d6fc7cbb746dda7773530cda557cdf119e1", + "reference": "37982d6fc7cbb746dda7773530cda557cdf119e1", "shasum": "" }, "require": { @@ -3150,7 +3304,7 @@ "type": "github" } ], - "time": "2025-09-30T10:16:31+00:00" + "time": "2026-02-28T20:30:03+00:00" }, { "name": "phpunit/php-code-coverage", @@ -3501,16 +3655,16 @@ }, { "name": "phpunit/phpunit", - "version": "11.5.53", + "version": "11.5.55", "source": { "type": "git", "url": "https://github.com/sebastianbergmann/phpunit.git", - "reference": "a997a653a82845f1240d73ee73a8a4e97e4b0607" + "reference": "adc7262fccc12de2b30f12a8aa0b33775d814f00" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/sebastianbergmann/phpunit/zipball/a997a653a82845f1240d73ee73a8a4e97e4b0607", - "reference": "a997a653a82845f1240d73ee73a8a4e97e4b0607", + "url": "https://api.github.com/repos/sebastianbergmann/phpunit/zipball/adc7262fccc12de2b30f12a8aa0b33775d814f00", + "reference": "adc7262fccc12de2b30f12a8aa0b33775d814f00", "shasum": "" }, "require": { @@ -3583,7 +3737,7 @@ "support": { "issues": "https://github.com/sebastianbergmann/phpunit/issues", "security": "https://github.com/sebastianbergmann/phpunit/security/policy", - "source": "https://github.com/sebastianbergmann/phpunit/tree/11.5.53" + "source": "https://github.com/sebastianbergmann/phpunit/tree/11.5.55" }, "funding": [ { @@ -3607,7 +3761,7 @@ "type": "tidelift" } ], - "time": "2026-02-10T12:28:25+00:00" + "time": "2026-02-18T12:37:06+00:00" }, { "name": "sebastian/cli-parser", @@ -4649,16 +4803,16 @@ }, { "name": "symfony/polyfill-ctype", - "version": "v1.33.0", + "version": "v1.37.0", "source": { "type": "git", "url": "https://github.com/symfony/polyfill-ctype.git", - "reference": "a3cc8b044a6ea513310cbd48ef7333b384945638" + "reference": "141046a8f9477948ff284fa65be2095baafb94f2" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/symfony/polyfill-ctype/zipball/a3cc8b044a6ea513310cbd48ef7333b384945638", - "reference": "a3cc8b044a6ea513310cbd48ef7333b384945638", + "url": "https://api.github.com/repos/symfony/polyfill-ctype/zipball/141046a8f9477948ff284fa65be2095baafb94f2", + "reference": "141046a8f9477948ff284fa65be2095baafb94f2", "shasum": "" }, "require": { @@ -4708,7 +4862,7 @@ "portable" ], "support": { - "source": "https://github.com/symfony/polyfill-ctype/tree/v1.33.0" + "source": "https://github.com/symfony/polyfill-ctype/tree/v1.37.0" }, "funding": [ { @@ -4728,20 +4882,20 @@ "type": "tidelift" } ], - "time": "2024-09-09T11:45:10+00:00" + "time": "2026-04-10T16:19:22+00:00" }, { "name": "symfony/polyfill-php80", - "version": "v1.33.0", + "version": "v1.37.0", "source": { "type": "git", "url": "https://github.com/symfony/polyfill-php80.git", - "reference": "0cc9dd0f17f61d8131e7df6b84bd344899fe2608" + "reference": "dfb55726c3a76ea3b6459fcfda1ec2d80a682411" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/symfony/polyfill-php80/zipball/0cc9dd0f17f61d8131e7df6b84bd344899fe2608", - "reference": "0cc9dd0f17f61d8131e7df6b84bd344899fe2608", + "url": "https://api.github.com/repos/symfony/polyfill-php80/zipball/dfb55726c3a76ea3b6459fcfda1ec2d80a682411", + "reference": "dfb55726c3a76ea3b6459fcfda1ec2d80a682411", "shasum": "" }, "require": { @@ -4792,7 +4946,7 @@ "shim" ], "support": { - "source": "https://github.com/symfony/polyfill-php80/tree/v1.33.0" + "source": "https://github.com/symfony/polyfill-php80/tree/v1.37.0" }, "funding": [ { @@ -4812,7 +4966,7 @@ "type": "tidelift" } ], - "time": "2025-01-02T08:10:11+00:00" + "time": "2026-04-10T16:19:22+00:00" }, { "name": "theseer/tokenizer", From bf50409cbd59b2df6adae765359d2e74ed10fe57 Mon Sep 17 00:00:00 2001 From: Torsten Dittmann Date: Mon, 27 Apr 2026 16:27:41 +0400 Subject: [PATCH 42/91] Update utopia-php/storage to 2.* --- composer.json | 2 +- composer.lock | 238 +++++++++----------------------------------------- 2 files changed, 42 insertions(+), 198 deletions(-) diff --git a/composer.json b/composer.json index 72d4a7a068..a52b23a9b6 100644 --- a/composer.json +++ b/composer.json @@ -27,7 +27,7 @@ "ext-openssl": "*", "appwrite/appwrite": "19.*", "utopia-php/database": "5.*", - "utopia-php/storage": "0.*", + "utopia-php/storage": "2.*", "utopia-php/dsn": "0.2.*", "halaxa/json-machine": "^1.2" }, diff --git a/composer.lock b/composer.lock index 1ea510e148..5878a44542 100644 --- a/composer.lock +++ b/composer.lock @@ -4,7 +4,7 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "21b3b0c90a7d5ac554486cd4e54edfff", + "content-hash": "38981f8df096cfbc9dd34487643b7ed6", "packages": [ { "name": "appwrite/appwrite", @@ -2287,54 +2287,6 @@ }, "time": "2026-04-20T07:12:46+00:00" }, - { - "name": "utopia-php/di", - "version": "0.1.0", - "source": { - "type": "git", - "url": "https://github.com/utopia-php/di.git", - "reference": "22490c95f7ac3898ed1c33f1b1b5dd577305ee31" - }, - "dist": { - "type": "zip", - "url": "https://api.github.com/repos/utopia-php/di/zipball/22490c95f7ac3898ed1c33f1b1b5dd577305ee31", - "reference": "22490c95f7ac3898ed1c33f1b1b5dd577305ee31", - "shasum": "" - }, - "require": { - "php": ">=8.2" - }, - "require-dev": { - "laravel/pint": "^1.2", - "phpbench/phpbench": "^1.2", - "phpstan/phpstan": "^1.10", - "phpunit/phpunit": "^9.5.25", - "swoole/ide-helper": "4.8.3" - }, - "type": "library", - "autoload": { - "psr-4": { - "Utopia\\": "src/", - "Tests\\E2E\\": "tests/e2e" - } - }, - "notification-url": "https://packagist.org/downloads/", - "license": [ - "MIT" - ], - "description": "A simple and lite library for managing dependency injections", - "keywords": [ - "framework", - "http", - "php", - "upf" - ], - "support": { - "issues": "https://github.com/utopia-php/di/issues", - "source": "https://github.com/utopia-php/di/tree/0.1.0" - }, - "time": "2024-08-08T14:35:19+00:00" - }, { "name": "utopia-php/dsn", "version": "0.2.1", @@ -2382,56 +2334,6 @@ }, "time": "2024-05-07T02:01:25+00:00" }, - { - "name": "utopia-php/framework", - "version": "1.0.2", - "source": { - "type": "git", - "url": "https://github.com/utopia-php/http.git", - "reference": "fc63ec61c720190a5ea5bb484c615145850951e6" - }, - "dist": { - "type": "zip", - "url": "https://api.github.com/repos/utopia-php/http/zipball/fc63ec61c720190a5ea5bb484c615145850951e6", - "reference": "fc63ec61c720190a5ea5bb484c615145850951e6", - "shasum": "" - }, - "require": { - "ext-swoole": "*", - "php": ">=8.0", - "utopia-php/servers": "0.1.*" - }, - "require-dev": { - "ext-xdebug": "*", - "laravel/pint": "^1.2", - "phpbench/phpbench": "^1.2", - "phpstan/phpstan": "^1.10", - "phpunit/phpunit": "^9.5.25", - "swoole/ide-helper": "4.8.3" - }, - "type": "library", - "autoload": { - "psr-4": { - "Utopia\\": "src/" - } - }, - "notification-url": "https://packagist.org/downloads/", - "license": [ - "MIT" - ], - "description": "A simple, light and advanced PHP HTTP framework", - "keywords": [ - "framework", - "http", - "php", - "upf" - ], - "support": { - "issues": "https://github.com/utopia-php/http/issues", - "source": "https://github.com/utopia-php/http/tree/1.0.2" - }, - "time": "2024-09-10T09:04:19+00:00" - }, { "name": "utopia-php/mongo", "version": "1.1.0", @@ -2546,89 +2448,33 @@ }, "time": "2026-02-26T08:42:40+00:00" }, - { - "name": "utopia-php/servers", - "version": "0.1.1", - "source": { - "type": "git", - "url": "https://github.com/utopia-php/servers.git", - "reference": "fd5c8d32778f265256c1936372a071b944f5ba8a" - }, - "dist": { - "type": "zip", - "url": "https://api.github.com/repos/utopia-php/servers/zipball/fd5c8d32778f265256c1936372a071b944f5ba8a", - "reference": "fd5c8d32778f265256c1936372a071b944f5ba8a", - "shasum": "" - }, - "require": { - "php": ">=8.0", - "utopia-php/di": "0.1.*" - }, - "require-dev": { - "laravel/pint": "^0.2.3", - "phpstan/phpstan": "^1.8", - "phpunit/phpunit": "^9.5.5" - }, - "type": "library", - "autoload": { - "psr-4": { - "Utopia\\Servers\\": "src/Servers" - } - }, - "notification-url": "https://packagist.org/downloads/", - "license": [ - "MIT" - ], - "authors": [ - { - "name": "Team Appwrite", - "email": "team@appwrite.io" - } - ], - "description": "A base library for building Utopia style servers.", - "keywords": [ - "framework", - "php", - "servers", - "upf", - "utopia" - ], - "support": { - "issues": "https://github.com/utopia-php/servers/issues", - "source": "https://github.com/utopia-php/servers/tree/0.1.1" - }, - "time": "2024-09-06T02:25:56+00:00" - }, { "name": "utopia-php/storage", - "version": "0.19.2", + "version": "2.0.0", "source": { "type": "git", "url": "https://github.com/utopia-php/storage.git", - "reference": "fdae7bf8d01c1ad735e45ae519bd65970becbde8" + "reference": "52d1f89a47165ef0d3deff63043cda182175adfb" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/storage/zipball/fdae7bf8d01c1ad735e45ae519bd65970becbde8", - "reference": "fdae7bf8d01c1ad735e45ae519bd65970becbde8", + "url": "https://api.github.com/repos/utopia-php/storage/zipball/52d1f89a47165ef0d3deff63043cda182175adfb", + "reference": "52d1f89a47165ef0d3deff63043cda182175adfb", "shasum": "" }, "require": { - "ext-brotli": "*", + "ext-curl": "*", "ext-fileinfo": "*", - "ext-lz4": "*", - "ext-snappy": "*", - "ext-xz": "*", + "ext-simplexml": "*", "ext-zlib": "*", - "ext-zstd": "*", - "php": ">=8.0", - "utopia-php/framework": "1.0.*", - "utopia-php/system": "0.9.*" + "php": ">=8.1", + "utopia-php/system": "0.*.*", + "utopia-php/telemetry": "0.2.*", + "utopia-php/validators": "0.2.*" }, "require-dev": { - "laravel/pint": "1.2.*", - "phpunit/phpunit": "^9.3", - "vimeo/psalm": "4.0.1" + "laravel/pint": "^1.21", + "phpunit/phpunit": "^9.3" }, "type": "library", "autoload": { @@ -2650,22 +2496,22 @@ ], "support": { "issues": "https://github.com/utopia-php/storage/issues", - "source": "https://github.com/utopia-php/storage/tree/0.19.2" + "source": "https://github.com/utopia-php/storage/tree/2.0.0" }, - "time": "2024-11-06T09:34:30+00:00" + "time": "2026-04-27T11:39:32+00:00" }, { "name": "utopia-php/system", - "version": "0.9.0", + "version": "0.10.1", "source": { "type": "git", "url": "https://github.com/utopia-php/system.git", - "reference": "8e4a7edaf2dfeb4c9524e9f766d27754f2c4b64d" + "reference": "7c1669533bb9c285de19191270c8c1439161a78a" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/system/zipball/8e4a7edaf2dfeb4c9524e9f766d27754f2c4b64d", - "reference": "8e4a7edaf2dfeb4c9524e9f766d27754f2c4b64d", + "url": "https://api.github.com/repos/utopia-php/system/zipball/7c1669533bb9c285de19191270c8c1439161a78a", + "reference": "7c1669533bb9c285de19191270c8c1439161a78a", "shasum": "" }, "require": { @@ -2673,7 +2519,7 @@ }, "require-dev": { "laravel/pint": "1.13.*", - "phpstan/phpstan": "1.10.*", + "phpstan/phpstan": "1.12.*", "phpunit/phpunit": "9.6.*" }, "type": "library", @@ -2706,22 +2552,22 @@ ], "support": { "issues": "https://github.com/utopia-php/system/issues", - "source": "https://github.com/utopia-php/system/tree/0.9.0" + "source": "https://github.com/utopia-php/system/tree/0.10.1" }, - "time": "2024-10-09T14:44:01+00:00" + "time": "2026-03-15T21:07:41+00:00" }, { "name": "utopia-php/telemetry", - "version": "0.3.0", + "version": "0.2.0", "source": { "type": "git", "url": "https://github.com/utopia-php/telemetry.git", - "reference": "62bbadad03e593b071b8ca63fac2c117c1900991" + "reference": "9997ebf59bb77920a7223ad73d834a76b09152c3" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/telemetry/zipball/62bbadad03e593b071b8ca63fac2c117c1900991", - "reference": "62bbadad03e593b071b8ca63fac2c117c1900991", + "url": "https://api.github.com/repos/utopia-php/telemetry/zipball/9997ebf59bb77920a7223ad73d834a76b09152c3", + "reference": "9997ebf59bb77920a7223ad73d834a76b09152c3", "shasum": "" }, "require": { @@ -2761,9 +2607,9 @@ ], "support": { "issues": "https://github.com/utopia-php/telemetry/issues", - "source": "https://github.com/utopia-php/telemetry/tree/0.3.0" + "source": "https://github.com/utopia-php/telemetry/tree/0.2.0" }, - "time": "2026-04-01T13:52:56+00:00" + "time": "2025-12-17T07:56:38+00:00" }, { "name": "utopia-php/validators", @@ -2876,16 +2722,16 @@ }, { "name": "laravel/pint", - "version": "v1.29.1", + "version": "v1.2.1", "source": { "type": "git", "url": "https://github.com/laravel/pint.git", - "reference": "0770e9b7fafd50d4586881d456d6eb41c9247a80" + "reference": "e60e2112ee779ce60f253695b273d1646a17d6f1" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/laravel/pint/zipball/0770e9b7fafd50d4586881d456d6eb41c9247a80", - "reference": "0770e9b7fafd50d4586881d456d6eb41c9247a80", + "url": "https://api.github.com/repos/laravel/pint/zipball/e60e2112ee779ce60f253695b273d1646a17d6f1", + "reference": "e60e2112ee779ce60f253695b273d1646a17d6f1", "shasum": "" }, "require": { @@ -2893,17 +2739,16 @@ "ext-mbstring": "*", "ext-tokenizer": "*", "ext-xml": "*", - "php": "^8.2.0" + "php": "^8.0" }, "require-dev": { - "friendsofphp/php-cs-fixer": "^3.95.1", - "illuminate/view": "^12.56.0", - "larastan/larastan": "^3.9.6", - "laravel-zero/framework": "^12.1.0", - "mockery/mockery": "^1.6.12", - "nunomaduro/termwind": "^2.4.0", - "pestphp/pest": "^3.8.6", - "shipfastlabs/agent-detector": "^1.1.3" + "friendsofphp/php-cs-fixer": "^3.11.0", + "illuminate/view": "^9.32.0", + "laravel-zero/framework": "^9.2.0", + "mockery/mockery": "^1.5.1", + "nunomaduro/larastan": "^2.2.0", + "nunomaduro/termwind": "^1.14.0", + "pestphp/pest": "^1.22.1" }, "bin": [ "builds/pint" @@ -2929,7 +2774,6 @@ "description": "An opinionated code formatter for PHP.", "homepage": "https://laravel.com", "keywords": [ - "dev", "format", "formatter", "lint", @@ -2940,7 +2784,7 @@ "issues": "https://github.com/laravel/pint/issues", "source": "https://github.com/laravel/pint" }, - "time": "2026-04-20T15:26:14+00:00" + "time": "2022-11-29T16:25:20+00:00" }, { "name": "myclabs/deep-copy", From 371ee48fb68a4cea92ea3e2624f77030f0519536 Mon Sep 17 00:00:00 2001 From: Torsten Dittmann Date: Mon, 27 Apr 2026 16:32:45 +0400 Subject: [PATCH 43/91] Apply code formatting --- src/Migration/Destinations/Appwrite.php | 5 +++-- src/Migration/Destinations/JSON.php | 1 - src/Migration/Resources/Sites/EnvVar.php | 1 - src/Migration/Sources/Appwrite.php | 6 +----- src/Migration/Sources/Appwrite/Reader.php | 1 - src/Migration/Sources/Firebase.php | 1 - 6 files changed, 4 insertions(+), 11 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index 893bf9879d..e9bbf2d33b 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -283,7 +283,6 @@ class Appwrite extends Destination $scope = 'sites.write'; $this->sites->create('', '', Framework::OTHER(), BuildRuntime::STATIC1()); } - } catch (AppwriteException $e) { if ($e->getCode() === 403) { throw new \Exception( @@ -1084,7 +1083,6 @@ class Appwrite extends Destination fn () => $dbForDatabases->createDocuments($collectionId, $this->rowBuffer) ), }; - } finally { $this->rowBuffer = []; } @@ -1141,6 +1139,7 @@ class Appwrite extends Destination 'none' => Compression::NONE(), 'gzip' => Compression::GZIP(), 'zstd' => Compression::ZSTD(), + // no break default => throw new \Exception('Invalid Compression: ' . $resource->getCompression(), Exception::CODE_VALIDATION), }; @@ -1464,6 +1463,7 @@ class Appwrite extends Destination 'bun-1.0' => Runtime::BUN10(), 'bun-1.1' => Runtime::BUN11(), 'go-1.23' => Runtime::GO123(), + // no break default => throw new \Exception('Invalid Runtime: ' . $resource->getRuntime(), Exception::CODE_VALIDATION), }; @@ -1683,6 +1683,7 @@ class Appwrite extends Destination 'flutter-3.29' => BuildRuntime::FLUTTER329(), 'flutter-3.32' => BuildRuntime::FLUTTER332(), 'flutter-3.35' => BuildRuntime::FLUTTER335(), + // no break default => throw new \Exception('Invalid Build Runtime: ' . $resource->getBuildRuntime(), Exception::CODE_VALIDATION), }; diff --git a/src/Migration/Destinations/JSON.php b/src/Migration/Destinations/JSON.php index 91016ef589..6660ab5a06 100644 --- a/src/Migration/Destinations/JSON.php +++ b/src/Migration/Destinations/JSON.php @@ -316,5 +316,4 @@ class JSON extends Destination return $this->convertValueToJSON($item); }, $value); } - } diff --git a/src/Migration/Resources/Sites/EnvVar.php b/src/Migration/Resources/Sites/EnvVar.php index 78fce7e18b..a2300f3030 100644 --- a/src/Migration/Resources/Sites/EnvVar.php +++ b/src/Migration/Resources/Sites/EnvVar.php @@ -67,5 +67,4 @@ class EnvVar extends Resource { return $this->value; } - } diff --git a/src/Migration/Sources/Appwrite.php b/src/Migration/Sources/Appwrite.php index daf9b6a3f3..050f01b88a 100644 --- a/src/Migration/Sources/Appwrite.php +++ b/src/Migration/Sources/Appwrite.php @@ -144,7 +144,6 @@ class Appwrite extends Source default: throw new \Exception('Unknown source', Exception::CODE_VALIDATION); } - } public static function getName(): string @@ -354,7 +353,6 @@ class Appwrite extends Source */ private function reportStorage(array $resources, array &$report, array $resourceIds = []): void { - if (\in_array(Resource::TYPE_BUCKET, $resources)) { $bucketQueries = $this->buildQueries( resourceType: Resource::TYPE_BUCKET, @@ -869,7 +867,6 @@ class Appwrite extends Source 'enabled' => $database['enabled'] ?? true, ]); $databases[] = $newDatabase; - } } @@ -997,7 +994,7 @@ class Appwrite extends Source } /** @var Table $table */ - $col = match($table->getDatabase()->getType()) { + $col = match ($table->getDatabase()->getType()) { Resource::TYPE_DATABASE_VECTORSDB => self::getColumn($table, $column)->getAttribute(), default => self::getColumn($table, $column), }; @@ -2499,7 +2496,6 @@ class Appwrite extends Source default => throw new \InvalidArgumentException("Unsupported column type: {$column['type']}"), }; - } /** diff --git a/src/Migration/Sources/Appwrite/Reader.php b/src/Migration/Sources/Appwrite/Reader.php index d7a18027a3..fb6efd98d4 100644 --- a/src/Migration/Sources/Appwrite/Reader.php +++ b/src/Migration/Sources/Appwrite/Reader.php @@ -108,5 +108,4 @@ interface Reader */ public function queryLimit(int $limit): mixed; public function getSupportForAttributes(): bool; - } diff --git a/src/Migration/Sources/Firebase.php b/src/Migration/Sources/Firebase.php index 4495fb5ba1..b2acb1f3ef 100644 --- a/src/Migration/Sources/Firebase.php +++ b/src/Migration/Sources/Firebase.php @@ -667,7 +667,6 @@ class Firebase extends Source previous: $e )); } - } private function exportBuckets(int $batchsize): void From c76de9acffa7fddac7cb1e969ebde63c053abcd3 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Mon, 27 Apr 2026 13:57:33 +0100 Subject: [PATCH 44/91] Two-way relationships: sync partner-side onDelete on UpdateInPlace utopia's updateRelationship updates the physical constraint on both sides, but the Appwrite-level attributes meta doc on the partner side keeps the old options.onDelete value. Reads from the related collection's attribute list (Appwrite API, validators, subsequent re-migration pre-checks) see stale data. Mirrors the partner-side cleanup pattern already used in dropAttributeForRecreate. One-way unaffected (onDelete change on one-way already routes to DropAndRecreate). --- src/Migration/Destinations/Appwrite.php | 47 +++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index 80b22c711f..d1efd09870 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -1444,9 +1444,56 @@ class Appwrite extends Destination ])); $this->purgeTableCaches($database, $table, $dbForDatabases); + + // utopia's updateRelationship synced the physical constraint on both sides but + // not the Appwrite-level partner meta doc — refresh it so reads from the related + // collection don't see stale onDelete. + if ($isTwoWay) { + $this->refreshTwoWayPartnerOnDelete($database, $destOptions, $sourceOptions, $updatedAt, $dbForDatabases); + } + return true; } + private function refreshTwoWayPartnerOnDelete( + UtopiaDocument $database, + array $destOptions, + array $sourceOptions, + string $updatedAt, + UtopiaDatabase $dbForDatabases, + ): void { + $relatedTableId = (string) ($destOptions['relatedCollection'] ?? ''); + $partnerKey = (string) ($destOptions['twoWayKey'] ?? ''); + if ($relatedTableId === '' || $partnerKey === '') { + return; + } + + $relatedTable = $this->dbForProject->getDocument( + $this->databaseCollectionId($database), + $relatedTableId, + ); + if ($relatedTable->isEmpty()) { + return; + } + + $partnerMeta = $this->dbForProject->getDocument( + 'attributes', + $this->attributeIndexMetaId($database, $relatedTable, $partnerKey), + ); + if ($partnerMeta->isEmpty()) { + return; + } + + $partnerOptions = $partnerMeta->getAttribute('options', []); + $this->dbForProject->updateDocument('attributes', $partnerMeta->getId(), new UtopiaDocument([ + 'options' => array_merge($partnerOptions, [ + 'onDelete' => $sourceOptions['onDelete'] ?? $partnerOptions['onDelete'] ?? null, + ]), + '$updatedAt' => $updatedAt, + ])); + $this->purgeTableCaches($database, $relatedTable, $dbForDatabases); + } + /** * `lengths` is intentionally not compared: it's derived per-column from * the adapter's index validator and not settable on the Index resource. From c13e77d562e775b66ab8c03ee5c8163e53c3067e Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Mon, 27 Apr 2026 14:42:58 +0100 Subject: [PATCH 45/91] Two-way relationships: restore partner-side dedup via pair-key set MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Source emits both sides of a two-way relationship as separate Column resources, but processing one side already reconciles both physical columns + both Appwrite-level meta docs (utopia's createRelationship/ deleteRelationship cascade). Without dedup, the partner pass can fire DropAndRecreate again — partner's source createdAt is independent of parent's and may not match what we just stamped on dest's partner meta (parent's createdAt). Reintroduces the pair-key dedup that existed in 791dbb1 and was removed in 6e6f825 when relationships routed exclusively through UpdateInPlace. Commit 786a27b reopened the DropAndRecreate path for createdAt-different without restoring the dedup; this fixes that gap. Pair-key is canonical (sorted, scoped to dbSeq) so both sides resolve to the same string. Set after Tolerate, after UpdateInPlace success, and after the create-path completion. Skip check at the top of createField. --- src/Migration/Destinations/Appwrite.php | 61 +++++++++++++++++++++++++ 1 file changed, 61 insertions(+) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index d1efd09870..7eedb82d4b 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -119,6 +119,18 @@ class Appwrite extends Destination */ private array $orphansByTable = []; + /** + * Two-way relationship pairs already reconciled this run, keyed by a + * canonical pair-key. Source emits both sides as separate Column + * resources, but processing one side already reconciles both physical + * columns + both Appwrite-level meta docs. Without this set, the + * partner pass can re-trigger DropAndRecreate and destroy partner-table + * rows already migrated. + * + * @var array + */ + private array $processedTwoWayPairs = []; + /** * @param string $project * @param string $endpoint @@ -775,6 +787,17 @@ class Appwrite extends Destination // Two-way drop loses partner row data, restored by the subsequent Upsert row pass. $isRelationship = $type === UtopiaDatabase::VAR_RELATIONSHIP; + // Two-way relationships emit two source-side resources but reconcile both + // physical columns + both Appwrite-level meta docs in one pass. Skip the + // partner — re-processing can fire DropAndRecreate again and destroy + // partner-table rows already migrated this run (parent and partner have + // independent source createdAt values that may not match). + $twoWayPairKey = $this->twoWayPairKey($database, $table, $resource, $type); + if ($twoWayPairKey !== null && isset($this->processedTwoWayPairs[$twoWayPairKey])) { + $resource->setStatus(Resource::STATUS_SKIPPED, 'Two-way partner already reconciled'); + return false; + } + $attributeMetaId = $this->attributeIndexMetaId($database, $table, $resource->getKey()); if ($this->onDuplicate !== OnDuplicate::Fail) { $existingAttr = $this->dbForProject->getDocument('attributes', $attributeMetaId); @@ -802,6 +825,9 @@ class Appwrite extends Destination SchemaAction::DropAndRecreate, SchemaAction::Create => null, }; if ($earlyReturn !== null) { + if ($twoWayPairKey !== null) { + $this->processedTwoWayPairs[$twoWayPairKey] = true; + } return $earlyReturn; } @@ -972,6 +998,10 @@ class Appwrite extends Destination $this->purgeTableCaches($database, $table, $dbForDatabases); + if ($twoWayPairKey !== null) { + $this->processedTwoWayPairs[$twoWayPairKey] = true; + } + return true; } @@ -1510,6 +1540,37 @@ class Appwrite extends Destination return $database->getSequence() . ':' . $table->getSequence(); } + /** + * Canonical pair-key for a two-way relationship — same string regardless + * of which side (parent or partner) is being processed. Returns null for + * non-two-way attributes (no pair-level tracking needed). + */ + private function twoWayPairKey( + UtopiaDocument $database, + UtopiaDocument $table, + Column|Attribute $resource, + string $type, + ): ?string { + if ($type !== UtopiaDatabase::VAR_RELATIONSHIP) { + return null; + } + $options = $resource->getOptions(); + if (empty($options['twoWay'])) { + return null; + } + $twoWayKey = (string) ($options['twoWayKey'] ?? ''); + $relatedTableId = (string) ($options['relatedCollection'] ?? ''); + if ($twoWayKey === '' || $relatedTableId === '') { + return null; + } + + $thisSide = $table->getId() . '::' . $resource->getKey(); + $partnerSide = $relatedTableId . '::' . $twoWayKey; + $pair = [$thisSide, $partnerSide]; + \sort($pair); + return $database->getSequence() . '@' . \implode('<->', $pair); + } + private function databaseCollectionId(UtopiaDocument $database): string { return 'database_' . $database->getSequence(); From 09c1b2133d3ec42d11aee345f003d067d1de9ae5 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Mon, 27 Apr 2026 17:27:12 +0100 Subject: [PATCH 46/91] Maintainability pass from PR review Four targeted fixes from a code review pass on the schema-reconciliation code, picked for clear correctness or future-debug-cost improvements: 1. META_DATABASES / META_ATTRIBUTES / META_INDEXES class constants. ~30 bare collection-name string literals are now phpstan-checkable and a typo no longer compiles. Avoided false-positive replacements in getAttribute('attributes', []) / collectionStructure['indexes'] etc., which name UtopiaDocument fields, not collections. 2. resetRunState() called at top of run(). $rowBuffer, $orphansByTable, and $processedTwoWayPairs are instance state that previously leaked across run() invocations on a reused Appwrite destination instance. A second run on the same instance would inherit the first run's processed-pair set and silently SKIP unrelated two-way attributes. 3. tolerateMissing() renamed to bestEffort(). The previous name implied it caught only NotFound errors, but the implementation swallows all \Throwable. Honest naming prevents 'why didn't the orphan get cleaned up' debugging time later. 4. Inconsistent partner-side error message: 'Column limit exceeded' on line 949 was a copy-paste drift from the parent block's correct 'Attribute limit exceeded'. Same conceptual failure should surface the same user-visible message. 5. TwoWayPartner value object + resolveTwoWayPartner() helper. Three sites (dropAttributeForRecreate, refreshTwoWayPartnerOnDelete, dropOrphanAttribute) independently extracted relatedCollection / twoWayKey from options with subtly different fallback handling (?? null vs ?? ''). Single helper returns ?TwoWayPartner with relatedTable / partnerKey / partnerMetaId; null when not two-way or the partner table has gone away. Inconsistent fallbacks were a P1 bug waiting to ship. All four are P1 reviewer concerns. Larger items (split createField, template-method for the pre-check skeleton) deferred to a follow-up PR per the user's explicit instruction. 31/31 unit tests pass, pint clean, phpstan level 3 clean. --- src/Migration/Destinations/Appwrite.php | 166 +++++++++++-------- src/Migration/Destinations/TwoWayPartner.php | 15 ++ 2 files changed, 110 insertions(+), 71 deletions(-) create mode 100644 src/Migration/Destinations/TwoWayPartner.php diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index 7eedb82d4b..c206c35db7 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -63,6 +63,11 @@ use Utopia\Migration\Transfer; class Appwrite extends Destination { + /** Names of the platform-DB collections holding Appwrite schema metadata. */ + private const META_DATABASES = 'databases'; + private const META_ATTRIBUTES = 'attributes'; + private const META_INDEXES = 'indexes'; + /** Fields the SDK's per-type updateXAttribute endpoints don't expose; a change here forces DropAndRecreate. */ private const ATTRIBUTE_NON_SDK_FIELDS = [ 'type', @@ -176,10 +181,19 @@ class Appwrite extends Destination string $rootResourceId = '', string $rootResourceType = '', ): void { + $this->resetRunState(); parent::run($resources, $callback, $rootResourceId, $rootResourceType); $this->cleanupUpsertOrphans(); } + /** Per-run state must not leak across run() invocations on a reused instance. */ + private function resetRunState(): void + { + $this->rowBuffer = []; + $this->orphansByTable = []; + $this->processedTwoWayPairs = []; + } + public static function getName(): string { return 'Appwrite'; @@ -481,7 +495,7 @@ class Appwrite extends Destination $updatedAt = $this->normalizeDateTime($resource->getUpdatedAt(), $createdAt); if ($this->onDuplicate !== OnDuplicate::Fail) { - $existing = $this->dbForProject->getDocument('databases', $resource->getId()); + $existing = $this->dbForProject->getDocument(self::META_DATABASES, $resource->getId()); $action = $this->onDuplicate->resolveSchemaAction( !$existing->isEmpty(), $createdAt, @@ -498,7 +512,7 @@ class Appwrite extends Destination return false; })(), SchemaAction::UpdateInPlace => (function () use ($resource, $existing, $updatedAt): bool { - $this->dbForProject->updateDocument('databases', $existing->getId(), new UtopiaDocument([ + $this->dbForProject->updateDocument(self::META_DATABASES, $existing->getId(), new UtopiaDocument([ 'name' => $resource->getDatabaseName(), 'search' => implode(' ', [$resource->getId(), $resource->getDatabaseName()]), 'enabled' => $resource->getEnabled(), @@ -517,7 +531,7 @@ class Appwrite extends Destination } } - $database = $this->dbForProject->createDocument('databases', new UtopiaDocument([ + $database = $this->dbForProject->createDocument(self::META_DATABASES, new UtopiaDocument([ '$id' => $resource->getId(), 'name' => $resource->getDatabaseName(), 'enabled' => $resource->getEnabled(), @@ -575,7 +589,7 @@ class Appwrite extends Destination } $database = $this->dbForProject->getDocument( - 'databases', + self::META_DATABASES, $resource->getDatabase()->getId() ); @@ -705,7 +719,7 @@ class Appwrite extends Destination }; $database = $this->dbForProject->getDocument( - 'databases', + self::META_DATABASES, $resource->getTable()->getDatabase()->getId(), ); @@ -800,7 +814,7 @@ class Appwrite extends Destination $attributeMetaId = $this->attributeIndexMetaId($database, $table, $resource->getKey()); if ($this->onDuplicate !== OnDuplicate::Fail) { - $existingAttr = $this->dbForProject->getDocument('attributes', $attributeMetaId); + $existingAttr = $this->dbForProject->getDocument(self::META_ATTRIBUTES, $attributeMetaId); $action = $this->onDuplicate->resolveSchemaAction( !$existingAttr->isEmpty(), $createdAt, @@ -861,7 +875,7 @@ class Appwrite extends Destination $this->dbForProject->checkAttribute($table, $column); - $column = $this->dbForProject->createDocument('attributes', $column); + $column = $this->dbForProject->createDocument(self::META_ATTRIBUTES, $column); } catch (DuplicateException) { throw new Exception( resourceName: $resource->getName(), @@ -915,9 +929,9 @@ class Appwrite extends Destination '$updatedAt' => $updatedAt, ]); - $this->dbForProject->createDocument('attributes', $twoWayAttribute); + $this->dbForProject->createDocument(self::META_ATTRIBUTES, $twoWayAttribute); } catch (DuplicateException) { - $this->dbForProject->deleteDocument('attributes', $column->getId()); + $this->dbForProject->deleteDocument(self::META_ATTRIBUTES, $column->getId()); throw new Exception( resourceName: $resource->getName(), @@ -926,13 +940,13 @@ class Appwrite extends Destination message: 'Attribute already exists', ); } catch (LimitException) { - $this->dbForProject->deleteDocument('attributes', $column->getId()); + $this->dbForProject->deleteDocument(self::META_ATTRIBUTES, $column->getId()); throw new Exception( resourceName: $resource->getName(), resourceGroup: $resource->getGroup(), resourceId: $resource->getId(), - message: 'Column limit exceeded', + message: 'Attribute limit exceeded', ); } catch (\Throwable $e) { $this->purgeTableCaches($database, $relatedTable, $dbForDatabases); @@ -978,10 +992,10 @@ class Appwrite extends Destination } } } catch (\Throwable) { - $this->dbForProject->deleteDocument('attributes', $column->getId()); + $this->dbForProject->deleteDocument(self::META_ATTRIBUTES, $column->getId()); if (isset($twoWayAttribute)) { - $this->dbForProject->deleteDocument('attributes', $twoWayAttribute->getId()); + $this->dbForProject->deleteDocument(self::META_ATTRIBUTES, $twoWayAttribute->getId()); } throw new Exception( @@ -1012,7 +1026,7 @@ class Appwrite extends Destination protected function createIndex(Index $resource): bool { $database = $this->dbForProject->getDocument( - 'databases', + self::META_DATABASES, $resource->getTable()->getDatabase()->getId(), ); if ($database->isEmpty()) { @@ -1038,7 +1052,7 @@ class Appwrite extends Destination } $dbForDatabases = ($this->getDatabasesDB)($database); - $count = $this->dbForProject->count('indexes', [ + $count = $this->dbForProject->count(self::META_INDEXES, [ Query::equal('collectionInternalId', [$table->getSequence()]), Query::equal('databaseInternalId', [$database->getSequence()]) ], $dbForDatabases->getLimitForIndexes()); @@ -1118,7 +1132,7 @@ class Appwrite extends Destination $indexMetaId = $this->attributeIndexMetaId($database, $table, $resource->getKey()); if ($this->onDuplicate !== OnDuplicate::Fail) { - $existingIdx = $this->dbForProject->getDocument('indexes', $indexMetaId); + $existingIdx = $this->dbForProject->getDocument(self::META_INDEXES, $indexMetaId); $action = $this->onDuplicate->resolveSchemaAction( !$existingIdx->isEmpty(), $createdAt, @@ -1150,12 +1164,12 @@ class Appwrite extends Destination if ($action === SchemaAction::DropAndRecreate || $action === SchemaAction::UpdateInPlace) { $dbForDatabases->deleteIndex($this->tableCollectionId($database, $table), $resource->getKey()); - $this->dbForProject->deleteDocument('indexes', $indexMetaId); + $this->dbForProject->deleteDocument(self::META_INDEXES, $indexMetaId); $this->dbForProject->purgeCachedDocument($this->databaseCollectionId($database), $table->getId()); } } - $index = $this->dbForProject->createDocument('indexes', $index); + $index = $this->dbForProject->createDocument(self::META_INDEXES, $index); try { $result = $dbForDatabases->createIndex( @@ -1176,7 +1190,7 @@ class Appwrite extends Destination ); } } catch (\Throwable $th) { - $this->dbForProject->deleteDocument('indexes', $index->getId()); + $this->dbForProject->deleteDocument(self::META_INDEXES, $index->getId()); throw new Exception( resourceName: $resource->getName(), @@ -1263,7 +1277,7 @@ class Appwrite extends Destination if ($isLast) { try { $database = $this->dbForProject->getDocument( - 'databases', + self::META_DATABASES, $resource->getTable()->getDatabase()->getId(), ); @@ -1347,21 +1361,13 @@ class Appwrite extends Destination $dbForDatabases->deleteAttribute($collectionId, $resource->getKey()); } - $this->dbForProject->deleteDocument('attributes', $attributeMetaId); + $this->dbForProject->deleteDocument(self::META_ATTRIBUTES, $attributeMetaId); // deleteRelationship only touches utopia's _metadata; clear the Appwrite-level partner meta doc too. - if ($isRelationship && ($resource->getOptions()['twoWay'] ?? false)) { - $relatedTableId = $resource->getOptions()['relatedCollection'] ?? null; - $twoWayKey = $resource->getOptions()['twoWayKey'] ?? null; - if ($relatedTableId !== null && $twoWayKey !== null) { - $relatedTable = $this->dbForProject->getDocument( - $this->databaseCollectionId($database), - $relatedTableId, - ); - if (!$relatedTable->isEmpty()) { - $partnerMetaId = $this->attributeIndexMetaId($database, $relatedTable, $twoWayKey); - $this->tolerateMissing(fn () => $this->dbForProject->deleteDocument('attributes', $partnerMetaId)); - } + if ($isRelationship) { + $partner = $this->resolveTwoWayPartner($database, $resource->getOptions()); + if ($partner !== null) { + $this->bestEffort(fn () => $this->dbForProject->deleteDocument(self::META_ATTRIBUTES, $partner->partnerMetaId)); } } @@ -1411,7 +1417,7 @@ class Appwrite extends Destination filters: $existingAttr->getAttribute('filters'), ); - $this->dbForProject->updateDocument('attributes', $existingAttr->getId(), new UtopiaDocument([ + $this->dbForProject->updateDocument(self::META_ATTRIBUTES, $existingAttr->getId(), new UtopiaDocument([ 'key' => $resource->getKey(), 'type' => $type, 'size' => $resource->getSize(), @@ -1464,7 +1470,7 @@ class Appwrite extends Destination ); } - $this->dbForProject->updateDocument('attributes', $existingAttr->getId(), new UtopiaDocument([ + $this->dbForProject->updateDocument(self::META_ATTRIBUTES, $existingAttr->getId(), new UtopiaDocument([ 'key' => $resource->getKey(), 'type' => $type, 'options' => array_merge($destOptions, [ @@ -1485,6 +1491,10 @@ class Appwrite extends Destination return true; } + /** + * @param array $destOptions + * @param array $sourceOptions + */ private function refreshTwoWayPartnerOnDelete( UtopiaDocument $database, array $destOptions, @@ -1492,36 +1502,24 @@ class Appwrite extends Destination string $updatedAt, UtopiaDatabase $dbForDatabases, ): void { - $relatedTableId = (string) ($destOptions['relatedCollection'] ?? ''); - $partnerKey = (string) ($destOptions['twoWayKey'] ?? ''); - if ($relatedTableId === '' || $partnerKey === '') { + $partner = $this->resolveTwoWayPartner($database, $destOptions); + if ($partner === null) { return; } - $relatedTable = $this->dbForProject->getDocument( - $this->databaseCollectionId($database), - $relatedTableId, - ); - if ($relatedTable->isEmpty()) { - return; - } - - $partnerMeta = $this->dbForProject->getDocument( - 'attributes', - $this->attributeIndexMetaId($database, $relatedTable, $partnerKey), - ); + $partnerMeta = $this->dbForProject->getDocument(self::META_ATTRIBUTES, $partner->partnerMetaId); if ($partnerMeta->isEmpty()) { return; } $partnerOptions = $partnerMeta->getAttribute('options', []); - $this->dbForProject->updateDocument('attributes', $partnerMeta->getId(), new UtopiaDocument([ + $this->dbForProject->updateDocument(self::META_ATTRIBUTES, $partnerMeta->getId(), new UtopiaDocument([ 'options' => array_merge($partnerOptions, [ 'onDelete' => $sourceOptions['onDelete'] ?? $partnerOptions['onDelete'] ?? null, ]), '$updatedAt' => $updatedAt, ])); - $this->purgeTableCaches($database, $relatedTable, $dbForDatabases); + $this->purgeTableCaches($database, $partner->relatedTable, $dbForDatabases); } /** @@ -1540,6 +1538,38 @@ class Appwrite extends Destination return $database->getSequence() . ':' . $table->getSequence(); } + /** + * Resolve a two-way relationship's partner-side context (related table doc, + * partner attribute key, partner meta-doc id) from a relationship's options. + * Returns null if not two-way, options are missing the partner pointer, + * or the partner table no longer exists. + * + * @param array $options + */ + private function resolveTwoWayPartner(UtopiaDocument $database, array $options): ?TwoWayPartner + { + if (empty($options['twoWay'])) { + return null; + } + $relatedTableId = (string) ($options['relatedCollection'] ?? ''); + $partnerKey = (string) ($options['twoWayKey'] ?? ''); + if ($relatedTableId === '' || $partnerKey === '') { + return null; + } + $relatedTable = $this->dbForProject->getDocument( + $this->databaseCollectionId($database), + $relatedTableId, + ); + if ($relatedTable->isEmpty()) { + return null; + } + return new TwoWayPartner( + $relatedTable, + $partnerKey, + $this->attributeIndexMetaId($database, $relatedTable, $partnerKey), + ); + } + /** * Canonical pair-key for a two-way relationship — same string regardless * of which side (parent or partner) is being processed. Returns null for @@ -1659,7 +1689,7 @@ class Appwrite extends Destination $dbForDatabases = $tracked['dbForDatabases']; $this->dropOrphansByKind( - 'attributes', + self::META_ATTRIBUTES, $tracked['attributeKeys'], $database, $table, @@ -1667,7 +1697,7 @@ class Appwrite extends Destination ); $this->dropOrphansByKind( - 'indexes', + self::META_INDEXES, $tracked['indexKeys'], $database, $table, @@ -1718,31 +1748,25 @@ class Appwrite extends Destination $collectionId = $this->tableCollectionId($database, $table); if ($type === UtopiaDatabase::VAR_RELATIONSHIP) { - $this->tolerateMissing(fn () => $dbForDatabases->deleteRelationship($collectionId, $key)); + $this->bestEffort(fn () => $dbForDatabases->deleteRelationship($collectionId, $key)); } else { - $this->tolerateMissing(fn () => $dbForDatabases->deleteAttribute($collectionId, $key)); + $this->bestEffort(fn () => $dbForDatabases->deleteAttribute($collectionId, $key)); } - $this->tolerateMissing(fn () => $this->dbForProject->deleteDocument('attributes', $attrDoc->getId())); + $this->bestEffort(fn () => $this->dbForProject->deleteDocument(self::META_ATTRIBUTES, $attrDoc->getId())); $this->dbForProject->purgeCachedDocument($this->databaseCollectionId($database), $table->getId()); $dbForDatabases->purgeCachedCollection($collectionId); - if ($type !== UtopiaDatabase::VAR_RELATIONSHIP || empty($options['twoWay'])) { + if ($type !== UtopiaDatabase::VAR_RELATIONSHIP) { return; } - $twoWayKey = (string) ($options['twoWayKey'] ?? ''); - $relatedTableId = (string) ($options['relatedCollection'] ?? ''); - if ($twoWayKey === '' || $relatedTableId === '') { - return; - } - $relatedTable = $this->dbForProject->getDocument($this->databaseCollectionId($database), $relatedTableId); - if ($relatedTable->isEmpty()) { + $partner = $this->resolveTwoWayPartner($database, $options); + if ($partner === null) { return; } // deleteRelationship already dropped the partner physical column; only the Appwrite-level meta doc remains. - $childMetaId = $this->attributeIndexMetaId($database, $relatedTable, $twoWayKey); - $this->tolerateMissing(fn () => $this->dbForProject->deleteDocument('attributes', $childMetaId)); - $this->purgeTableCaches($database, $relatedTable, $dbForDatabases); + $this->bestEffort(fn () => $this->dbForProject->deleteDocument(self::META_ATTRIBUTES, $partner->partnerMetaId)); + $this->purgeTableCaches($database, $partner->relatedTable, $dbForDatabases); } private function dropOrphanIndex( @@ -1754,13 +1778,13 @@ class Appwrite extends Destination $collectionId = $this->tableCollectionId($database, $table); $indexMetaId = $this->attributeIndexMetaId($database, $table, $indexKey); - $this->tolerateMissing(fn () => $dbForDatabases->deleteIndex($collectionId, $indexKey)); - $this->tolerateMissing(fn () => $this->dbForProject->deleteDocument('indexes', $indexMetaId)); + $this->bestEffort(fn () => $dbForDatabases->deleteIndex($collectionId, $indexKey)); + $this->bestEffort(fn () => $this->dbForProject->deleteDocument(self::META_INDEXES, $indexMetaId)); $this->dbForProject->purgeCachedDocument($this->databaseCollectionId($database), $table->getId()); } /** Swallows deletion errors — a prior run or relationship cascade may have already removed the target. */ - private function tolerateMissing(callable $fn): void + private function bestEffort(callable $fn): void { try { $fn(); diff --git a/src/Migration/Destinations/TwoWayPartner.php b/src/Migration/Destinations/TwoWayPartner.php new file mode 100644 index 0000000000..afb1cea4bc --- /dev/null +++ b/src/Migration/Destinations/TwoWayPartner.php @@ -0,0 +1,15 @@ + Date: Tue, 28 Apr 2026 03:30:55 +0100 Subject: [PATCH 47/91] Inline TwoWayPartner as a typed array shape The 3-field readonly value object was thin enough that an array shape (typed via phpdoc) covers the same phpstan-checkable surface without a separate class file. Helper return type narrows from ?TwoWayPartner to ?array{relatedTable, partnerKey, partnerMetaId} and call sites switch from $partner->field to $partner['field']. --- src/Migration/Destinations/Appwrite.php | 26 ++++++++++---------- src/Migration/Destinations/TwoWayPartner.php | 15 ----------- 2 files changed, 13 insertions(+), 28 deletions(-) delete mode 100644 src/Migration/Destinations/TwoWayPartner.php diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index c206c35db7..839fcb03bf 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -1367,7 +1367,7 @@ class Appwrite extends Destination if ($isRelationship) { $partner = $this->resolveTwoWayPartner($database, $resource->getOptions()); if ($partner !== null) { - $this->bestEffort(fn () => $this->dbForProject->deleteDocument(self::META_ATTRIBUTES, $partner->partnerMetaId)); + $this->bestEffort(fn () => $this->dbForProject->deleteDocument(self::META_ATTRIBUTES, $partner['partnerMetaId'])); } } @@ -1507,7 +1507,7 @@ class Appwrite extends Destination return; } - $partnerMeta = $this->dbForProject->getDocument(self::META_ATTRIBUTES, $partner->partnerMetaId); + $partnerMeta = $this->dbForProject->getDocument(self::META_ATTRIBUTES, $partner['partnerMetaId']); if ($partnerMeta->isEmpty()) { return; } @@ -1519,7 +1519,7 @@ class Appwrite extends Destination ]), '$updatedAt' => $updatedAt, ])); - $this->purgeTableCaches($database, $partner->relatedTable, $dbForDatabases); + $this->purgeTableCaches($database, $partner['relatedTable'], $dbForDatabases); } /** @@ -1539,14 +1539,14 @@ class Appwrite extends Destination } /** - * Resolve a two-way relationship's partner-side context (related table doc, - * partner attribute key, partner meta-doc id) from a relationship's options. + * Resolve a two-way relationship's partner-side context from options. * Returns null if not two-way, options are missing the partner pointer, * or the partner table no longer exists. * * @param array $options + * @return array{relatedTable: UtopiaDocument, partnerKey: string, partnerMetaId: string}|null */ - private function resolveTwoWayPartner(UtopiaDocument $database, array $options): ?TwoWayPartner + private function resolveTwoWayPartner(UtopiaDocument $database, array $options): ?array { if (empty($options['twoWay'])) { return null; @@ -1563,11 +1563,11 @@ class Appwrite extends Destination if ($relatedTable->isEmpty()) { return null; } - return new TwoWayPartner( - $relatedTable, - $partnerKey, - $this->attributeIndexMetaId($database, $relatedTable, $partnerKey), - ); + return [ + 'relatedTable' => $relatedTable, + 'partnerKey' => $partnerKey, + 'partnerMetaId' => $this->attributeIndexMetaId($database, $relatedTable, $partnerKey), + ]; } /** @@ -1765,8 +1765,8 @@ class Appwrite extends Destination } // deleteRelationship already dropped the partner physical column; only the Appwrite-level meta doc remains. - $this->bestEffort(fn () => $this->dbForProject->deleteDocument(self::META_ATTRIBUTES, $partner->partnerMetaId)); - $this->purgeTableCaches($database, $partner->relatedTable, $dbForDatabases); + $this->bestEffort(fn () => $this->dbForProject->deleteDocument(self::META_ATTRIBUTES, $partner['partnerMetaId'])); + $this->purgeTableCaches($database, $partner['relatedTable'], $dbForDatabases); } private function dropOrphanIndex( diff --git a/src/Migration/Destinations/TwoWayPartner.php b/src/Migration/Destinations/TwoWayPartner.php deleted file mode 100644 index afb1cea4bc..0000000000 --- a/src/Migration/Destinations/TwoWayPartner.php +++ /dev/null @@ -1,15 +0,0 @@ - Date: Tue, 28 Apr 2026 03:44:46 +0100 Subject: [PATCH 48/91] Lock-in test for ATTRIBUTE_NON_SDK_FIELDS via SDK reflection Reflects on appwrite/appwrite's TablesDB and Databases services to build the set of meta-doc fields the SDK can mutate via update*Column / update*Attribute endpoints, then asserts no overlap with our ATTRIBUTE_NON_SDK_FIELDS constant. When the SDK ships a new mutable param (e.g. exposing 'signed' or 'array' on Update), CI fails so we sync the constant. Catches drift in CI rather than at runtime. PARAM_TO_META_FIELD documents the SDK-vs-meta-doc vocabulary mismatch: - xdefault -> default (PHP keyword workaround) - min/max/elements -> null (sub-fields of formatOptions, not direct) - onDelete -> null (sub-field of relationship options) Currently observed SDK-exposed top-level fields: required, default, size. Constant correctly lists: type, array, signed, format, formatOptions, filters. Zero overlap, test passes. --- .../AppwriteAttributeSdkBoundaryTest.php | 96 +++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 tests/Migration/Unit/Destinations/AppwriteAttributeSdkBoundaryTest.php diff --git a/tests/Migration/Unit/Destinations/AppwriteAttributeSdkBoundaryTest.php b/tests/Migration/Unit/Destinations/AppwriteAttributeSdkBoundaryTest.php new file mode 100644 index 0000000000..3b2fdddc33 --- /dev/null +++ b/tests/Migration/Unit/Destinations/AppwriteAttributeSdkBoundaryTest.php @@ -0,0 +1,96 @@ + + */ + private const PARAM_TO_META_FIELD = [ + 'xdefault' => 'default', + 'min' => null, + 'max' => null, + 'elements' => null, + 'onDelete' => null, + ]; + + public function testSdkExposedFieldsAreNotInNonSdkConstant(): void + { + $sdkExposed = $this->collectSdkExposedMetaFields(); + $nonSdk = $this->readNonSdkConstant(); + + $overlap = \array_intersect($sdkExposed, $nonSdk); + $this->assertSame( + [], + \array_values($overlap), + 'ATTRIBUTE_NON_SDK_FIELDS marks these fields as non-SDK, but the appwrite/appwrite ' + . 'SDK exposes them via updateXColumn/updateXAttribute: ' . \implode(', ', $overlap) + . '. Either drop these from ATTRIBUTE_NON_SDK_FIELDS or update PARAM_TO_META_FIELD ' + . 'in this test if the SDK param doesn\'t correspond to a top-level meta-doc field.', + ); + } + + /** + * @return list meta-doc field names the SDK can mutate + */ + private function collectSdkExposedMetaFields(): array + { + $fields = []; + foreach ([TablesDB::class, Databases::class] as $service) { + $service = new ReflectionClass($service); + foreach ($service->getMethods(ReflectionMethod::IS_PUBLIC) as $method) { + if (!\preg_match('/^update.+(Column|Attribute)$/', $method->getName())) { + continue; + } + foreach ($method->getParameters() as $param) { + $name = $param->getName(); + if (\in_array($name, self::IGNORED_PARAMS, true)) { + continue; + } + $mapped = \array_key_exists($name, self::PARAM_TO_META_FIELD) + ? self::PARAM_TO_META_FIELD[$name] + : $name; + if ($mapped === null) { + continue; + } + $fields[$mapped] = true; + } + } + } + return \array_keys($fields); + } + + /** + * @return list + */ + private function readNonSdkConstant(): array + { + /** @var list $value */ + $value = (new ReflectionClass(AppwriteDestination::class))->getConstant('ATTRIBUTE_NON_SDK_FIELDS'); + return $value; + } +} From c8d17898458de4a297ba03fd1a126f7aa13227af Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Tue, 28 Apr 2026 04:12:58 +0100 Subject: [PATCH 49/91] Spec-match guard: skip drop when source and dest already match MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds an unconditional spec-match check after resolveSchemaAction returns DropAndRecreate or UpdateInPlace. If source's full attribute/table/db/ index spec already matches dest, action is forced to Tolerate — no DDL, no in-place call, no row-data wipe. Closes the gap where a user dropping + recreating a column on source with the same spec triggered a wasteful drop+recreate cascade on dest (createdAt advanced even though spec was unchanged). Row pass under Upsert mode still propagates source row values via upsertDocuments. Helpers: databaseSpecMatches, tableSpecMatches, attributeSpecMatches (handles relationship via RELATIONSHIP_STRUCTURAL_FIELDS + onDelete), indexSpecMatches (existing). Inserted as a single override at each of the four pre-check sites. createIndex: removed the inline indexSpecMatches IIFE inside UpdateInPlace since the unified outer guard now subsumes it. The 'Index spec unchanged' status message merges into the generic 'Already exists on destination' — slight loss of fidelity, gain in symmetry across the four create methods. 47/47 unit tests pass, pint clean, phpstan level 3 clean. --- src/Migration/Destinations/Appwrite.php | 83 ++++++++++++++++++++++--- 1 file changed, 74 insertions(+), 9 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index 839fcb03bf..c648a9d41b 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -504,6 +504,9 @@ class Appwrite extends Destination $existing->getUpdatedAt(), canDrop: false, ); + if ($action !== SchemaAction::Create && $this->databaseSpecMatches($existing, $resource)) { + $action = SchemaAction::Tolerate; + } $earlyReturn = match ($action) { SchemaAction::Tolerate => (function () use ($resource, $existing): bool { @@ -625,6 +628,9 @@ class Appwrite extends Destination $existing->getUpdatedAt(), canDrop: false, ); + if ($action !== SchemaAction::Create && $this->tableSpecMatches($existing, $resource)) { + $action = SchemaAction::Tolerate; + } $earlyReturn = match ($action) { SchemaAction::Tolerate => (function () use ($resource, $existing): bool { @@ -823,6 +829,9 @@ class Appwrite extends Destination $existingAttr->getUpdatedAt(), canDrop: true, ); + if ($action !== SchemaAction::Create && $this->attributeSpecMatches($existingAttr, $resource, $type, $isRelationship)) { + $action = SchemaAction::Tolerate; + } // UpdateInPlace returns null when the source change isn't SDK-expressible — falls through to the drop step below. $earlyReturn = match ($action) { @@ -1141,22 +1150,18 @@ class Appwrite extends Destination $existingIdx->getUpdatedAt(), canDrop: true, ); + if ($action !== SchemaAction::Create && $this->indexSpecMatches($existingIdx, $resource)) { + $action = SchemaAction::Tolerate; + } - // Indexes have no in-place primitive — UpdateInPlace tolerates if spec matches, else drop+recreate. + // Indexes have no in-place primitive — any action other than Tolerate falls through to drop+recreate. $earlyReturn = match ($action) { SchemaAction::Tolerate => (function () use ($resource, $database, $table): bool { $this->dbForProject->purgeCachedDocument($this->databaseCollectionId($database), $table->getId()); $resource->setStatus(Resource::STATUS_SKIPPED, 'Already exists on destination'); return false; })(), - SchemaAction::UpdateInPlace => $this->indexSpecMatches($existingIdx, $resource) - ? (function () use ($resource, $database, $table): bool { - $this->dbForProject->purgeCachedDocument($this->databaseCollectionId($database), $table->getId()); - $resource->setStatus(Resource::STATUS_SKIPPED, 'Index spec unchanged'); - return false; - })() - : null, - SchemaAction::DropAndRecreate, SchemaAction::Create => null, + SchemaAction::UpdateInPlace, SchemaAction::DropAndRecreate, SchemaAction::Create => null, }; if ($earlyReturn !== null) { return $earlyReturn; @@ -1522,6 +1527,66 @@ class Appwrite extends Destination $this->purgeTableCaches($database, $partner['relatedTable'], $dbForDatabases); } + private function databaseSpecMatches(UtopiaDocument $existing, Database $resource): bool + { + $sourceType = empty($resource->getType()) ? 'legacy' : $resource->getType(); + $sourceOriginalId = empty($resource->getOriginalId()) ? null : $resource->getOriginalId(); + + return $existing->getAttribute('name') === $resource->getDatabaseName() + && $existing->getAttribute('enabled') === $resource->getEnabled() + && $existing->getAttribute('type') === $sourceType + && $existing->getAttribute('originalId') === $sourceOriginalId + && $existing->getAttribute('database') === $resource->getDatabase(); + } + + private function tableSpecMatches(UtopiaDocument $existing, Table $resource): bool + { + if ($existing->getAttribute('name') !== $resource->getTableName() + || $existing->getAttribute('enabled') !== $resource->getEnabled() + || $existing->getAttribute('documentSecurity') !== $resource->getRowSecurity()) { + return false; + } + + $sourcePerms = Permission::aggregate($resource->getPermissions()); + /** @var list $destPerms */ + $destPerms = $existing->getAttribute('$permissions', []); + \sort($sourcePerms); + \sort($destPerms); + return $sourcePerms === $destPerms; + } + + /** + * Compares the full attribute spec including SDK-reachable fields. Used to + * short-circuit DropAndRecreate / UpdateInPlace when source and destination + * already match — no DDL needed regardless of timestamp drift. + */ + private function attributeSpecMatches(UtopiaDocument $existing, Column|Attribute $resource, string $type, bool $isRelationship): bool + { + if ($existing->getAttribute('type') !== $type) { + return false; + } + if ($isRelationship) { + $sourceOptions = $resource->getOptions(); + /** @var array $destOptions */ + $destOptions = $existing->getAttribute('options', []); + foreach (self::RELATIONSHIP_STRUCTURAL_FIELDS as $field) { + if (($sourceOptions[$field] ?? null) !== ($destOptions[$field] ?? null)) { + return false; + } + } + return ($sourceOptions['onDelete'] ?? null) === ($destOptions['onDelete'] ?? null); + } + + return $existing->getAttribute('size') === $resource->getSize() + && $existing->getAttribute('required') === $resource->isRequired() + && $existing->getAttribute('default') === $resource->getDefault() + && $existing->getAttribute('array') === $resource->isArray() + && $existing->getAttribute('signed') === $resource->isSigned() + && $existing->getAttribute('format') === $resource->getFormat() + && $existing->getAttribute('formatOptions') === $resource->getFormatOptions() + && $existing->getAttribute('filters') === $resource->getFilters(); + } + /** * `lengths` is intentionally not compared: it's derived per-column from * the adapter's index validator and not settable on the Index resource. From 89078ae8deeece9ec1fa16b6e738765e8a4b9240 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Tue, 28 Apr 2026 04:24:38 +0100 Subject: [PATCH 50/91] Trim verbose comments and helper docblocks Mostly mechanical reduction of multi-line WHY blocks to one-liners and removal of obvious WHAT comments. Keeps load-bearing rationale (e.g. 'utopia syncs both physical sides; partner meta has to be refreshed by hand') as one short line per concern. --- src/Migration/Destinations/Appwrite.php | 43 ++++--------------------- 1 file changed, 7 insertions(+), 36 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index c648a9d41b..44b252c946 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -125,12 +125,7 @@ class Appwrite extends Destination private array $orphansByTable = []; /** - * Two-way relationship pairs already reconciled this run, keyed by a - * canonical pair-key. Source emits both sides as separate Column - * resources, but processing one side already reconciles both physical - * columns + both Appwrite-level meta docs. Without this set, the - * partner pass can re-trigger DropAndRecreate and destroy partner-table - * rows already migrated. + * Two-way pairs already reconciled this run; partner pass short-circuits. * * @var array */ @@ -803,15 +798,9 @@ class Appwrite extends Destination $this->trackOrphanCandidate($database, $table, 'attributeKeys', $resource->getKey(), $dbForDatabases); - // Both rel types route through deleteRelationship — deleteAttribute throws for VAR_RELATIONSHIP. - // Two-way drop loses partner row data, restored by the subsequent Upsert row pass. $isRelationship = $type === UtopiaDatabase::VAR_RELATIONSHIP; - // Two-way relationships emit two source-side resources but reconcile both - // physical columns + both Appwrite-level meta docs in one pass. Skip the - // partner — re-processing can fire DropAndRecreate again and destroy - // partner-table rows already migrated this run (parent and partner have - // independent source createdAt values that may not match). + // Source emits both sides of a two-way; processing one side reconciles both. Partner skip. $twoWayPairKey = $this->twoWayPairKey($database, $table, $resource, $type); if ($twoWayPairKey !== null && isset($this->processedTwoWayPairs[$twoWayPairKey])) { $resource->setStatus(Resource::STATUS_SKIPPED, 'Two-way partner already reconciled'); @@ -833,7 +822,6 @@ class Appwrite extends Destination $action = SchemaAction::Tolerate; } - // UpdateInPlace returns null when the source change isn't SDK-expressible — falls through to the drop step below. $earlyReturn = match ($action) { SchemaAction::Tolerate => (function () use ($resource, $database, $table, $dbForDatabases): bool { $this->purgeTableCaches($database, $table, $dbForDatabases); @@ -1293,12 +1281,9 @@ class Appwrite extends Destination $dbForDatabases = ($this->getDatabasesDB)($database); - // Drop schema-level 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 is in case an attribute was deleted from Appwrite attributes collection but was not deleted from the table - * When creating an archive we select * which will include orphan attribute from the schema - */ + // Strip row payload fields the table doesn't declare — guards against orphans surviving in source archives. if ($dbForDatabases->getAdapter()->getSupportForAttributes()) { foreach ($this->rowBuffer as $row) { foreach ($row as $key => $value) { @@ -1486,9 +1471,7 @@ class Appwrite extends Destination $this->purgeTableCaches($database, $table, $dbForDatabases); - // utopia's updateRelationship synced the physical constraint on both sides but - // not the Appwrite-level partner meta doc — refresh it so reads from the related - // collection don't see stale onDelete. + // utopia syncs both physical sides; partner's Appwrite-level meta doc has to be refreshed by hand. if ($isTwoWay) { $this->refreshTwoWayPartnerOnDelete($database, $destOptions, $sourceOptions, $updatedAt, $dbForDatabases); } @@ -1555,11 +1538,7 @@ class Appwrite extends Destination return $sourcePerms === $destPerms; } - /** - * Compares the full attribute spec including SDK-reachable fields. Used to - * short-circuit DropAndRecreate / UpdateInPlace when source and destination - * already match — no DDL needed regardless of timestamp drift. - */ + /** Full-spec equality: short-circuits both DropAndRecreate and UpdateInPlace to Tolerate when nothing changed. */ private function attributeSpecMatches(UtopiaDocument $existing, Column|Attribute $resource, string $type, bool $isRelationship): bool { if ($existing->getAttribute('type') !== $type) { @@ -1604,10 +1583,6 @@ class Appwrite extends Destination } /** - * Resolve a two-way relationship's partner-side context from options. - * Returns null if not two-way, options are missing the partner pointer, - * or the partner table no longer exists. - * * @param array $options * @return array{relatedTable: UtopiaDocument, partnerKey: string, partnerMetaId: string}|null */ @@ -1635,11 +1610,7 @@ class Appwrite extends Destination ]; } - /** - * Canonical pair-key for a two-way relationship — same string regardless - * of which side (parent or partner) is being processed. Returns null for - * non-two-way attributes (no pair-level tracking needed). - */ + /** Canonical pair-key — same string regardless of which side is being processed. */ private function twoWayPairKey( UtopiaDocument $database, UtopiaDocument $table, From 36a1acf75027a22b0ad1a7374b8f88c94ab30f68 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Tue, 28 Apr 2026 05:16:28 +0100 Subject: [PATCH 51/91] Spec-match: order-independent assoc-array equality + comments - valuesMatch helper: ksort assoc arrays before === so {min,max} matches {max,min}. Lists (filters, columns) keep order-sensitive comparison since order is semantically meaningful there. - Apply via attributeSpecMatches (formatOptions, relationship options, onDelete) and arraysDifferOnKeys (used by updateAttributeInPlace and updateRelationshipInPlace). - One-line comment on each spec-match guard documenting why the Create case is excluded (no existing dest doc to match against). --- src/Migration/Destinations/Appwrite.php | 40 ++++++++++++++++++------- 1 file changed, 29 insertions(+), 11 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index 44b252c946..1a1acfbd5d 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -499,6 +499,7 @@ class Appwrite extends Destination $existing->getUpdatedAt(), canDrop: false, ); + // Spec match → skip work. Create excluded; nothing on dest to match against. if ($action !== SchemaAction::Create && $this->databaseSpecMatches($existing, $resource)) { $action = SchemaAction::Tolerate; } @@ -623,6 +624,7 @@ class Appwrite extends Destination $existing->getUpdatedAt(), canDrop: false, ); + // Spec match → skip work. Create excluded; nothing on dest to match against. if ($action !== SchemaAction::Create && $this->tableSpecMatches($existing, $resource)) { $action = SchemaAction::Tolerate; } @@ -818,6 +820,7 @@ class Appwrite extends Destination $existingAttr->getUpdatedAt(), canDrop: true, ); + // Spec match → skip work. Create excluded; nothing on dest to match against. if ($action !== SchemaAction::Create && $this->attributeSpecMatches($existingAttr, $resource, $type, $isRelationship)) { $action = SchemaAction::Tolerate; } @@ -1138,6 +1141,7 @@ class Appwrite extends Destination $existingIdx->getUpdatedAt(), canDrop: true, ); + // Spec match → skip work. Create excluded; nothing on dest to match against. if ($action !== SchemaAction::Create && $this->indexSpecMatches($existingIdx, $resource)) { $action = SchemaAction::Tolerate; } @@ -1549,21 +1553,21 @@ class Appwrite extends Destination /** @var array $destOptions */ $destOptions = $existing->getAttribute('options', []); foreach (self::RELATIONSHIP_STRUCTURAL_FIELDS as $field) { - if (($sourceOptions[$field] ?? null) !== ($destOptions[$field] ?? null)) { + if (!$this->valuesMatch($sourceOptions[$field] ?? null, $destOptions[$field] ?? null)) { return false; } } - return ($sourceOptions['onDelete'] ?? null) === ($destOptions['onDelete'] ?? null); + return $this->valuesMatch($sourceOptions['onDelete'] ?? null, $destOptions['onDelete'] ?? null); } - return $existing->getAttribute('size') === $resource->getSize() - && $existing->getAttribute('required') === $resource->isRequired() - && $existing->getAttribute('default') === $resource->getDefault() - && $existing->getAttribute('array') === $resource->isArray() - && $existing->getAttribute('signed') === $resource->isSigned() - && $existing->getAttribute('format') === $resource->getFormat() - && $existing->getAttribute('formatOptions') === $resource->getFormatOptions() - && $existing->getAttribute('filters') === $resource->getFilters(); + return $existing->getAttribute('size') === $resource->getSize() + && $existing->getAttribute('required') === $resource->isRequired() + && $existing->getAttribute('default') === $resource->getDefault() + && $existing->getAttribute('array') === $resource->isArray() + && $existing->getAttribute('signed') === $resource->isSigned() + && $existing->getAttribute('format') === $resource->getFormat() + && $this->valuesMatch($existing->getAttribute('formatOptions'), $resource->getFormatOptions()) + && $existing->getAttribute('filters') === $resource->getFilters(); } /** @@ -1670,13 +1674,27 @@ class Appwrite extends Destination private function arraysDifferOnKeys(array $a, array $b, array $keys): bool { foreach ($keys as $key) { - if (($a[$key] ?? null) !== ($b[$key] ?? null)) { + if (!$this->valuesMatch($a[$key] ?? null, $b[$key] ?? null)) { return true; } } return false; } + /** + * `===` on associative arrays is order-sensitive on keys; ksort both sides + * before comparing so {min, max} matches {max, min}. Lists (numeric keys) + * are left alone — order is semantically meaningful for filters/columns. + */ + private function valuesMatch(mixed $a, mixed $b): bool + { + if (\is_array($a) && \is_array($b) && !\array_is_list($a) && !\array_is_list($b)) { + \ksort($a); + \ksort($b); + } + return $a === $b; + } + /** $kind is 'attributeKeys' or 'indexKeys'. */ private function trackOrphanCandidate( UtopiaDocument $database, From 6ec2c45a4077d9452ae32e4faa1b49375ad77cae Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Tue, 28 Apr 2026 05:43:11 +0100 Subject: [PATCH 52/91] =?UTF-8?q?Drop=20createdAt=20handling=20=E2=80=94?= =?UTF-8?q?=20spec-match=20guard=20+=20sourceIsNewer=20cover=20everything?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit resolveSchemaAction's createdAt branch became redundant once the spec-match guard landed. The flow: - resolveSchemaAction returns Create / Tolerate / UpdateInPlace based purely on existence and updatedAt-newer. - The destination's spec-match guard overrides UpdateInPlace to Tolerate when source and dest have identical spec. - Inner attribute/index spec checks fall through to drop+recreate when the SDK can't express the change in place. End-state behavior on every scenario is identical (verified before this commit). The createdAt path was extra work that produced the same outcome via a longer route. Removed: - $sourceCreatedAt / $destCreatedAt / $canDrop params from resolveSchemaAction - createdAtDiffers private helper - SchemaAction::DropAndRecreate enum case (no longer returned by resolveSchemaAction; inner fallthrough drops directly) - 4 call sites in Appwrite.php drop the createdAt args + canDrop: named arg + DropAndRecreate match arm + DropAndRecreate post-match if-clause - ~13 createdAt-specific unit tests; remaining 19 test the exists × mode × updatedAt matrix --- src/Migration/Destinations/Appwrite.php | 32 ++--- src/Migration/Destinations/OnDuplicate.php | 44 +------ .../Unit/General/OnDuplicateTest.php | 123 +++--------------- 3 files changed, 33 insertions(+), 166 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index 1a1acfbd5d..d215452d8d 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -68,7 +68,7 @@ class Appwrite extends Destination private const META_ATTRIBUTES = 'attributes'; private const META_INDEXES = 'indexes'; - /** Fields the SDK's per-type updateXAttribute endpoints don't expose; a change here forces DropAndRecreate. */ + /** Fields the SDK's per-type updateXAttribute endpoints don't expose; a change here forces drop+recreate. */ private const ATTRIBUTE_NON_SDK_FIELDS = [ 'type', 'array', @@ -493,11 +493,8 @@ class Appwrite extends Destination $existing = $this->dbForProject->getDocument(self::META_DATABASES, $resource->getId()); $action = $this->onDuplicate->resolveSchemaAction( !$existing->isEmpty(), - $createdAt, - $existing->getCreatedAt(), $updatedAt, $existing->getUpdatedAt(), - canDrop: false, ); // Spec match → skip work. Create excluded; nothing on dest to match against. if ($action !== SchemaAction::Create && $this->databaseSpecMatches($existing, $resource)) { @@ -523,7 +520,7 @@ class Appwrite extends Destination $resource->setSequence($existing->getSequence()); return true; })(), - SchemaAction::Create, SchemaAction::DropAndRecreate => null, + SchemaAction::Create => null, }; if ($earlyReturn !== null) { return $earlyReturn; @@ -618,11 +615,8 @@ class Appwrite extends Destination ); $action = $this->onDuplicate->resolveSchemaAction( !$existing->isEmpty(), - $createdAt, - $existing->getCreatedAt(), $updatedAt, $existing->getUpdatedAt(), - canDrop: false, ); // Spec match → skip work. Create excluded; nothing on dest to match against. if ($action !== SchemaAction::Create && $this->tableSpecMatches($existing, $resource)) { @@ -651,7 +645,7 @@ class Appwrite extends Destination $resource->setSequence($existing->getSequence()); return true; })(), - SchemaAction::Create, SchemaAction::DropAndRecreate => null, + SchemaAction::Create => null, }; if ($earlyReturn !== null) { return $earlyReturn; @@ -814,11 +808,8 @@ class Appwrite extends Destination $existingAttr = $this->dbForProject->getDocument(self::META_ATTRIBUTES, $attributeMetaId); $action = $this->onDuplicate->resolveSchemaAction( !$existingAttr->isEmpty(), - $createdAt, - $existingAttr->getCreatedAt(), $updatedAt, $existingAttr->getUpdatedAt(), - canDrop: true, ); // Spec match → skip work. Create excluded; nothing on dest to match against. if ($action !== SchemaAction::Create && $this->attributeSpecMatches($existingAttr, $resource, $type, $isRelationship)) { @@ -836,7 +827,7 @@ class Appwrite extends Destination : $this->updateAttributeInPlace($database, $table, $resource, $type, $updatedAt, $existingAttr, $dbForDatabases)) ? true : null, - SchemaAction::DropAndRecreate, SchemaAction::Create => null, + SchemaAction::Create => null, }; if ($earlyReturn !== null) { if ($twoWayPairKey !== null) { @@ -845,7 +836,7 @@ class Appwrite extends Destination return $earlyReturn; } - if ($action === SchemaAction::DropAndRecreate || $action === SchemaAction::UpdateInPlace) { + if ($action === SchemaAction::UpdateInPlace) { $this->dropAttributeForRecreate($database, $table, $resource, $dbForDatabases); } } @@ -1135,11 +1126,8 @@ class Appwrite extends Destination $existingIdx = $this->dbForProject->getDocument(self::META_INDEXES, $indexMetaId); $action = $this->onDuplicate->resolveSchemaAction( !$existingIdx->isEmpty(), - $createdAt, - $existingIdx->getCreatedAt(), $updatedAt, $existingIdx->getUpdatedAt(), - canDrop: true, ); // Spec match → skip work. Create excluded; nothing on dest to match against. if ($action !== SchemaAction::Create && $this->indexSpecMatches($existingIdx, $resource)) { @@ -1153,13 +1141,13 @@ class Appwrite extends Destination $resource->setStatus(Resource::STATUS_SKIPPED, 'Already exists on destination'); return false; })(), - SchemaAction::UpdateInPlace, SchemaAction::DropAndRecreate, SchemaAction::Create => null, + SchemaAction::UpdateInPlace, SchemaAction::Create => null, }; if ($earlyReturn !== null) { return $earlyReturn; } - if ($action === SchemaAction::DropAndRecreate || $action === SchemaAction::UpdateInPlace) { + if ($action === SchemaAction::UpdateInPlace) { $dbForDatabases->deleteIndex($this->tableCollectionId($database, $table), $resource->getKey()); $this->dbForProject->deleteDocument(self::META_INDEXES, $indexMetaId); $this->dbForProject->purgeCachedDocument($this->databaseCollectionId($database), $table->getId()); @@ -1368,7 +1356,7 @@ class Appwrite extends Destination $this->purgeTableCaches($database, $table, $dbForDatabases); } - /** Returns false when the source change isn't SDK-expressible — caller falls through to DropAndRecreate. */ + /** Returns false when the source change isn't SDK-expressible — caller falls through to drop+recreate. */ private function updateAttributeInPlace( UtopiaDocument $database, UtopiaDocument $table, @@ -1430,7 +1418,7 @@ class Appwrite extends Destination } /** - * Returns false when the source change isn't SDK-expressible — caller falls through to DropAndRecreate. + * Returns false when the source change isn't SDK-expressible — caller falls through to drop+recreate. * One-way + onDelete change is also rejected: utopia's updateRelationship partner-cascade throws on one-way. */ private function updateRelationshipInPlace( @@ -1542,7 +1530,7 @@ class Appwrite extends Destination return $sourcePerms === $destPerms; } - /** Full-spec equality: short-circuits both DropAndRecreate and UpdateInPlace to Tolerate when nothing changed. */ + /** Full-spec equality: short-circuits UpdateInPlace to Tolerate when nothing changed. */ private function attributeSpecMatches(UtopiaDocument $existing, Column|Attribute $resource, string $type, bool $isRelationship): bool { if ($existing->getAttribute('type') !== $type) { diff --git a/src/Migration/Destinations/OnDuplicate.php b/src/Migration/Destinations/OnDuplicate.php index 744b2e1561..69b4cdf8f2 100644 --- a/src/Migration/Destinations/OnDuplicate.php +++ b/src/Migration/Destinations/OnDuplicate.php @@ -6,7 +6,6 @@ enum SchemaAction { case Create; case Tolerate; - case DropAndRecreate; case UpdateInPlace; } @@ -25,16 +24,14 @@ enum OnDuplicate: string } /** - * $canDrop = false (containers like databases/tables) forces UpdateInPlace - * even on createdAt-different — dropping would orphan children. + * Coarse routing for re-migration. The caller follows up with a spec-match + * check that overrides UpdateInPlace to Tolerate when source and dest + * already have identical spec — see DestinationAppwrite for the full flow. */ public function resolveSchemaAction( bool $exists, - ?string $sourceCreatedAt = null, - ?string $destCreatedAt = null, ?string $sourceUpdatedAt = null, ?string $destUpdatedAt = null, - bool $canDrop = false, ): SchemaAction { if (!$exists) { return SchemaAction::Create; @@ -42,41 +39,12 @@ enum OnDuplicate: string return match ($this) { self::Fail => SchemaAction::Create, self::Skip => SchemaAction::Tolerate, - self::Upsert => $this->resolveUpsertAction( - $sourceCreatedAt, - $destCreatedAt, - $sourceUpdatedAt, - $destUpdatedAt, - $canDrop, - ), + self::Upsert => $this->sourceIsNewer($sourceUpdatedAt, $destUpdatedAt) + ? SchemaAction::UpdateInPlace + : SchemaAction::Tolerate, }; } - private function resolveUpsertAction( - ?string $sourceCreatedAt, - ?string $destCreatedAt, - ?string $sourceUpdatedAt, - ?string $destUpdatedAt, - bool $canDrop, - ): SchemaAction { - if ($this->createdAtDiffers($sourceCreatedAt, $destCreatedAt)) { - return $canDrop ? SchemaAction::DropAndRecreate : SchemaAction::UpdateInPlace; - } - - if ($this->sourceIsNewer($sourceUpdatedAt, $destUpdatedAt)) { - return SchemaAction::UpdateInPlace; - } - - return SchemaAction::Tolerate; - } - - private function createdAtDiffers(?string $source, ?string $dest): bool - { - $src = $this->parseTimestamp($source); - $dst = $this->parseTimestamp($dest); - return $src !== null && $dst !== null && $src !== $dst; - } - private function sourceIsNewer(?string $source, ?string $dest): bool { $src = $this->parseTimestamp($source); diff --git a/tests/Migration/Unit/General/OnDuplicateTest.php b/tests/Migration/Unit/General/OnDuplicateTest.php index c8b10e1a4a..cc32625823 100644 --- a/tests/Migration/Unit/General/OnDuplicateTest.php +++ b/tests/Migration/Unit/General/OnDuplicateTest.php @@ -9,19 +9,10 @@ use Utopia\Migration\Destinations\SchemaAction; /** * OnDuplicate::resolveSchemaAction is the load-bearing decision point for - * re-migration tolerance. These tests lock the mode × existence × createdAt × - * updatedAt × canDrop matrix so a future refactor can't silently shift the - * mapping. - * - * Decision rules under Upsert (with $exists = true): - * - createdAt differs → resource was deleted+recreated on source. Caller can - * drop and recreate (canDrop=true) or update in place (canDrop=false; for - * containers like databases/tables which would lose children on drop). - * - createdAt same + updatedAt newer → metadata-only edit. UpdateInPlace. - * The caller checks whether changed fields are SDK-updatable; if not it - * falls through to DropAndRecreate. - * - createdAt same + updatedAt equal/older → Tolerate. - * - Unparseable createdAt or updatedAt → conservative; treat as if no diff. + * re-migration tolerance. The destination then runs a spec-match guard that + * overrides UpdateInPlace to Tolerate when source and dest already have + * identical spec — see DestinationAppwrite. These tests lock the + * mode × existence × updatedAt matrix. */ class OnDuplicateTest extends TestCase { @@ -49,15 +40,11 @@ class OnDuplicateTest extends TestCase public function testSkipAlwaysToleratesExisting(): void { - // Skip must ignore createdAt/updatedAt entirely — it's the "don't - // touch" contract. Exercise both source-newer and dest-newer to prove - // comparisons aren't consulted. + // Skip must ignore updatedAt entirely — it's the "don't touch" contract. $this->assertSame( SchemaAction::Tolerate, OnDuplicate::Skip->resolveSchemaAction( exists: true, - sourceCreatedAt: '2020-01-01T00:00:00.000+00:00', - destCreatedAt: '2026-01-01T00:00:00.000+00:00', sourceUpdatedAt: '2026-01-01T00:00:00.000+00:00', destUpdatedAt: '2020-01-01T00:00:00.000+00:00', ), @@ -72,73 +59,36 @@ class OnDuplicateTest extends TestCase ); } - public function testUpsertCreatedAtDiffersOnLeafDropsAndRecreates(): void + public function testUpsertSourceNewerUpdatesInPlace(): void { - // canDrop: true + createdAt differs → leaf was deleted/recreated on - // source. Drop the destination's incarnation and create fresh. - $this->assertSame( - SchemaAction::DropAndRecreate, - OnDuplicate::Upsert->resolveSchemaAction( - exists: true, - sourceCreatedAt: '2026-04-23T10:00:00.000+00:00', - destCreatedAt: '2026-04-20T10:00:00.000+00:00', - canDrop: true, - ), - ); - } - - public function testUpsertCreatedAtDiffersOnContainerUpdatesInPlace(): void - { - // Default canDrop: false (containers like databases/tables). Even on - // createdAt diff, drop is forbidden — children would be lost. Fall - // back to UpdateInPlace. + // Source updatedAt strictly newer than dest → UpdateInPlace. The + // caller (DestinationAppwrite) follows up with attribute/index spec + // checks and falls through to drop+recreate when the SDK can't + // express the change. $this->assertSame( SchemaAction::UpdateInPlace, OnDuplicate::Upsert->resolveSchemaAction( exists: true, - sourceCreatedAt: '2026-04-23T10:00:00.000+00:00', - destCreatedAt: '2026-04-20T10:00:00.000+00:00', - ), - ); - } - - public function testUpsertCreatedAtSameUpdatedAtNewerUpdatesInPlace(): void - { - // Same createdAt + newer updatedAt → metadata-only edit on the same - // physical resource. UpdateInPlace; caller checks whether the changed - // fields are SDK-updatable and falls back to DropAndRecreate if not. - $this->assertSame( - SchemaAction::UpdateInPlace, - OnDuplicate::Upsert->resolveSchemaAction( - exists: true, - sourceCreatedAt: '2026-04-20T10:00:00.000+00:00', - destCreatedAt: '2026-04-20T10:00:00.000+00:00', sourceUpdatedAt: '2026-04-23T10:00:00.000+00:00', destUpdatedAt: '2026-04-23T09:59:59.000+00:00', - canDrop: true, ), ); } - public function testUpsertCreatedAtSameUpdatedAtEqualTolerates(): void + public function testUpsertSourceEqualTolerates(): void { - // Same createdAt + same updatedAt → nothing changed. Skip the work. - $created = '2026-04-20T10:00:00.000+00:00'; - $updated = '2026-04-23T10:00:00.000+00:00'; + $when = '2026-04-23T10:00:00.000+00:00'; $this->assertSame( SchemaAction::Tolerate, OnDuplicate::Upsert->resolveSchemaAction( exists: true, - sourceCreatedAt: $created, - destCreatedAt: $created, - sourceUpdatedAt: $updated, - destUpdatedAt: $updated, - canDrop: true, + sourceUpdatedAt: $when, + destUpdatedAt: $when, ), ); } - public function testUpsertCreatedAtSameUpdatedAtOlderTolerates(): void + public function testUpsertSourceOlderTolerates(): void { // Dest is ahead — don't roll back. Avoids overwriting newer // destination edits with stale source data. @@ -146,11 +96,8 @@ class OnDuplicateTest extends TestCase SchemaAction::Tolerate, OnDuplicate::Upsert->resolveSchemaAction( exists: true, - sourceCreatedAt: '2026-04-20T10:00:00.000+00:00', - destCreatedAt: '2026-04-20T10:00:00.000+00:00', sourceUpdatedAt: '2026-04-23T09:00:00.000+00:00', destUpdatedAt: '2026-04-23T10:00:00.000+00:00', - canDrop: true, ), ); } @@ -158,29 +105,10 @@ class OnDuplicateTest extends TestCase public function testUpsertNoTimestampsTolerates(): void { // No timestamps provided at all → no information to act on. Conservative: - // Tolerate rather than risk destructive action on uncertain input. + // Tolerate rather than risk a destructive update on uncertain input. $this->assertSame( SchemaAction::Tolerate, - OnDuplicate::Upsert->resolveSchemaAction( - exists: true, - canDrop: true, - ), - ); - } - - public function testUpsertOnlyUpdatedAtNewerWithoutCreatedAtUpdatesInPlace(): void - { - // CreatedAt missing on either side (e.g. older Appwrite versions, CSV - // sources): can't detect "recreated", so the only signal is updatedAt. - // Newer source → UpdateInPlace path (caller validates SDK-updatability). - $this->assertSame( - SchemaAction::UpdateInPlace, - OnDuplicate::Upsert->resolveSchemaAction( - exists: true, - sourceUpdatedAt: '2026-04-23T10:00:00.000+00:00', - destUpdatedAt: '2026-04-23T09:59:59.000+00:00', - canDrop: true, - ), + OnDuplicate::Upsert->resolveSchemaAction(exists: true), ); } @@ -203,23 +131,6 @@ class OnDuplicateTest extends TestCase ]; } - #[DataProvider('unparseableTimestampPairs')] - public function testUpsertUnparseableCreatedAtDoesNotTriggerDrop(?string $source, ?string $dest): void - { - // Unparseable createdAt → don't trigger DropAndRecreate. With - // updatedAt also absent, falls through to Tolerate. Safety net for - // sources that emit malformed timestamps. - $this->assertSame( - SchemaAction::Tolerate, - OnDuplicate::Upsert->resolveSchemaAction( - exists: true, - sourceCreatedAt: $source, - destCreatedAt: $dest, - canDrop: true, - ), - ); - } - #[DataProvider('unparseableTimestampPairs')] public function testUpsertUnparseableUpdatedAtTolerates(?string $source, ?string $dest): void { From aa1e7c706326542a050354635f4290df43f06443 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Tue, 28 Apr 2026 07:03:39 +0100 Subject: [PATCH 53/91] Fix two greptile-flagged P1 bugs in createField MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 1. Stale $table after dropAttributeForRecreate caused false LimitException $table is loaded once at the top of createField. After dropAttributeForRecreate runs (UpdateInPlace fallthrough), the meta doc + physical column are gone from the DB but the in-memory $table object still has the dropped entry in its 'attributes' array. utopia's checkAttribute clones $table and appends the new attribute, then asks the adapter for getCountOfAttributes — at the adapter ceiling this throws LimitException even though the net change is zero. Fix: re-fetch $table after dropAttributeForRecreate. 2. Partner meta-doc deleted from wrong table when relatedCollection changes dropAttributeForRecreate looked up the partner meta via $resource->getOptions() — source's options. But it runs precisely when RELATIONSHIP_STRUCTURAL_FIELDS differ (relatedCollection, twoWayKey, etc), so source's options point to the NEW partner table while dest's existing partner meta lives on the OLD partner table. The OLD partner meta was left orphaned forever. Fix: pass $existingAttr through to dropAttributeForRecreate and use its 'options' (dest's current state) for partner resolution. --- src/Migration/Destinations/Appwrite.php | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index d215452d8d..eae78d9971 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -837,7 +837,14 @@ class Appwrite extends Destination } if ($action === SchemaAction::UpdateInPlace) { - $this->dropAttributeForRecreate($database, $table, $resource, $dbForDatabases); + $this->dropAttributeForRecreate($database, $table, $resource, $dbForDatabases, $existingAttr); + // Re-fetch $table: the in-memory copy still holds the dropped + // attribute, so checkAttribute below would over-count and trip + // the adapter's LimitException at the column ceiling. + $table = $this->dbForProject->getDocument( + $this->databaseCollectionId($database), + $table->getId(), + ); } } @@ -1332,6 +1339,7 @@ class Appwrite extends Destination UtopiaDocument $table, Column|Attribute $resource, UtopiaDatabase $dbForDatabases, + ?UtopiaDocument $existingAttr = null, ): void { $collectionId = $this->tableCollectionId($database, $table); $attributeMetaId = $this->attributeIndexMetaId($database, $table, $resource->getKey()); @@ -1346,8 +1354,13 @@ class Appwrite extends Destination $this->dbForProject->deleteDocument(self::META_ATTRIBUTES, $attributeMetaId); // deleteRelationship only touches utopia's _metadata; clear the Appwrite-level partner meta doc too. + // Use dest's options ($existingAttr): we drop precisely when relatedCollection/twoWayKey differ, + // so source's options point to the NEW partner; the OLD partner meta lives where dest currently has it. if ($isRelationship) { - $partner = $this->resolveTwoWayPartner($database, $resource->getOptions()); + $options = $existingAttr !== null && !$existingAttr->isEmpty() + ? (array) $existingAttr->getAttribute('options', []) + : $resource->getOptions(); + $partner = $this->resolveTwoWayPartner($database, $options); if ($partner !== null) { $this->bestEffort(fn () => $this->dbForProject->deleteDocument(self::META_ATTRIBUTES, $partner['partnerMetaId'])); } From 4c3965bc89557109d80ee1443f0efa59c07c8465 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Tue, 28 Apr 2026 07:11:04 +0100 Subject: [PATCH 54/91] Tighten dropAttributeForRecreate: required $existingAttr, trimmed comments MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit $existingAttr is always non-empty at the only call site (UpdateInPlace fallthrough requires $exists=true). Drops the unreachable nullable fallback path and the defensive isEmpty() check. Comments collapsed to one line each — the WHY is small enough to fit. --- src/Migration/Destinations/Appwrite.php | 25 ++++++------------------- 1 file changed, 6 insertions(+), 19 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index eae78d9971..ee70a8c4e4 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -838,13 +838,8 @@ class Appwrite extends Destination if ($action === SchemaAction::UpdateInPlace) { $this->dropAttributeForRecreate($database, $table, $resource, $dbForDatabases, $existingAttr); - // Re-fetch $table: the in-memory copy still holds the dropped - // attribute, so checkAttribute below would over-count and trip - // the adapter's LimitException at the column ceiling. - $table = $this->dbForProject->getDocument( - $this->databaseCollectionId($database), - $table->getId(), - ); + // Reload $table — in-memory copy still holds the dropped attribute, so checkAttribute would over-count. + $table = $this->dbForProject->getDocument($this->databaseCollectionId($database), $table->getId()); } } @@ -1330,16 +1325,13 @@ class Appwrite extends Destination return true; } - /** - * Drop attribute (meta doc + physical column). Relationships route through - * deleteRelationship since deleteAttribute throws for VAR_RELATIONSHIP. - */ + /** Relationships route through deleteRelationship since deleteAttribute throws for VAR_RELATIONSHIP. */ private function dropAttributeForRecreate( UtopiaDocument $database, UtopiaDocument $table, Column|Attribute $resource, UtopiaDatabase $dbForDatabases, - ?UtopiaDocument $existingAttr = null, + UtopiaDocument $existingAttr, ): void { $collectionId = $this->tableCollectionId($database, $table); $attributeMetaId = $this->attributeIndexMetaId($database, $table, $resource->getKey()); @@ -1353,14 +1345,9 @@ class Appwrite extends Destination $this->dbForProject->deleteDocument(self::META_ATTRIBUTES, $attributeMetaId); - // deleteRelationship only touches utopia's _metadata; clear the Appwrite-level partner meta doc too. - // Use dest's options ($existingAttr): we drop precisely when relatedCollection/twoWayKey differ, - // so source's options point to the NEW partner; the OLD partner meta lives where dest currently has it. + // Use dest's options for partner lookup — drop fires when relatedCollection/twoWayKey differ, so source points to the NEW partner. if ($isRelationship) { - $options = $existingAttr !== null && !$existingAttr->isEmpty() - ? (array) $existingAttr->getAttribute('options', []) - : $resource->getOptions(); - $partner = $this->resolveTwoWayPartner($database, $options); + $partner = $this->resolveTwoWayPartner($database, (array) $existingAttr->getAttribute('options', [])); if ($partner !== null) { $this->bestEffort(fn () => $this->dbForProject->deleteDocument(self::META_ATTRIBUTES, $partner['partnerMetaId'])); } From d37efed0d977a5f0c164861e58fc807763b1115f Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Tue, 28 Apr 2026 07:55:53 +0100 Subject: [PATCH 55/91] Track partner key for two-way orphan cleanup MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Greptile #2: source-side filter (Sources/Appwrite::exportColumns) skips RELATION_SIDE_CHILD, so the partner meta-doc created inline inside the parent's createField never reaches the partner table's createField path — and therefore never gets registered with trackOrphanCandidate. If any other column on the partner table is migrated, orphan cleanup sees the partner key absent from the tracked set and deletes it, breaking the relationship's child side. Adds a trackOrphanCandidate call right after the inline createDocument so the partner key is registered against $relatedTable. Phpstan note: adding the strict-typed call inside the existing relationship block shifted phpstan's narrowing analysis and made it flag two pre-existing $relatedTable usages (createRelationship at line 957 and purgeCachedDocument at line 1004). Both are reachable only when type === VAR_RELATIONSHIP, where $relatedTable is guaranteed defined. Suppressed with @phpstan-ignore-next-line on those two specific lines. --- src/Migration/Destinations/Appwrite.php | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index ee70a8c4e4..c710570ecc 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -923,6 +923,7 @@ class Appwrite extends Destination ]); $this->dbForProject->createDocument(self::META_ATTRIBUTES, $twoWayAttribute); + $this->trackOrphanCandidate($database, $relatedTable, 'attributeKeys', $twoWayKey, $dbForDatabases); } catch (DuplicateException) { $this->dbForProject->deleteDocument(self::META_ATTRIBUTES, $column->getId()); @@ -952,6 +953,7 @@ class Appwrite extends Destination case UtopiaDatabase::VAR_RELATIONSHIP: if (!$dbForDatabases->createRelationship( collection: $this->tableCollectionId($database, $table), + // @phpstan-ignore-next-line — $relatedTable is set when type is VAR_RELATIONSHIP. relatedCollection: $this->tableCollectionId($database, $relatedTable), type: $options['relationType'], twoWay: $options['twoWay'], @@ -1000,6 +1002,7 @@ class Appwrite extends Destination } if ($type === UtopiaDatabase::VAR_RELATIONSHIP && $options['twoWay']) { + // @phpstan-ignore-next-line — $relatedTable is set when type is VAR_RELATIONSHIP. $this->dbForProject->purgeCachedDocument($this->databaseCollectionId($database), $relatedTable->getId()); } From 7d71505ec0a5731f322bbdc83cc9bee32053df2e Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Tue, 28 Apr 2026 08:10:11 +0100 Subject: [PATCH 56/91] createIndex: run pre-check + drop before count and IndexValidator MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Greptile: $count (META_INDEXES query) and IndexValidator both ran BEFORE the pre-check / drop block. On an Upsert recreate path: - The to-be-dropped index was included in the count, so a table at getLimitForIndexes() falsely threw 'Index limit reached' even though the net change is zero (one drop, one add). - IndexValidator was initialized with $tableIndexes from the in-memory $table — including the existing index — so the new index spec could be flagged as a conflict against itself ('Invalid index: …') before the drop ran. Reordered createIndex so: 1. Pre-check + drop block runs first (Tolerate returns early). 2. $table is reloaded after a drop so embedded $tableIndexes reflects the post-drop state. 3. count, validateFieldsForIndexes, build $index, IndexValidator all run AFTER the drop, against the fresh $table. Mirrors the attribute path's structure where checkAttribute already runs after dropAttributeForRecreate. --- src/Migration/Destinations/Appwrite.php | 85 +++++++++++++------------ 1 file changed, 45 insertions(+), 40 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index c710570ecc..a9254e57fa 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -1048,6 +1048,50 @@ class Appwrite extends Destination } $dbForDatabases = ($this->getDatabasesDB)($database); + $createdAt = $this->normalizeDateTime($resource->getCreatedAt()); + $updatedAt = $this->normalizeDateTime($resource->getUpdatedAt(), $createdAt); + + $this->trackOrphanCandidate($database, $table, 'indexKeys', $resource->getKey(), $dbForDatabases); + + $indexMetaId = $this->attributeIndexMetaId($database, $table, $resource->getKey()); + + // 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 + // ceiling throws "Index limit reached" or "Invalid index" even though the net change is zero). + if ($this->onDuplicate !== OnDuplicate::Fail) { + $existingIdx = $this->dbForProject->getDocument(self::META_INDEXES, $indexMetaId); + $action = $this->onDuplicate->resolveSchemaAction( + !$existingIdx->isEmpty(), + $updatedAt, + $existingIdx->getUpdatedAt(), + ); + // Spec match → skip work. Create excluded; nothing on dest to match against. + if ($action !== SchemaAction::Create && $this->indexSpecMatches($existingIdx, $resource)) { + $action = SchemaAction::Tolerate; + } + + // Indexes have no in-place primitive — any action other than Tolerate falls through to drop+recreate. + $earlyReturn = match ($action) { + SchemaAction::Tolerate => (function () use ($resource, $database, $table): bool { + $this->dbForProject->purgeCachedDocument($this->databaseCollectionId($database), $table->getId()); + $resource->setStatus(Resource::STATUS_SKIPPED, 'Already exists on destination'); + return false; + })(), + SchemaAction::UpdateInPlace, SchemaAction::Create => null, + }; + if ($earlyReturn !== null) { + return $earlyReturn; + } + + if ($action === SchemaAction::UpdateInPlace) { + $dbForDatabases->deleteIndex($this->tableCollectionId($database, $table), $resource->getKey()); + $this->dbForProject->deleteDocument(self::META_INDEXES, $indexMetaId); + $this->dbForProject->purgeCachedDocument($this->databaseCollectionId($database), $table->getId()); + // Reload $table — in-memory copy still holds the dropped index, so IndexValidator below would over-count. + $table = $this->dbForProject->getDocument($this->databaseCollectionId($database), $table->getId()); + } + } + $count = $this->dbForProject->count(self::META_INDEXES, [ Query::equal('collectionInternalId', [$table->getSequence()]), Query::equal('databaseInternalId', [$database->getSequence()]) @@ -1069,13 +1113,8 @@ class Appwrite extends Destination $this->validateFieldsForIndexes($resource, $table, $lengths); } - $createdAt = $this->normalizeDateTime($resource->getCreatedAt()); - $updatedAt = $this->normalizeDateTime($resource->getUpdatedAt(), $createdAt); - - $this->trackOrphanCandidate($database, $table, 'indexKeys', $resource->getKey(), $dbForDatabases); - $index = new UtopiaDocument([ - '$id' => ID::custom($this->attributeIndexMetaId($database, $table, $resource->getKey())), + '$id' => ID::custom($indexMetaId), 'key' => $resource->getKey(), 'status' => 'available', // processing, available, failed, deleting, stuck 'databaseInternalId' => $database->getSequence(), @@ -1116,7 +1155,6 @@ class Appwrite extends Destination $dbForDatabases->getAdapter()->getSupportForFulltextIndex() ); - if (!$validator->isValid($index)) { throw new Exception( resourceName: $resource->getName(), @@ -1126,39 +1164,6 @@ class Appwrite extends Destination ); } - $indexMetaId = $this->attributeIndexMetaId($database, $table, $resource->getKey()); - if ($this->onDuplicate !== OnDuplicate::Fail) { - $existingIdx = $this->dbForProject->getDocument(self::META_INDEXES, $indexMetaId); - $action = $this->onDuplicate->resolveSchemaAction( - !$existingIdx->isEmpty(), - $updatedAt, - $existingIdx->getUpdatedAt(), - ); - // Spec match → skip work. Create excluded; nothing on dest to match against. - if ($action !== SchemaAction::Create && $this->indexSpecMatches($existingIdx, $resource)) { - $action = SchemaAction::Tolerate; - } - - // Indexes have no in-place primitive — any action other than Tolerate falls through to drop+recreate. - $earlyReturn = match ($action) { - SchemaAction::Tolerate => (function () use ($resource, $database, $table): bool { - $this->dbForProject->purgeCachedDocument($this->databaseCollectionId($database), $table->getId()); - $resource->setStatus(Resource::STATUS_SKIPPED, 'Already exists on destination'); - return false; - })(), - SchemaAction::UpdateInPlace, SchemaAction::Create => null, - }; - if ($earlyReturn !== null) { - return $earlyReturn; - } - - if ($action === SchemaAction::UpdateInPlace) { - $dbForDatabases->deleteIndex($this->tableCollectionId($database, $table), $resource->getKey()); - $this->dbForProject->deleteDocument(self::META_INDEXES, $indexMetaId); - $this->dbForProject->purgeCachedDocument($this->databaseCollectionId($database), $table->getId()); - } - } - $index = $this->dbForProject->createDocument(self::META_INDEXES, $index); try { From 2b7e29ea83315e2a2444d152a8dd545ac07614c6 Mon Sep 17 00:00:00 2001 From: Chirag Aggarwal Date: Wed, 29 Apr 2026 15:47:12 +0530 Subject: [PATCH 57/91] Remove deprecated curl_close calls --- src/Migration/Target.php | 1 - tests/Migration/E2E/Sources/Base.php | 1 - 2 files changed, 2 deletions(-) diff --git a/src/Migration/Target.php b/src/Migration/Target.php index 8dbc5a87f2..777609f22a 100644 --- a/src/Migration/Target.php +++ b/src/Migration/Target.php @@ -150,7 +150,6 @@ abstract class Target throw new \Exception(\curl_error($ch), Exception::CODE_INTERNAL); } - \curl_close($ch); if ($responseStatus >= 400) { if (\is_array($responseBody)) { diff --git a/tests/Migration/E2E/Sources/Base.php b/tests/Migration/E2E/Sources/Base.php index 7b5bd403e8..9563344e3a 100644 --- a/tests/Migration/E2E/Sources/Base.php +++ b/tests/Migration/E2E/Sources/Base.php @@ -124,7 +124,6 @@ abstract class Base extends TestCase throw new \Exception(curl_error($ch)); } - curl_close($ch); if ($responseStatus >= 400) { if (is_array($responseBody)) { From 5520cb2585ce2498699937e6ef9e0706cfcd1f00 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Thu, 30 Apr 2026 11:21:31 +0100 Subject: [PATCH 58/91] Rename SDK-boundary constants to IMMUTABLE_FIELDS; fix META doc Maintainer review feedback: - ATTRIBUTE_NON_SDK_FIELDS -> ATTRIBUTE_IMMUTABLE_FIELDS - RELATIONSHIP_STRUCTURAL_FIELDS -> RELATIONSHIP_IMMUTABLE_FIELDS - META_* docblock 'platform-DB' -> 'project-DB' (these collections live in dbForProject, not the platform-level DB) Naming shift: "NON_SDK"/"STRUCTURAL" describes the cause (SDK doesn't expose them), "IMMUTABLE" describes the effect (can't change in place, only via drop+recreate). The latter is the audience-facing semantic. SDK-boundary lock-in test (AppwriteAttributeSdkBoundaryTest) still reflects on the renamed constant; updated its references. --- src/Migration/Destinations/Appwrite.php | 18 +++++++++--------- .../AppwriteAttributeSdkBoundaryTest.php | 10 +++++----- 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index a9254e57fa..ca0b9cd30b 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -63,13 +63,13 @@ use Utopia\Migration\Transfer; class Appwrite extends Destination { - /** Names of the platform-DB collections holding Appwrite schema metadata. */ + /** Names of the project-DB collections holding Appwrite schema metadata. */ private const META_DATABASES = 'databases'; private const META_ATTRIBUTES = 'attributes'; private const META_INDEXES = 'indexes'; - /** Fields the SDK's per-type updateXAttribute endpoints don't expose; a change here forces drop+recreate. */ - private const ATTRIBUTE_NON_SDK_FIELDS = [ + /** Attribute fields the SDK can't update in place (no per-type updateX endpoint exposes them); a change here forces drop+recreate. */ + private const ATTRIBUTE_IMMUTABLE_FIELDS = [ 'type', 'array', 'signed', @@ -78,8 +78,8 @@ class Appwrite extends Destination 'filters', ]; - /** Fields the SDK's updateRelationshipAttribute doesn't expose (only onDelete/newKey are SDK-reachable). */ - private const RELATIONSHIP_STRUCTURAL_FIELDS = [ + /** Relationship options fields the SDK can't update in place (only onDelete/newKey are SDK-reachable); a change here forces drop+recreate. */ + private const RELATIONSHIP_IMMUTABLE_FIELDS = [ 'relationType', 'twoWay', 'twoWayKey', @@ -1384,11 +1384,11 @@ class Appwrite extends Destination ]; $existingFields = []; - foreach (self::ATTRIBUTE_NON_SDK_FIELDS as $field) { + foreach (self::ATTRIBUTE_IMMUTABLE_FIELDS as $field) { $existingFields[$field] = $existingAttr->getAttribute($field); } - if ($this->arraysDifferOnKeys($sourceFields, $existingFields, self::ATTRIBUTE_NON_SDK_FIELDS)) { + if ($this->arraysDifferOnKeys($sourceFields, $existingFields, self::ATTRIBUTE_IMMUTABLE_FIELDS)) { return false; } @@ -1441,7 +1441,7 @@ class Appwrite extends Destination $sourceOptions = $resource->getOptions(); $destOptions = $existingAttr->getAttribute('options', []); - if ($this->arraysDifferOnKeys($sourceOptions, $destOptions, self::RELATIONSHIP_STRUCTURAL_FIELDS)) { + if ($this->arraysDifferOnKeys($sourceOptions, $destOptions, self::RELATIONSHIP_IMMUTABLE_FIELDS)) { return false; } @@ -1548,7 +1548,7 @@ class Appwrite extends Destination $sourceOptions = $resource->getOptions(); /** @var array $destOptions */ $destOptions = $existing->getAttribute('options', []); - foreach (self::RELATIONSHIP_STRUCTURAL_FIELDS as $field) { + foreach (self::RELATIONSHIP_IMMUTABLE_FIELDS as $field) { if (!$this->valuesMatch($sourceOptions[$field] ?? null, $destOptions[$field] ?? null)) { return false; } diff --git a/tests/Migration/Unit/Destinations/AppwriteAttributeSdkBoundaryTest.php b/tests/Migration/Unit/Destinations/AppwriteAttributeSdkBoundaryTest.php index 3b2fdddc33..a079ea61fb 100644 --- a/tests/Migration/Unit/Destinations/AppwriteAttributeSdkBoundaryTest.php +++ b/tests/Migration/Unit/Destinations/AppwriteAttributeSdkBoundaryTest.php @@ -10,12 +10,12 @@ use ReflectionMethod; use Utopia\Migration\Destinations\Appwrite as AppwriteDestination; /** - * Lock-in for the SDK boundary that drives ATTRIBUTE_NON_SDK_FIELDS. + * Lock-in for the SDK boundary that drives ATTRIBUTE_IMMUTABLE_FIELDS. * * Reflects on appwrite/appwrite's TablesDB + Databases services. If the SDK * ships a new updateXColumn / updateXAttribute endpoint that exposes a * previously-non-SDK field, this test fails so DestinationAppwrite's - * ATTRIBUTE_NON_SDK_FIELDS constant can be synced. Catches drift in CI + * ATTRIBUTE_IMMUTABLE_FIELDS constant can be synced. Catches drift in CI * rather than at runtime. */ class AppwriteAttributeSdkBoundaryTest extends TestCase @@ -47,9 +47,9 @@ class AppwriteAttributeSdkBoundaryTest extends TestCase $this->assertSame( [], \array_values($overlap), - 'ATTRIBUTE_NON_SDK_FIELDS marks these fields as non-SDK, but the appwrite/appwrite ' + 'ATTRIBUTE_IMMUTABLE_FIELDS marks these fields as non-SDK, but the appwrite/appwrite ' . 'SDK exposes them via updateXColumn/updateXAttribute: ' . \implode(', ', $overlap) - . '. Either drop these from ATTRIBUTE_NON_SDK_FIELDS or update PARAM_TO_META_FIELD ' + . '. Either drop these from ATTRIBUTE_IMMUTABLE_FIELDS or update PARAM_TO_META_FIELD ' . 'in this test if the SDK param doesn\'t correspond to a top-level meta-doc field.', ); } @@ -90,7 +90,7 @@ class AppwriteAttributeSdkBoundaryTest extends TestCase private function readNonSdkConstant(): array { /** @var list $value */ - $value = (new ReflectionClass(AppwriteDestination::class))->getConstant('ATTRIBUTE_NON_SDK_FIELDS'); + $value = (new ReflectionClass(AppwriteDestination::class))->getConstant('ATTRIBUTE_IMMUTABLE_FIELDS'); return $value; } } From b8ae7bc953d1897994eaa0de7e677687a19e5133 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Thu, 30 Apr 2026 11:24:12 +0100 Subject: [PATCH 59/91] Rename OnDuplicate::Upsert -> OnDuplicate::Overwrite MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- src/Migration/Destinations/Appwrite.php | 20 ++++++++--------- src/Migration/Destinations/OnDuplicate.php | 4 ++-- .../Unit/General/OnDuplicateTest.php | 22 +++++++++---------- 3 files changed, 23 insertions(+), 23 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index ca0b9cd30b..fb25bb55ea 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -109,7 +109,7 @@ class Appwrite extends Destination 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 * after their cleanup runs so the end-of-run sweep only visits tables * that had no rows. @@ -178,7 +178,7 @@ class Appwrite extends Destination ): void { $this->resetRunState(); parent::run($resources, $callback, $rootResourceId, $rootResourceType); - $this->cleanupUpsertOrphans(); + $this->cleanupOverwriteOrphans(); } /** 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()); // 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). if ($this->onDuplicate !== OnDuplicate::Fail) { $existingIdx = $this->dbForProject->getDocument(self::META_INDEXES, $indexMetaId); @@ -1284,7 +1284,7 @@ class Appwrite extends Destination $dbForDatabases = ($this->getDatabasesDB)($database); // 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. if ($dbForDatabases->getAdapter()->getSupportForAttributes()) { foreach ($this->rowBuffer as $row) { @@ -1311,7 +1311,7 @@ class Appwrite extends Destination $collectionId = $this->tableCollectionId($database, $table); match ($this->onDuplicate) { - OnDuplicate::Upsert => $dbForDatabases->skipRelationshipsExistCheck( + OnDuplicate::Overwrite => $dbForDatabases->skipRelationshipsExistCheck( fn () => $dbForDatabases->upsertDocuments($collectionId, $this->rowBuffer) ), OnDuplicate::Skip => $dbForDatabases->skipDuplicates( @@ -1699,7 +1699,7 @@ class Appwrite extends Destination string $key, UtopiaDatabase $dbForDatabases, ): void { - if ($this->onDuplicate !== OnDuplicate::Upsert) { + if ($this->onDuplicate !== OnDuplicate::Overwrite) { return; } $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). */ - private function cleanupUpsertOrphans(): void + private function cleanupOverwriteOrphans(): void { 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. */ - private function cleanupUpsertOrphansForTable(string $tableId): void + private function cleanupOverwriteOrphansForTable(string $tableId): void { - if ($this->onDuplicate !== OnDuplicate::Upsert) { + if ($this->onDuplicate !== OnDuplicate::Overwrite) { return; } if (!isset($this->orphansByTable[$tableId])) { diff --git a/src/Migration/Destinations/OnDuplicate.php b/src/Migration/Destinations/OnDuplicate.php index 69b4cdf8f2..3ba945c005 100644 --- a/src/Migration/Destinations/OnDuplicate.php +++ b/src/Migration/Destinations/OnDuplicate.php @@ -13,7 +13,7 @@ enum OnDuplicate: string { case Fail = 'fail'; case Skip = 'skip'; - case Upsert = 'upsert'; + case Overwrite = 'overwrite'; /** * @return list @@ -39,7 +39,7 @@ enum OnDuplicate: string return match ($this) { self::Fail => SchemaAction::Create, self::Skip => SchemaAction::Tolerate, - self::Upsert => $this->sourceIsNewer($sourceUpdatedAt, $destUpdatedAt) + self::Overwrite => $this->sourceIsNewer($sourceUpdatedAt, $destUpdatedAt) ? SchemaAction::UpdateInPlace : SchemaAction::Tolerate, }; diff --git a/tests/Migration/Unit/General/OnDuplicateTest.php b/tests/Migration/Unit/General/OnDuplicateTest.php index cc32625823..0141cb5d33 100644 --- a/tests/Migration/Unit/General/OnDuplicateTest.php +++ b/tests/Migration/Unit/General/OnDuplicateTest.php @@ -59,7 +59,7 @@ class OnDuplicateTest extends TestCase ); } - public function testUpsertSourceNewerUpdatesInPlace(): void + public function testOverwriteSourceNewerUpdatesInPlace(): void { // Source updatedAt strictly newer than dest → UpdateInPlace. The // caller (DestinationAppwrite) follows up with attribute/index spec @@ -67,7 +67,7 @@ class OnDuplicateTest extends TestCase // express the change. $this->assertSame( SchemaAction::UpdateInPlace, - OnDuplicate::Upsert->resolveSchemaAction( + OnDuplicate::Overwrite->resolveSchemaAction( exists: true, sourceUpdatedAt: '2026-04-23T10:00:00.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'; $this->assertSame( SchemaAction::Tolerate, - OnDuplicate::Upsert->resolveSchemaAction( + OnDuplicate::Overwrite->resolveSchemaAction( exists: true, sourceUpdatedAt: $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 // destination edits with stale source data. $this->assertSame( SchemaAction::Tolerate, - OnDuplicate::Upsert->resolveSchemaAction( + OnDuplicate::Overwrite->resolveSchemaAction( exists: true, sourceUpdatedAt: '2026-04-23T09: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: // Tolerate rather than risk a destructive update on uncertain input. $this->assertSame( SchemaAction::Tolerate, - OnDuplicate::Upsert->resolveSchemaAction(exists: true), + OnDuplicate::Overwrite->resolveSchemaAction(exists: true), ); } @@ -132,13 +132,13 @@ class OnDuplicateTest extends TestCase } #[DataProvider('unparseableTimestampPairs')] - public function testUpsertUnparseableUpdatedAtTolerates(?string $source, ?string $dest): void + public function testOverwriteUnparseableUpdatedAtTolerates(?string $source, ?string $dest): void { // Conservative: unparseable updatedAt preserves existing destination // rather than risk a destructive update on garbage input. $this->assertSame( SchemaAction::Tolerate, - OnDuplicate::Upsert->resolveSchemaAction( + OnDuplicate::Overwrite->resolveSchemaAction( exists: true, sourceUpdatedAt: $source, destUpdatedAt: $dest, @@ -150,6 +150,6 @@ class OnDuplicateTest extends TestCase { // The values() helper is consumed by API/SDK param validators; this // protects against an accidental case-rename or reorder. - $this->assertSame(['fail', 'skip', 'upsert'], OnDuplicate::values()); + $this->assertSame(['fail', 'skip', 'overwrite'], OnDuplicate::values()); } } From dfb0224ce18310a5bd7dd2676201909e6dec6525 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Thu, 30 Apr 2026 11:59:43 +0100 Subject: [PATCH 60/91] createRecord: reload $table after orphan cleanup before field-strip MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Greptile #3167268161: cleanupOverwriteOrphansForTable removes orphan attributes from dest's META_ATTRIBUTES + physical schema, but the in-memory $table object still holds them in its 'attributes' array. The field-strip loop right after iterates $table->getAttribute( 'attributes') to decide which row payload fields to keep — finds the orphan as 'valid' and leaves it in the row. Subsequent upsertDocuments hits the post-cleanup schema, structure validator rejects the row. Fix: reload $table immediately after orphan cleanup. Mirrors the attribute-path and index-path stale-$table fixes. --- src/Migration/Destinations/Appwrite.php | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index c23de53d5c..5b8047c671 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -1288,6 +1288,11 @@ class Appwrite extends Destination // Drop schema orphans before rows land so the Structure validator doesn't reject on orphan required columns. $this->cleanupOverwriteOrphansForTable($this->tableIdentity($database, $table)); + // Reload $table — in-memory copy still holds the dropped attributes, so the strip loop below would over-keep. + $table = $this->dbForProject->getDocument( + $this->databaseCollectionId($database), + $resource->getTable()->getId(), + ); // Strip row payload fields the table doesn't declare — guards against orphans surviving in source archives. if ($dbForDatabases->getAdapter()->getSupportForAttributes()) { foreach ($this->rowBuffer as $row) { From d7c3d0536dbb9e37a4894cd0b3b0134a483e04e8 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Thu, 30 Apr 2026 12:08:08 +0100 Subject: [PATCH 61/91] Rename SchemaAction cases to match Appwrite terms MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Jake's review on PR #171 (line 9 of OnDuplicate.php — SchemaAction enum): align the SchemaAction case names with Appwrite's user-facing terms (skip / overwrite / fail). - SchemaAction::Tolerate -> SchemaAction::Skip - SchemaAction::UpdateInPlace -> SchemaAction::Overwrite - SchemaAction::Create kept (no Appwrite equivalent; means 'no existing dest doc, run the create flow') Now the inner machinery uses the same vocabulary as the user-facing OnDuplicate enum (Fail / Skip / Overwrite). Comments and test method names updated to match (Tolerate -> Skip, UpdateInPlace -> Overwrite where they refer to the action — the test name 'UpdatesInPlace' as a verb phrase stays). --- src/Migration/Destinations/Appwrite.php | 32 ++++++++--------- src/Migration/Destinations/OnDuplicate.php | 12 +++---- .../Unit/General/OnDuplicateTest.php | 34 +++++++++---------- 3 files changed, 39 insertions(+), 39 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index 5b8047c671..41023b1a65 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -501,16 +501,16 @@ class Appwrite extends Destination ); // Spec match → skip work. Create excluded; nothing on dest to match against. if ($action !== SchemaAction::Create && $this->databaseSpecMatches($existing, $resource)) { - $action = SchemaAction::Tolerate; + $action = SchemaAction::Skip; } $earlyReturn = match ($action) { - SchemaAction::Tolerate => (function () use ($resource, $existing): bool { + SchemaAction::Skip => (function () use ($resource, $existing): bool { $resource->setSequence($existing->getSequence()); $resource->setStatus(Resource::STATUS_SKIPPED, 'Already exists on destination'); return false; })(), - SchemaAction::UpdateInPlace => (function () use ($resource, $existing, $updatedAt): bool { + SchemaAction::Overwrite => (function () use ($resource, $existing, $updatedAt): bool { $this->dbForProject->updateDocument(self::META_DATABASES, $existing->getId(), new UtopiaDocument([ 'name' => $resource->getDatabaseName(), 'search' => implode(' ', [$resource->getId(), $resource->getDatabaseName()]), @@ -623,16 +623,16 @@ class Appwrite extends Destination ); // Spec match → skip work. Create excluded; nothing on dest to match against. if ($action !== SchemaAction::Create && $this->tableSpecMatches($existing, $resource)) { - $action = SchemaAction::Tolerate; + $action = SchemaAction::Skip; } $earlyReturn = match ($action) { - SchemaAction::Tolerate => (function () use ($resource, $existing): bool { + SchemaAction::Skip => (function () use ($resource, $existing): bool { $resource->setSequence($existing->getSequence()); $resource->setStatus(Resource::STATUS_SKIPPED, 'Already exists on destination'); return false; })(), - SchemaAction::UpdateInPlace => (function () use ($resource, $existing, $database, $updatedAt): bool { + SchemaAction::Overwrite => (function () use ($resource, $existing, $database, $updatedAt): bool { $this->dbForProject->updateDocument( $this->databaseCollectionId($database), $existing->getId(), @@ -816,16 +816,16 @@ class Appwrite extends Destination ); // Spec match → skip work. Create excluded; nothing on dest to match against. if ($action !== SchemaAction::Create && $this->attributeSpecMatches($existingAttr, $resource, $type, $isRelationship)) { - $action = SchemaAction::Tolerate; + $action = SchemaAction::Skip; } $earlyReturn = match ($action) { - SchemaAction::Tolerate => (function () use ($resource, $database, $table, $dbForDatabases): bool { + SchemaAction::Skip => (function () use ($resource, $database, $table, $dbForDatabases): bool { $this->purgeTableCaches($database, $table, $dbForDatabases); $resource->setStatus(Resource::STATUS_SKIPPED, 'Already exists on destination'); return false; })(), - SchemaAction::UpdateInPlace => ($isRelationship + SchemaAction::Overwrite => ($isRelationship ? $this->updateRelationshipInPlace($database, $table, $resource, $type, $updatedAt, $existingAttr, $dbForDatabases) : $this->updateAttributeInPlace($database, $table, $resource, $type, $updatedAt, $existingAttr, $dbForDatabases)) ? true @@ -839,7 +839,7 @@ class Appwrite extends Destination return $earlyReturn; } - if ($action === SchemaAction::UpdateInPlace) { + if ($action === SchemaAction::Overwrite) { $this->dropAttributeForRecreate($database, $table, $resource, $dbForDatabases, $existingAttr); // Reload $table — in-memory copy still holds the dropped attribute, so checkAttribute would over-count. $table = $this->dbForProject->getDocument($this->databaseCollectionId($database), $table->getId()); @@ -1070,23 +1070,23 @@ class Appwrite extends Destination ); // Spec match → skip work. Create excluded; nothing on dest to match against. if ($action !== SchemaAction::Create && $this->indexSpecMatches($existingIdx, $resource)) { - $action = SchemaAction::Tolerate; + $action = SchemaAction::Skip; } - // Indexes have no in-place primitive — any action other than Tolerate falls through to drop+recreate. + // Indexes have no in-place primitive — any action other than Skip falls through to drop+recreate. $earlyReturn = match ($action) { - SchemaAction::Tolerate => (function () use ($resource, $database, $table): bool { + SchemaAction::Skip => (function () use ($resource, $database, $table): bool { $this->dbForProject->purgeCachedDocument($this->databaseCollectionId($database), $table->getId()); $resource->setStatus(Resource::STATUS_SKIPPED, 'Already exists on destination'); return false; })(), - SchemaAction::UpdateInPlace, SchemaAction::Create => null, + SchemaAction::Overwrite, SchemaAction::Create => null, }; if ($earlyReturn !== null) { return $earlyReturn; } - if ($action === SchemaAction::UpdateInPlace) { + if ($action === SchemaAction::Overwrite) { $dbForDatabases->deleteIndex($this->tableCollectionId($database, $table), $resource->getKey()); $this->dbForProject->deleteDocument(self::META_INDEXES, $indexMetaId); $this->dbForProject->purgeCachedDocument($this->databaseCollectionId($database), $table->getId()); @@ -1545,7 +1545,7 @@ class Appwrite extends Destination return $sourcePerms === $destPerms; } - /** Full-spec equality: short-circuits UpdateInPlace to Tolerate when nothing changed. */ + /** Full-spec equality: short-circuits Overwrite to Skip when nothing changed. */ private function attributeSpecMatches(UtopiaDocument $existing, Column|Attribute $resource, string $type, bool $isRelationship): bool { if ($existing->getAttribute('type') !== $type) { diff --git a/src/Migration/Destinations/OnDuplicate.php b/src/Migration/Destinations/OnDuplicate.php index 3ba945c005..a88ebf8033 100644 --- a/src/Migration/Destinations/OnDuplicate.php +++ b/src/Migration/Destinations/OnDuplicate.php @@ -5,8 +5,8 @@ namespace Utopia\Migration\Destinations; enum SchemaAction { case Create; - case Tolerate; - case UpdateInPlace; + case Skip; + case Overwrite; } enum OnDuplicate: string @@ -25,7 +25,7 @@ enum OnDuplicate: string /** * Coarse routing for re-migration. The caller follows up with a spec-match - * check that overrides UpdateInPlace to Tolerate when source and dest + * check that overrides Overwrite to Skip when source and dest * already have identical spec — see DestinationAppwrite for the full flow. */ public function resolveSchemaAction( @@ -38,10 +38,10 @@ enum OnDuplicate: string } return match ($this) { self::Fail => SchemaAction::Create, - self::Skip => SchemaAction::Tolerate, + self::Skip => SchemaAction::Skip, self::Overwrite => $this->sourceIsNewer($sourceUpdatedAt, $destUpdatedAt) - ? SchemaAction::UpdateInPlace - : SchemaAction::Tolerate, + ? SchemaAction::Overwrite + : SchemaAction::Skip, }; } diff --git a/tests/Migration/Unit/General/OnDuplicateTest.php b/tests/Migration/Unit/General/OnDuplicateTest.php index 0141cb5d33..3b7e4b1163 100644 --- a/tests/Migration/Unit/General/OnDuplicateTest.php +++ b/tests/Migration/Unit/General/OnDuplicateTest.php @@ -10,7 +10,7 @@ use Utopia\Migration\Destinations\SchemaAction; /** * OnDuplicate::resolveSchemaAction is the load-bearing decision point for * re-migration tolerance. The destination then runs a spec-match guard that - * overrides UpdateInPlace to Tolerate when source and dest already have + * overrides Overwrite to Skip when source and dest already have * identical spec — see DestinationAppwrite. These tests lock the * mode × existence × updatedAt matrix. */ @@ -29,20 +29,20 @@ class OnDuplicateTest extends TestCase public function testFailExistsReturnsCreateSoCallerDDLThrows(): void { - // Fail is routed through Create (not Tolerate) so the caller's normal + // Fail is routed through Create (not Skip) so the caller's normal // create flow runs and the library surfaces DuplicateException as - // designed. Returning Tolerate here would silently hide the error. + // designed. Returning Skip here would silently hide the error. $this->assertSame( SchemaAction::Create, OnDuplicate::Fail->resolveSchemaAction(exists: true), ); } - public function testSkipAlwaysToleratesExisting(): void + public function testSkipAlwaysSkipsExisting(): void { // Skip must ignore updatedAt entirely — it's the "don't touch" contract. $this->assertSame( - SchemaAction::Tolerate, + SchemaAction::Skip, OnDuplicate::Skip->resolveSchemaAction( exists: true, sourceUpdatedAt: '2026-01-01T00:00:00.000+00:00', @@ -50,7 +50,7 @@ class OnDuplicateTest extends TestCase ), ); $this->assertSame( - SchemaAction::Tolerate, + SchemaAction::Skip, OnDuplicate::Skip->resolveSchemaAction( exists: true, sourceUpdatedAt: '2020-01-01T00:00:00.000+00:00', @@ -61,12 +61,12 @@ class OnDuplicateTest extends TestCase public function testOverwriteSourceNewerUpdatesInPlace(): void { - // Source updatedAt strictly newer than dest → UpdateInPlace. The + // Source updatedAt strictly newer than dest → Overwrite. The // caller (DestinationAppwrite) follows up with attribute/index spec // checks and falls through to drop+recreate when the SDK can't // express the change. $this->assertSame( - SchemaAction::UpdateInPlace, + SchemaAction::Overwrite, OnDuplicate::Overwrite->resolveSchemaAction( exists: true, sourceUpdatedAt: '2026-04-23T10:00:00.000+00:00', @@ -75,11 +75,11 @@ class OnDuplicateTest extends TestCase ); } - public function testOverwriteSourceEqualTolerates(): void + public function testOverwriteSourceEqualSkips(): void { $when = '2026-04-23T10:00:00.000+00:00'; $this->assertSame( - SchemaAction::Tolerate, + SchemaAction::Skip, OnDuplicate::Overwrite->resolveSchemaAction( exists: true, sourceUpdatedAt: $when, @@ -88,12 +88,12 @@ class OnDuplicateTest extends TestCase ); } - public function testOverwriteSourceOlderTolerates(): void + public function testOverwriteSourceOlderSkips(): void { // Dest is ahead — don't roll back. Avoids overwriting newer // destination edits with stale source data. $this->assertSame( - SchemaAction::Tolerate, + SchemaAction::Skip, OnDuplicate::Overwrite->resolveSchemaAction( exists: true, sourceUpdatedAt: '2026-04-23T09:00:00.000+00:00', @@ -102,12 +102,12 @@ class OnDuplicateTest extends TestCase ); } - public function testOverwriteNoTimestampsTolerates(): void + public function testOverwriteNoTimestampsSkips(): void { // No timestamps provided at all → no information to act on. Conservative: - // Tolerate rather than risk a destructive update on uncertain input. + // Skip rather than risk a destructive update on uncertain input. $this->assertSame( - SchemaAction::Tolerate, + SchemaAction::Skip, OnDuplicate::Overwrite->resolveSchemaAction(exists: true), ); } @@ -132,12 +132,12 @@ class OnDuplicateTest extends TestCase } #[DataProvider('unparseableTimestampPairs')] - public function testOverwriteUnparseableUpdatedAtTolerates(?string $source, ?string $dest): void + public function testOverwriteUnparseableUpdatedAtSkips(?string $source, ?string $dest): void { // Conservative: unparseable updatedAt preserves existing destination // rather than risk a destructive update on garbage input. $this->assertSame( - SchemaAction::Tolerate, + SchemaAction::Skip, OnDuplicate::Overwrite->resolveSchemaAction( exists: true, sourceUpdatedAt: $source, From 39a249231c9e2064969040a96bf5a7d56b91ff9d Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Mon, 4 May 2026 07:51:33 +0100 Subject: [PATCH 62/91] Stop user-data errors leaking to Sentry from migrations Two changes in Destinations/Appwrite.php: 1. Per-resource wrap rethrows non-Migration\Exception throwables. User errors still record on the migration document and the loop continues (existing behaviour). Library bugs and infra failures now bubble to the worker boundary so they can be routed to Sentry instead of being silently absorbed. 2. Row-flush match block catches DuplicateException and StructureException from the database adapter and rethrows them as Migration\Exception so the per-resource wrap above recognises them as user-facing failures. This keeps "Document already exists" / invalid structure messages in the migration report only. --- src/Migration/Destinations/Appwrite.php | 51 +++++++++++++++++++------ 1 file changed, 39 insertions(+), 12 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index 81ee6b2fda..daaad0a135 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -344,6 +344,13 @@ class Appwrite extends Destination previous: $e )); + // User-facing failures (Migration\Exception) are recorded for the migration + // report and the loop continues. Anything else is a library bug or infra + // failure — rethrow so the worker boundary can route it to Sentry. + if (!$e instanceof Exception) { + throw $e; + } + $responseResource = $resource; } finally { $this->dbForProject->setPreserveDates(false); @@ -1074,19 +1081,39 @@ class Appwrite extends Destination } $collectionId = 'database_' . $databaseInternalId . '_collection_' . $tableInternalId; - match ($this->onDuplicate) { - OnDuplicate::Upsert => $dbForDatabases->skipRelationshipsExistCheck( - fn () => $dbForDatabases->upsertDocuments($collectionId, $this->rowBuffer) - ), - OnDuplicate::Skip => $dbForDatabases->skipDuplicates( - fn () => $dbForDatabases->skipRelationshipsExistCheck( + try { + match ($this->onDuplicate) { + OnDuplicate::Upsert => $dbForDatabases->skipRelationshipsExistCheck( + fn () => $dbForDatabases->upsertDocuments($collectionId, $this->rowBuffer) + ), + OnDuplicate::Skip => $dbForDatabases->skipDuplicates( + fn () => $dbForDatabases->skipRelationshipsExistCheck( + fn () => $dbForDatabases->createDocuments($collectionId, $this->rowBuffer) + ) + ), + OnDuplicate::Fail => $dbForDatabases->skipRelationshipsExistCheck( fn () => $dbForDatabases->createDocuments($collectionId, $this->rowBuffer) - ) - ), - OnDuplicate::Fail => $dbForDatabases->skipRelationshipsExistCheck( - fn () => $dbForDatabases->createDocuments($collectionId, $this->rowBuffer) - ), - }; + ), + }; + } catch (DuplicateException $e) { + // Convert to Migration\Exception so the per-resource wrap recognises it + // as a user-facing failure and records it without escalating to Sentry. + throw new Exception( + resourceName: $resource->getName(), + resourceGroup: $resource->getGroup(), + resourceId: $resource->getId(), + message: 'Document already exists', + previous: $e, + ); + } catch (StructureException $e) { + throw new Exception( + resourceName: $resource->getName(), + resourceGroup: $resource->getGroup(), + resourceId: $resource->getId(), + message: $e->getMessage(), + previous: $e, + ); + } } finally { $this->rowBuffer = []; } From 276e7c25077a4dee670a806f715869f11367d932 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Mon, 4 May 2026 08:20:31 +0100 Subject: [PATCH 63/91] Stop user-data errors leaking to Sentry from migrations MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Convert per-resource user-error throws into setStatus + addError + return false in the create*() methods (createDatabase, createEntity, createField, createIndex, createRecord). Failures are recorded for the migration report where they're detected, and the import loop continues to the next resource — matching the existing skip-from-cache pattern at line 1015 and the documents-DB skip at line 535. The per-resource wrap at import() simplifies to a pure safety net: record for the user, then rethrow. By construction, anything reaching it is a library bug or infra failure, which the worker boundary routes to Sentry. Row-flush DuplicateException / StructureException are caught at the flush site and recorded inline — same shape as the rest of the create*() methods. Behaviour preserved: user errors continue to appear in the migration report, the loop continues across resources, the migration ends with status=failed when any resource failed. Only routing to Sentry changed. --- src/Migration/Destinations/Appwrite.php | 147 +++++++++++++++--------- 1 file changed, 93 insertions(+), 54 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index daaad0a135..fab054399c 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -333,6 +333,10 @@ class Appwrite extends Destination default => throw new \Exception('Invalid resource group', Exception::CODE_VALIDATION), }; } catch (\Throwable $e) { + // Safety net: expected user-data failures are recorded inline by the + // create*() methods via setStatus + addError + return false. Anything + // reaching here is a library bug or infra failure — record it for the + // user, then rethrow so the worker boundary can route it to Sentry. $resource->setStatus(Resource::STATUS_ERROR, $e->getMessage()); $this->addError(new Exception( @@ -344,14 +348,7 @@ class Appwrite extends Destination previous: $e )); - // User-facing failures (Migration\Exception) are recorded for the migration - // report and the loop continues. Anything else is a library bug or infra - // failure — rethrow so the worker boundary can route it to Sentry. - if (!$e instanceof Exception) { - throw $e; - } - - $responseResource = $resource; + throw $e; } finally { $this->dbForProject->setPreserveDates(false); } @@ -421,12 +418,14 @@ class Appwrite extends Destination $validator = new UID(); if (!$validator->isValid($resource->getId())) { - throw new Exception( + $resource->setStatus(Resource::STATUS_ERROR, $validator->getDescription()); + $this->addError(new Exception( resourceName: $resource->getName(), resourceGroup: $resource->getGroup(), resourceId: $resource->getId(), message: $validator->getDescription(), - ); + )); + return false; } $createdAt = $this->normalizeDateTime($resource->getCreatedAt()); @@ -481,12 +480,14 @@ class Appwrite extends Destination $validator = new UID(); if (!$validator->isValid($resource->getId())) { - throw new Exception( + $resource->setStatus(Resource::STATUS_ERROR, $validator->getDescription()); + $this->addError(new Exception( resourceName: $resource->getName(), resourceGroup: $resource->getGroup(), resourceId: $resource->getId(), message: $validator->getDescription(), - ); + )); + return false; } $database = $this->dbForProject->getDocument( @@ -495,12 +496,14 @@ class Appwrite extends Destination ); if ($database->isEmpty()) { - throw new Exception( + $resource->setStatus(Resource::STATUS_ERROR, 'Database not found'); + $this->addError(new Exception( resourceName: $resource->getName(), resourceGroup: $resource->getGroup(), resourceId: $resource->getId(), message: 'Database not found', - ); + )); + return false; } $createdAt = $this->normalizeDateTime($resource->getCreatedAt()); @@ -582,12 +585,14 @@ class Appwrite extends Destination ); if ($database->isEmpty()) { - throw new Exception( + $resource->setStatus(Resource::STATUS_ERROR, 'Database not found'); + $this->addError(new Exception( resourceName: $resource->getName(), resourceGroup: $resource->getGroup(), resourceId: $resource->getId(), message: 'Database not found', - ); + )); + return false; } $table = $this->dbForProject->getDocument( @@ -596,41 +601,49 @@ class Appwrite extends Destination ); if ($table->isEmpty()) { - throw new Exception( + $resource->setStatus(Resource::STATUS_ERROR, 'Table not found'); + $this->addError(new Exception( resourceName: $resource->getName(), resourceGroup: $resource->getGroup(), resourceId: $resource->getId(), message: 'Table not found', - ); + )); + return false; } if (!empty($resource->getFormat())) { if (!Structure::hasFormat($resource->getFormat(), $type)) { - throw new Exception( + $resource->setStatus(Resource::STATUS_ERROR, "Format {$resource->getFormat()} not available for column type {$type}"); + $this->addError(new Exception( resourceName: $resource->getName(), resourceGroup: $resource->getGroup(), resourceId: $resource->getId(), message: "Format {$resource->getFormat()} not available for column type {$type}", - ); + )); + return false; } } if ($resource->isRequired() && $resource->getDefault() !== null) { - throw new Exception( + $resource->setStatus(Resource::STATUS_ERROR, 'Cannot set default value for required column'); + $this->addError(new Exception( resourceName: $resource->getName(), resourceGroup: $resource->getGroup(), resourceId: $resource->getId(), message: 'Cannot set default value for required column', - ); + )); + return false; } if ($resource->isArray() && $resource->getDefault() !== null) { - throw new Exception( + $resource->setStatus(Resource::STATUS_ERROR, 'Cannot set default value for array column'); + $this->addError(new Exception( resourceName: $resource->getName(), resourceGroup: $resource->getGroup(), resourceId: $resource->getId(), message: 'Cannot set default value for array column', - ); + )); + return false; } if ($type === UtopiaDatabase::VAR_RELATIONSHIP) { @@ -640,12 +653,14 @@ class Appwrite extends Destination $resource->getOptions()['relatedCollection'] ); if ($relatedTable->isEmpty()) { - throw new Exception( + $resource->setStatus(Resource::STATUS_ERROR, 'Related table not found'); + $this->addError(new Exception( resourceName: $resource->getName(), resourceGroup: $resource->getGroup(), resourceId: $resource->getId(), message: 'Related table not found', - ); + )); + return false; } } @@ -678,20 +693,26 @@ class Appwrite extends Destination $this->dbForProject->checkAttribute($table, $column); $column = $this->dbForProject->createDocument('attributes', $column); - } catch (DuplicateException) { - throw new Exception( + } catch (DuplicateException $e) { + $resource->setStatus(Resource::STATUS_ERROR, 'Attribute already exists'); + $this->addError(new Exception( resourceName: $resource->getName(), resourceGroup: $resource->getGroup(), resourceId: $resource->getId(), message: 'Attribute already exists', - ); - } catch (LimitException) { - throw new Exception( + previous: $e, + )); + return false; + } catch (LimitException $e) { + $resource->setStatus(Resource::STATUS_ERROR, 'Attribute limit exceeded'); + $this->addError(new Exception( resourceName: $resource->getName(), resourceGroup: $resource->getGroup(), resourceId: $resource->getId(), message: 'Attribute limit exceeded', - ); + previous: $e, + )); + return false; } catch (\Throwable $e) { $this->dbForProject->purgeCachedDocument('database_' . $database->getSequence(), $table->getId()); $dbForDatabases->purgeCachedCollection('database_' . $database->getSequence() . '_collection_' . $table->getSequence()); @@ -734,24 +755,30 @@ class Appwrite extends Destination ]); $this->dbForProject->createDocument('attributes', $twoWayAttribute); - } catch (DuplicateException) { + } catch (DuplicateException $e) { $this->dbForProject->deleteDocument('attributes', $column->getId()); - throw new Exception( + $resource->setStatus(Resource::STATUS_ERROR, 'Attribute already exists'); + $this->addError(new Exception( resourceName: $resource->getName(), resourceGroup: $resource->getGroup(), resourceId: $resource->getId(), message: 'Attribute already exists', - ); - } catch (LimitException) { + previous: $e, + )); + return false; + } catch (LimitException $e) { $this->dbForProject->deleteDocument('attributes', $column->getId()); - throw new Exception( + $resource->setStatus(Resource::STATUS_ERROR, 'Column limit exceeded'); + $this->addError(new Exception( resourceName: $resource->getName(), resourceGroup: $resource->getGroup(), resourceId: $resource->getId(), message: 'Column limit exceeded', - ); + previous: $e, + )); + return false; } catch (\Throwable $e) { $this->dbForProject->purgeCachedDocument('database_' . $database->getSequence(), $relatedTable->getId()); $dbForDatabases->purgeCachedCollection('database_' . $database->getSequence() . '_collection_' . $relatedTable->getSequence()); @@ -832,12 +859,14 @@ class Appwrite extends Destination $resource->getTable()->getDatabase()->getId(), ); if ($database->isEmpty()) { - throw new Exception( + $resource->setStatus(Resource::STATUS_ERROR, 'Database not found'); + $this->addError(new Exception( resourceName: $resource->getName(), resourceGroup: $resource->getGroup(), resourceId: $resource->getId(), message: 'Database not found', - ); + )); + return false; } $table = $this->dbForProject->getDocument( @@ -845,12 +874,14 @@ class Appwrite extends Destination $resource->getTable()->getId(), ); if ($table->isEmpty()) { - throw new Exception( + $resource->setStatus(Resource::STATUS_ERROR, 'Table not found'); + $this->addError(new Exception( resourceName: $resource->getName(), resourceGroup: $resource->getGroup(), resourceId: $resource->getId(), message: 'Table not found', - ); + )); + return false; } $dbForDatabases = ($this->getDatabasesDB)($database); @@ -860,12 +891,14 @@ class Appwrite extends Destination ], $dbForDatabases->getLimitForIndexes()); if ($count >= $dbForDatabases->getLimitForIndexes()) { - throw new Exception( + $resource->setStatus(Resource::STATUS_ERROR, 'Index limit reached for table'); + $this->addError(new Exception( resourceName: $resource->getName(), resourceGroup: $resource->getGroup(), resourceId: $resource->getId(), message: 'Index limit reached for table', - ); + )); + return false; } // Lengths hidden by default @@ -922,12 +955,14 @@ class Appwrite extends Destination if (!$validator->isValid($index)) { - throw new Exception( + $resource->setStatus(Resource::STATUS_ERROR, 'Invalid index: ' . $validator->getDescription()); + $this->addError(new Exception( resourceName: $resource->getName(), resourceGroup: $resource->getGroup(), resourceId: $resource->getId(), message: 'Invalid index: ' . $validator->getDescription(), - ); + )); + return false; } $index = $this->dbForProject->createDocument('indexes', $index); @@ -984,12 +1019,14 @@ class Appwrite extends Destination $validator = new UID(); if (!$validator->isValid($resource->getId())) { - throw new Exception( + $resource->setStatus(Resource::STATUS_ERROR, $validator->getDescription()); + $this->addError(new Exception( resourceName: $resource->getName(), resourceGroup: $resource->getGroup(), resourceId: $resource->getId(), message: $validator->getDescription(), - ); + )); + return false; } // Check if document has already been created @@ -1096,23 +1133,25 @@ class Appwrite extends Destination ), }; } catch (DuplicateException $e) { - // Convert to Migration\Exception so the per-resource wrap recognises it - // as a user-facing failure and records it without escalating to Sentry. - throw new Exception( + $resource->setStatus(Resource::STATUS_ERROR, 'Document already exists'); + $this->addError(new Exception( resourceName: $resource->getName(), resourceGroup: $resource->getGroup(), resourceId: $resource->getId(), message: 'Document already exists', previous: $e, - ); + )); + return false; } catch (StructureException $e) { - throw new Exception( + $resource->setStatus(Resource::STATUS_ERROR, $e->getMessage()); + $this->addError(new Exception( resourceName: $resource->getName(), resourceGroup: $resource->getGroup(), resourceId: $resource->getId(), message: $e->getMessage(), previous: $e, - ); + )); + return false; } } finally { $this->rowBuffer = []; From 0710fde3a99f7236f8bbcf2bf5fc860da0378535 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Mon, 4 May 2026 11:03:40 +0100 Subject: [PATCH 64/91] Combine Duplicate/Structure catches at row-flush; trim verbose comments DB adapters already normalise DuplicateException's message to 'Document already exists', so a multi-type catch with $e->getMessage() collapses both branches into one without changing user-visible behaviour. Trimmed the safety-net comment to a single line. --- src/Migration/Destinations/Appwrite.php | 18 +++--------------- 1 file changed, 3 insertions(+), 15 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index fab054399c..67a20a15c7 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -333,10 +333,8 @@ class Appwrite extends Destination default => throw new \Exception('Invalid resource group', Exception::CODE_VALIDATION), }; } catch (\Throwable $e) { - // Safety net: expected user-data failures are recorded inline by the - // create*() methods via setStatus + addError + return false. Anything - // reaching here is a library bug or infra failure — record it for the - // user, then rethrow so the worker boundary can route it to Sentry. + // Safety net for unexpected failures — record on the migration and + // rethrow so the worker boundary can route bugs to Sentry. $resource->setStatus(Resource::STATUS_ERROR, $e->getMessage()); $this->addError(new Exception( @@ -1132,17 +1130,7 @@ class Appwrite extends Destination fn () => $dbForDatabases->createDocuments($collectionId, $this->rowBuffer) ), }; - } catch (DuplicateException $e) { - $resource->setStatus(Resource::STATUS_ERROR, 'Document already exists'); - $this->addError(new Exception( - resourceName: $resource->getName(), - resourceGroup: $resource->getGroup(), - resourceId: $resource->getId(), - message: 'Document already exists', - previous: $e, - )); - return false; - } catch (StructureException $e) { + } catch (DuplicateException | StructureException $e) { $resource->setStatus(Resource::STATUS_ERROR, $e->getMessage()); $this->addError(new Exception( resourceName: $resource->getName(), From 3fdcd279254e41e323d64b95e7efafe5b9bab19f Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Mon, 4 May 2026 11:06:03 +0100 Subject: [PATCH 65/91] Combine Duplicate/Limit catches in createField Same shape as the row-flush combine: multi-type catch with a small ternary for the per-type message. Two pairs collapsed: the single attribute path and the relationship two-way path (which differ only in 'Attribute limit exceeded' vs 'Column limit exceeded'). --- src/Migration/Destinations/Appwrite.php | 36 ++++++------------------- 1 file changed, 8 insertions(+), 28 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index 67a20a15c7..22fc0efe61 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -691,23 +691,14 @@ class Appwrite extends Destination $this->dbForProject->checkAttribute($table, $column); $column = $this->dbForProject->createDocument('attributes', $column); - } catch (DuplicateException $e) { - $resource->setStatus(Resource::STATUS_ERROR, 'Attribute already exists'); + } catch (DuplicateException | LimitException $e) { + $message = $e instanceof DuplicateException ? 'Attribute already exists' : 'Attribute limit exceeded'; + $resource->setStatus(Resource::STATUS_ERROR, $message); $this->addError(new Exception( resourceName: $resource->getName(), resourceGroup: $resource->getGroup(), resourceId: $resource->getId(), - message: 'Attribute already exists', - previous: $e, - )); - return false; - } catch (LimitException $e) { - $resource->setStatus(Resource::STATUS_ERROR, 'Attribute limit exceeded'); - $this->addError(new Exception( - resourceName: $resource->getName(), - resourceGroup: $resource->getGroup(), - resourceId: $resource->getId(), - message: 'Attribute limit exceeded', + message: $message, previous: $e, )); return false; @@ -753,27 +744,16 @@ class Appwrite extends Destination ]); $this->dbForProject->createDocument('attributes', $twoWayAttribute); - } catch (DuplicateException $e) { + } catch (DuplicateException | LimitException $e) { $this->dbForProject->deleteDocument('attributes', $column->getId()); - $resource->setStatus(Resource::STATUS_ERROR, 'Attribute already exists'); + $message = $e instanceof DuplicateException ? 'Attribute already exists' : 'Column limit exceeded'; + $resource->setStatus(Resource::STATUS_ERROR, $message); $this->addError(new Exception( resourceName: $resource->getName(), resourceGroup: $resource->getGroup(), resourceId: $resource->getId(), - message: 'Attribute already exists', - previous: $e, - )); - return false; - } catch (LimitException $e) { - $this->dbForProject->deleteDocument('attributes', $column->getId()); - - $resource->setStatus(Resource::STATUS_ERROR, 'Column limit exceeded'); - $this->addError(new Exception( - resourceName: $resource->getName(), - resourceGroup: $resource->getGroup(), - resourceId: $resource->getId(), - message: 'Column limit exceeded', + message: $message, previous: $e, )); return false; From 7bb1da14e1c320bc32c67f47e7f3b251823200f9 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Mon, 4 May 2026 11:11:24 +0100 Subject: [PATCH 66/91] Revert catch combines; keep typed catches separate --- src/Migration/Destinations/Appwrite.php | 48 ++++++++++++++++++++----- 1 file changed, 39 insertions(+), 9 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index 22fc0efe61..e7e4fc535a 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -691,14 +691,23 @@ class Appwrite extends Destination $this->dbForProject->checkAttribute($table, $column); $column = $this->dbForProject->createDocument('attributes', $column); - } catch (DuplicateException | LimitException $e) { - $message = $e instanceof DuplicateException ? 'Attribute already exists' : 'Attribute limit exceeded'; - $resource->setStatus(Resource::STATUS_ERROR, $message); + } catch (DuplicateException $e) { + $resource->setStatus(Resource::STATUS_ERROR, 'Attribute already exists'); $this->addError(new Exception( resourceName: $resource->getName(), resourceGroup: $resource->getGroup(), resourceId: $resource->getId(), - message: $message, + message: 'Attribute already exists', + previous: $e, + )); + return false; + } catch (LimitException $e) { + $resource->setStatus(Resource::STATUS_ERROR, 'Attribute limit exceeded'); + $this->addError(new Exception( + resourceName: $resource->getName(), + resourceGroup: $resource->getGroup(), + resourceId: $resource->getId(), + message: 'Attribute limit exceeded', previous: $e, )); return false; @@ -744,16 +753,27 @@ class Appwrite extends Destination ]); $this->dbForProject->createDocument('attributes', $twoWayAttribute); - } catch (DuplicateException | LimitException $e) { + } catch (DuplicateException $e) { $this->dbForProject->deleteDocument('attributes', $column->getId()); - $message = $e instanceof DuplicateException ? 'Attribute already exists' : 'Column limit exceeded'; - $resource->setStatus(Resource::STATUS_ERROR, $message); + $resource->setStatus(Resource::STATUS_ERROR, 'Attribute already exists'); $this->addError(new Exception( resourceName: $resource->getName(), resourceGroup: $resource->getGroup(), resourceId: $resource->getId(), - message: $message, + message: 'Attribute already exists', + previous: $e, + )); + return false; + } catch (LimitException $e) { + $this->dbForProject->deleteDocument('attributes', $column->getId()); + + $resource->setStatus(Resource::STATUS_ERROR, 'Column limit exceeded'); + $this->addError(new Exception( + resourceName: $resource->getName(), + resourceGroup: $resource->getGroup(), + resourceId: $resource->getId(), + message: 'Column limit exceeded', previous: $e, )); return false; @@ -1110,7 +1130,17 @@ class Appwrite extends Destination fn () => $dbForDatabases->createDocuments($collectionId, $this->rowBuffer) ), }; - } catch (DuplicateException | StructureException $e) { + } catch (DuplicateException $e) { + $resource->setStatus(Resource::STATUS_ERROR, 'Document already exists'); + $this->addError(new Exception( + resourceName: $resource->getName(), + resourceGroup: $resource->getGroup(), + resourceId: $resource->getId(), + message: 'Document already exists', + previous: $e, + )); + return false; + } catch (StructureException $e) { $resource->setStatus(Resource::STATUS_ERROR, $e->getMessage()); $this->addError(new Exception( resourceName: $resource->getName(), From def0ad8ad8ee6efd0b9324668c0c416a57af6987 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Tue, 5 May 2026 19:23:09 +0530 Subject: [PATCH 67/91] updated --- src/Migration/Sources/Appwrite.php | 1 + 1 file changed, 1 insertion(+) diff --git a/src/Migration/Sources/Appwrite.php b/src/Migration/Sources/Appwrite.php index 2c0b8db134..48dc03d949 100644 --- a/src/Migration/Sources/Appwrite.php +++ b/src/Migration/Sources/Appwrite.php @@ -2393,6 +2393,7 @@ class Appwrite extends Source array: $column['array'], min: $column['min'] ?? null, max: $column['max'] ?? null, + signed: $column['signed'] ?? true, createdAt: $column['$createdAt'] ?? '', updatedAt: $column['$updatedAt'] ?? '', ), From e060244b01d296f97668f2705627ca38ce3b61f7 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Tue, 5 May 2026 15:46:26 +0100 Subject: [PATCH 68/91] Stop createField/createIndex cleanup catches from silencing bugs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The catch (\Throwable) cleanup blocks in createField and createIndex were rewrapping any thrown exception as a Migration\Exception with a generic 'Failed to create column/index' message. With the worker's instanceof MigrationException gate, this silenced real library bugs (TypeError, RuntimeException, PDOException) from Sentry — the exact opposite of what the surrounding PR aims to do. Rethrow the original cause instead, so the safety net at import() records the real message for the user and the worker boundary routes non-MigrationException throwables to Sentry with full trace. --- src/Migration/Destinations/Appwrite.php | 16 +++------------- 1 file changed, 3 insertions(+), 13 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index e7e4fc535a..846669cb86 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -821,19 +821,14 @@ class Appwrite extends Destination throw new \Exception('Failed to create Column', Exception::CODE_INTERNAL); } } - } catch (\Throwable) { + } catch (\Throwable $e) { $this->dbForProject->deleteDocument('attributes', $column->getId()); if (isset($twoWayAttribute)) { $this->dbForProject->deleteDocument('attributes', $twoWayAttribute->getId()); } - throw new Exception( - resourceName: $resource->getName(), - resourceGroup: $resource->getGroup(), - resourceId: $resource->getId(), - message: 'Failed to create column', - ); + throw $e; } if ($type === UtopiaDatabase::VAR_RELATIONSHIP && $options['twoWay']) { @@ -986,12 +981,7 @@ class Appwrite extends Destination } catch (\Throwable $th) { $this->dbForProject->deleteDocument('indexes', $index->getId()); - throw new Exception( - resourceName: $resource->getName(), - resourceGroup: $resource->getGroup(), - resourceId: $resource->getId(), - message: 'Failed to create index', - ); + throw $th; } $this->dbForProject->purgeCachedDocument( From da8205e8f3e927b2b860dddc2efca0e408171116 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Tue, 5 May 2026 16:50:58 +0100 Subject: [PATCH 69/91] Revert per-resource wrap rethrow; record and continue MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The earlier 'throw $e' aborted the batch on the first failure, leaving items #6-N at STATUS_PENDING and skipping the rest of the source's fetch loop. Restore the original 'absorb-and-continue' shape so every resource in the batch is attempted and recorded — failures all land in the migration report and the user retries the run cleanly. Trade-off: library bugs (TypeError, etc.) caught here are absorbed and don't reach Sentry. Acceptable — the deterministic-bug case fails the same way for every resource, so absorbing produces a uniform 'all errored' report instead of '1 errored + N pending'. User errors are still kept out of Sentry by the worker's instanceof MigrationException gate, which is the primary goal of this PR. --- src/Migration/Destinations/Appwrite.php | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index fd7a7c7095..38673cbbd1 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -400,8 +400,6 @@ class Appwrite extends Destination default => throw new \Exception('Invalid resource group', Exception::CODE_VALIDATION), }; } catch (\Throwable $e) { - // Safety net for unexpected failures — record on the migration and - // rethrow so the worker boundary can route bugs to Sentry. $resource->setStatus(Resource::STATUS_ERROR, $e->getMessage()); $this->addError(new Exception( @@ -413,7 +411,7 @@ class Appwrite extends Destination previous: $e )); - throw $e; + $responseResource = $resource; } finally { $this->dbForProject->setPreserveDates(false); } From 664228335ed95e89e8a9ae139993561947ad4fe4 Mon Sep 17 00:00:00 2001 From: Jake Barnby Date: Wed, 6 May 2026 13:09:34 +1200 Subject: [PATCH 70/91] (chore): update version --- composer.json | 2 +- composer.lock | 103 ++++++++---------- .../AppwriteAttributeSdkBoundaryTest.php | 2 +- tests/Migration/Unit/General/CacheTest.php | 2 +- .../Unit/General/OnDuplicateTest.php | 2 +- 5 files changed, 52 insertions(+), 59 deletions(-) diff --git a/composer.json b/composer.json index 7cb93cdb33..a52b23a9b6 100644 --- a/composer.json +++ b/composer.json @@ -26,7 +26,7 @@ "ext-curl": "*", "ext-openssl": "*", "appwrite/appwrite": "19.*", - "utopia-php/database": "dev-big-init as 5.77", + "utopia-php/database": "5.*", "utopia-php/storage": "2.*", "utopia-php/dsn": "0.2.*", "halaxa/json-machine": "^1.2" diff --git a/composer.lock b/composer.lock index 5a9224b0e1..1588249162 100644 --- a/composer.lock +++ b/composer.lock @@ -4,7 +4,7 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "ae396ad0e75429f13de6f2891f3cfae3", + "content-hash": "38981f8df096cfbc9dd34487643b7ed6", "packages": [ { "name": "appwrite/appwrite", @@ -1487,16 +1487,16 @@ }, { "name": "symfony/http-client", - "version": "v7.4.8", + "version": "v7.4.9", "source": { "type": "git", "url": "https://github.com/symfony/http-client.git", - "reference": "01933e626c3de76bea1e22641e205e78f6a34342" + "reference": "7e941c6abf4e3bf7dca160bf0e11ef36a9f832f6" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/symfony/http-client/zipball/01933e626c3de76bea1e22641e205e78f6a34342", - "reference": "01933e626c3de76bea1e22641e205e78f6a34342", + "url": "https://api.github.com/repos/symfony/http-client/zipball/7e941c6abf4e3bf7dca160bf0e11ef36a9f832f6", + "reference": "7e941c6abf4e3bf7dca160bf0e11ef36a9f832f6", "shasum": "" }, "require": { @@ -1564,7 +1564,7 @@ "http" ], "support": { - "source": "https://github.com/symfony/http-client/tree/v7.4.8" + "source": "https://github.com/symfony/http-client/tree/v7.4.9" }, "funding": [ { @@ -1584,7 +1584,7 @@ "type": "tidelift" } ], - "time": "2026-03-30T12:55:43+00:00" + "time": "2026-04-29T13:25:15+00:00" }, { "name": "symfony/http-client-contracts", @@ -2230,16 +2230,16 @@ }, { "name": "utopia-php/database", - "version": "dev-big-init", + "version": "5.7.0", "source": { "type": "git", "url": "https://github.com/utopia-php/database.git", - "reference": "ee8895a3ae835978fa4eb143619e4950e7001648" + "reference": "eb35e68f7f90932d5a60bd72e70158ae7a4e0511" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/database/zipball/ee8895a3ae835978fa4eb143619e4950e7001648", - "reference": "ee8895a3ae835978fa4eb143619e4950e7001648", + "url": "https://api.github.com/repos/utopia-php/database/zipball/eb35e68f7f90932d5a60bd72e70158ae7a4e0511", + "reference": "eb35e68f7f90932d5a60bd72e70158ae7a4e0511", "shasum": "" }, "require": { @@ -2284,9 +2284,9 @@ ], "support": { "issues": "https://github.com/utopia-php/database/issues", - "source": "https://github.com/utopia-php/database/tree/big-init" + "source": "https://github.com/utopia-php/database/tree/5.7.0" }, - "time": "2026-05-05T13:27:52+00:00" + "time": "2026-05-06T01:04:08+00:00" }, { "name": "utopia-php/dsn", @@ -2451,16 +2451,16 @@ }, { "name": "utopia-php/storage", - "version": "2.0.0", + "version": "2.0.2", "source": { "type": "git", "url": "https://github.com/utopia-php/storage.git", - "reference": "52d1f89a47165ef0d3deff63043cda182175adfb" + "reference": "64e132a3768e22243eda36fe4262da22fd204f3c" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/storage/zipball/52d1f89a47165ef0d3deff63043cda182175adfb", - "reference": "52d1f89a47165ef0d3deff63043cda182175adfb", + "url": "https://api.github.com/repos/utopia-php/storage/zipball/64e132a3768e22243eda36fe4262da22fd204f3c", + "reference": "64e132a3768e22243eda36fe4262da22fd204f3c", "shasum": "" }, "require": { @@ -2497,22 +2497,22 @@ ], "support": { "issues": "https://github.com/utopia-php/storage/issues", - "source": "https://github.com/utopia-php/storage/tree/2.0.0" + "source": "https://github.com/utopia-php/storage/tree/2.0.2" }, - "time": "2026-04-27T11:39:32+00:00" + "time": "2026-05-01T15:06:16+00:00" }, { "name": "utopia-php/system", - "version": "0.10.1", + "version": "0.10.2", "source": { "type": "git", "url": "https://github.com/utopia-php/system.git", - "reference": "7c1669533bb9c285de19191270c8c1439161a78a" + "reference": "04229a822b147c1abaf1a92fb42c2d7aad4625df" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/system/zipball/7c1669533bb9c285de19191270c8c1439161a78a", - "reference": "7c1669533bb9c285de19191270c8c1439161a78a", + "url": "https://api.github.com/repos/utopia-php/system/zipball/04229a822b147c1abaf1a92fb42c2d7aad4625df", + "reference": "04229a822b147c1abaf1a92fb42c2d7aad4625df", "shasum": "" }, "require": { @@ -2553,9 +2553,9 @@ ], "support": { "issues": "https://github.com/utopia-php/system/issues", - "source": "https://github.com/utopia-php/system/tree/0.10.1" + "source": "https://github.com/utopia-php/system/tree/0.10.2" }, - "time": "2026-03-15T21:07:41+00:00" + "time": "2026-05-05T14:33:41+00:00" }, { "name": "utopia-php/telemetry", @@ -2614,16 +2614,16 @@ }, { "name": "utopia-php/validators", - "version": "0.2.0", + "version": "0.2.2", "source": { "type": "git", "url": "https://github.com/utopia-php/validators.git", - "reference": "30b6030a5b100fc1dff34506e5053759594b2a20" + "reference": "5d7d494e64457cd4eb67fdcfd9481f2c89796aa6" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/validators/zipball/30b6030a5b100fc1dff34506e5053759594b2a20", - "reference": "30b6030a5b100fc1dff34506e5053759594b2a20", + "url": "https://api.github.com/repos/utopia-php/validators/zipball/5d7d494e64457cd4eb67fdcfd9481f2c89796aa6", + "reference": "5d7d494e64457cd4eb67fdcfd9481f2c89796aa6", "shasum": "" }, "require": { @@ -2653,9 +2653,9 @@ ], "support": { "issues": "https://github.com/utopia-php/validators/issues", - "source": "https://github.com/utopia-php/validators/tree/0.2.0" + "source": "https://github.com/utopia-php/validators/tree/0.2.2" }, - "time": "2026-01-13T09:16:51+00:00" + "time": "2026-04-27T16:30:24+00:00" } ], "packages-dev": [ @@ -2723,16 +2723,16 @@ }, { "name": "laravel/pint", - "version": "v1.2.1", + "version": "v1.29.1", "source": { "type": "git", "url": "https://github.com/laravel/pint.git", - "reference": "e60e2112ee779ce60f253695b273d1646a17d6f1" + "reference": "0770e9b7fafd50d4586881d456d6eb41c9247a80" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/laravel/pint/zipball/e60e2112ee779ce60f253695b273d1646a17d6f1", - "reference": "e60e2112ee779ce60f253695b273d1646a17d6f1", + "url": "https://api.github.com/repos/laravel/pint/zipball/0770e9b7fafd50d4586881d456d6eb41c9247a80", + "reference": "0770e9b7fafd50d4586881d456d6eb41c9247a80", "shasum": "" }, "require": { @@ -2740,16 +2740,17 @@ "ext-mbstring": "*", "ext-tokenizer": "*", "ext-xml": "*", - "php": "^8.0" + "php": "^8.2.0" }, "require-dev": { - "friendsofphp/php-cs-fixer": "^3.11.0", - "illuminate/view": "^9.32.0", - "laravel-zero/framework": "^9.2.0", - "mockery/mockery": "^1.5.1", - "nunomaduro/larastan": "^2.2.0", - "nunomaduro/termwind": "^1.14.0", - "pestphp/pest": "^1.22.1" + "friendsofphp/php-cs-fixer": "^3.95.1", + "illuminate/view": "^12.56.0", + "larastan/larastan": "^3.9.6", + "laravel-zero/framework": "^12.1.0", + "mockery/mockery": "^1.6.12", + "nunomaduro/termwind": "^2.4.0", + "pestphp/pest": "^3.8.6", + "shipfastlabs/agent-detector": "^1.1.3" }, "bin": [ "builds/pint" @@ -2775,6 +2776,7 @@ "description": "An opinionated code formatter for PHP.", "homepage": "https://laravel.com", "keywords": [ + "dev", "format", "formatter", "lint", @@ -2785,7 +2787,7 @@ "issues": "https://github.com/laravel/pint/issues", "source": "https://github.com/laravel/pint" }, - "time": "2022-11-29T16:25:20+00:00" + "time": "2026-04-20T15:26:14+00:00" }, { "name": "myclabs/deep-copy", @@ -4948,18 +4950,9 @@ "time": "2025-12-27T19:49:13+00:00" } ], - "aliases": [ - { - "package": "utopia-php/database", - "version": "dev-big-init", - "alias": "5.77", - "alias_normalized": "5.77.0.0" - } - ], + "aliases": [], "minimum-stability": "stable", - "stability-flags": { - "utopia-php/database": 20 - }, + "stability-flags": {}, "prefer-stable": false, "prefer-lowest": false, "platform": { diff --git a/tests/Migration/Unit/Destinations/AppwriteAttributeSdkBoundaryTest.php b/tests/Migration/Unit/Destinations/AppwriteAttributeSdkBoundaryTest.php index a079ea61fb..2e5c182a5c 100644 --- a/tests/Migration/Unit/Destinations/AppwriteAttributeSdkBoundaryTest.php +++ b/tests/Migration/Unit/Destinations/AppwriteAttributeSdkBoundaryTest.php @@ -1,6 +1,6 @@ Date: Wed, 6 May 2026 13:42:14 +0100 Subject: [PATCH 71/91] Fix message: 'Column' -> 'Attribute' limit exceeded to match main --- src/Migration/Destinations/Appwrite.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index 38673cbbd1..d8b1fef9ec 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -966,12 +966,12 @@ class Appwrite extends Destination } catch (LimitException $e) { $this->dbForProject->deleteDocument(self::META_ATTRIBUTES, $column->getId()); - $resource->setStatus(Resource::STATUS_ERROR, 'Column limit exceeded'); + $resource->setStatus(Resource::STATUS_ERROR, 'Attribute limit exceeded'); $this->addError(new Exception( resourceName: $resource->getName(), resourceGroup: $resource->getGroup(), resourceId: $resource->getId(), - message: 'Column limit exceeded', + message: 'Attribute limit exceeded', previous: $e, )); return false; From ff3b4445e7935b3468ef63cdff0ae4f115378bb0 Mon Sep 17 00:00:00 2001 From: Jake Barnby Date: Fri, 8 May 2026 14:12:08 +1200 Subject: [PATCH 72/91] fix(destination): stop propagating source DSN to destination database documents MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Restore an opt-in resolver for `_databases.database` on the Appwrite destination so cross-instance migrations don't write the source's DSN into the destination project's metadata. Without a resolver, the field is left blank and the runtime falls back to the destination project's DSN — correct for legacy single-DSN projects. Why: PR #151 removed the `getDatabaseDSN` callable on the assumption it was unused, and replaced it with `\$resource->getDatabase()` (the source DSN). On Cloud this routed destination reads to the source's host with the destination's project sequence as the namespace, producing `Table 'appwrite.___metadata' doesn't exist` for every migrated database. Multi-type setups (documentsdb / vectorsdb) were silently broken the same way. Refs PR #151. --- src/Migration/Destinations/Appwrite.php | 34 ++++++- .../AppwriteDestinationDsnTest.php | 95 +++++++++++++++++++ 2 files changed, 126 insertions(+), 3 deletions(-) create mode 100644 tests/Migration/Unit/Destinations/AppwriteDestinationDsnTest.php diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index c47b9cdc22..fa464e1104 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -103,6 +103,17 @@ 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. + * + * @var (callable(Database $resource): string)|null + */ + protected $getDatabaseDSN; + /** * @var array */ @@ -139,6 +150,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. */ public function __construct( string $project, @@ -148,6 +160,7 @@ class Appwrite extends Destination callable $getDatabasesDB, protected array $collectionStructure, protected OnDuplicate $onDuplicate = OnDuplicate::Fail, + ?callable $getDatabaseDSN = null, ) { $this->project = $project; $this->endpoint = $endpoint; @@ -166,6 +179,21 @@ class Appwrite extends Destination $this->users = new Users($this->client); $this->getDatabasesDB = $getDatabasesDB; + $this->getDatabaseDSN = $getDatabaseDSN; + } + + /** + * 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). + */ + private function resolveDestinationDsn(Database $resource): string + { + if ($this->getDatabaseDSN === null) { + return ''; + } + return ($this->getDatabaseDSN)($resource); } /** Orphan cleanup runs only after a successful migration — a mid-run throw preserves the destination as-is. */ @@ -519,7 +547,7 @@ class Appwrite extends Destination 'enabled' => $resource->getEnabled(), 'type' => empty($resource->getType()) ? 'legacy' : $resource->getType(), 'originalId' => empty($resource->getOriginalId()) ? null : $resource->getOriginalId(), - 'database' => $resource->getDatabase(), + 'database' => $this->resolveDestinationDsn($resource), '$updatedAt' => $updatedAt, ])); $resource->setSequence($existing->getSequence()); @@ -541,8 +569,8 @@ 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 location - 'database' => $resource->getDatabase() + // Source and destination can be in different locations; never write the source DSN here. + 'database' => $this->resolveDestinationDsn($resource), ])); $resource->setSequence($database->getSequence()); diff --git a/tests/Migration/Unit/Destinations/AppwriteDestinationDsnTest.php b/tests/Migration/Unit/Destinations/AppwriteDestinationDsnTest.php new file mode 100644 index 0000000000..892868db96 --- /dev/null +++ b/tests/Migration/Unit/Destinations/AppwriteDestinationDsnTest.php @@ -0,0 +1,95 @@ +__metadata' doesn't exist`. + */ +class AppwriteDestinationDsnTest extends TestCase +{ + public function testWithoutResolverReturnsEmptyString(): void + { + $destination = $this->makeDestination(getDatabaseDSN: null); + $resource = $this->makeResource(sourceDsn: 'database_db_fra1_self_hosted_11_0'); + + $resolved = $this->invokeResolver($destination, $resource); + + $this->assertSame('', $resolved, 'Without a resolver the destination must not propagate the source DSN.'); + } + + public function testWithResolverUsesItsReturnValue(): void + { + $expected = 'appwrite://database_db_fra1_self_hosted_17_0?database=appwrite&namespace=_1'; + $destination = $this->makeDestination( + getDatabaseDSN: fn (DatabaseResource $r): string => $expected, + ); + $resource = $this->makeResource(sourceDsn: 'database_db_fra1_self_hosted_11_0'); + + $resolved = $this->invokeResolver($destination, $resource); + + $this->assertSame($expected, $resolved); + $this->assertNotSame($resource->getDatabase(), $resolved, 'Source DSN must not leak through the resolver path.'); + } + + public function testResolverReceivesTheResource(): void + { + $captured = null; + $destination = $this->makeDestination( + getDatabaseDSN: function (DatabaseResource $r) use (&$captured): string { + $captured = $r; + return 'resolved'; + }, + ); + $resource = $this->makeResource(sourceDsn: 'src'); + + $this->invokeResolver($destination, $resource); + + $this->assertSame($resource, $captured); + } + + private function makeDestination(?callable $getDatabaseDSN): AppwriteDestination + { + return new AppwriteDestination( + project: 'destination-project', + endpoint: 'http://example.test/v1', + key: 'test-key', + dbForProject: $this->createStub(UtopiaDatabase::class), + getDatabasesDB: fn (): UtopiaDatabase => $this->createStub(UtopiaDatabase::class), + collectionStructure: ['attributes' => [], 'indexes' => []], + onDuplicate: OnDuplicate::Fail, + getDatabaseDSN: $getDatabaseDSN, + ); + } + + private function makeResource(string $sourceDsn): DatabaseResource + { + return new DatabaseResource( + id: 'src-database', + name: 'src', + type: 'legacy', + database: $sourceDsn, + ); + } + + private function invokeResolver(AppwriteDestination $destination, DatabaseResource $resource): string + { + $method = (new ReflectionClass(AppwriteDestination::class))->getMethod('resolveDestinationDsn'); + /** @var string $value */ + $value = $method->invoke($destination, $resource); + return $value; + } +} From 8a0ebdbed72466a362de2580d06742cea6daff3a Mon Sep 17 00:00:00 2001 From: Jake Barnby Date: Fri, 8 May 2026 17:39:28 +1200 Subject: [PATCH 73/91] =?UTF-8?q?docs:=20clarify=20resolver=20scope=20?= =?UTF-8?q?=E2=80=94=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), ])); From 2eefb590346ce4d1667cf979a8345f516cd3af6e Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 8 May 2026 06:04:53 +0000 Subject: [PATCH 74/91] fix(test): add UtopiaDocument parameter to getDatabasesDB closure signature Agent-Logs-Url: https://github.com/utopia-php/migration/sessions/d317b600-9533-45b9-b24b-59eb2df45014 Co-authored-by: abnegate <5857008+abnegate@users.noreply.github.com> --- .../Migration/Unit/Destinations/AppwriteDestinationDsnTest.php | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/tests/Migration/Unit/Destinations/AppwriteDestinationDsnTest.php b/tests/Migration/Unit/Destinations/AppwriteDestinationDsnTest.php index 892868db96..e6e9e4d8f9 100644 --- a/tests/Migration/Unit/Destinations/AppwriteDestinationDsnTest.php +++ b/tests/Migration/Unit/Destinations/AppwriteDestinationDsnTest.php @@ -5,6 +5,7 @@ namespace Utopia\Tests\Unit\Destinations; use PHPUnit\Framework\TestCase; use ReflectionClass; use Utopia\Database\Database as UtopiaDatabase; +use Utopia\Database\Document as UtopiaDocument; use Utopia\Migration\Destinations\Appwrite as AppwriteDestination; use Utopia\Migration\Destinations\OnDuplicate; use Utopia\Migration\Resources\Database\Database as DatabaseResource; @@ -68,7 +69,7 @@ class AppwriteDestinationDsnTest extends TestCase endpoint: 'http://example.test/v1', key: 'test-key', dbForProject: $this->createStub(UtopiaDatabase::class), - getDatabasesDB: fn (): UtopiaDatabase => $this->createStub(UtopiaDatabase::class), + getDatabasesDB: fn (UtopiaDocument $database): UtopiaDatabase => $this->createStub(UtopiaDatabase::class), collectionStructure: ['attributes' => [], 'indexes' => []], onDuplicate: OnDuplicate::Fail, getDatabaseDSN: $getDatabaseDSN, From 9c9df8f1eb12c3fb1fa98f4749005190ccd279b5 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 8 May 2026 06:07:13 +0000 Subject: [PATCH 75/91] fix(destination): use resolveDestinationDsn in databaseSpecMatches instead of source DSN Agent-Logs-Url: https://github.com/utopia-php/migration/sessions/f7af1371-ec8c-49fd-bb9e-932ae59e7d6e Co-authored-by: abnegate <5857008+abnegate@users.noreply.github.com> --- src/Migration/Destinations/Appwrite.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index a34e164b26..312f7e3fd3 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -1610,7 +1610,7 @@ class Appwrite extends Destination && $existing->getAttribute('enabled') === $resource->getEnabled() && $existing->getAttribute('type') === $sourceType && $existing->getAttribute('originalId') === $sourceOriginalId - && $existing->getAttribute('database') === $resource->getDatabase(); + && $existing->getAttribute('database') === $this->resolveDestinationDsn($resource); } private function tableSpecMatches(UtopiaDocument $existing, Table $resource): bool From 0305666acabcd4b384033e4315517e7bf2254552 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Fri, 8 May 2026 08:25:33 +0100 Subject: [PATCH 76/91] feat: bump appwrite/appwrite to 23.* (Backups service, breaking changes) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds typed Backups SDK service support (cloud uses this). Fixes PHPStan errors against SDK 23: - Replace removed Runtime::DENO121/124/135 (kept ::DENO140 onward) - Functions::create / Sites::create: specification → buildSpecification + runtimeSpecification (SDK 21 split) - importPasswordUser return type: array → \Appwrite\Models\User|null - API::getRow: call ->toArray() since SDK 22+ returns typed Row NOTE: many other call sites in Sources/Destinations still use array offset access on typed responses. Those paths will break at runtime under SDK 23. This commit is the minimum to ship typed-Backups support in cloud; a follow-up refactor will convert all array-offset access to property access. --- composer.json | 2 +- composer.lock | 70 +++++++++++-------- src/Migration/Destinations/Appwrite.php | 16 ++--- src/Migration/Sources/Appwrite/Reader/API.php | 2 +- 4 files changed, 47 insertions(+), 43 deletions(-) diff --git a/composer.json b/composer.json index a52b23a9b6..8649e3befd 100644 --- a/composer.json +++ b/composer.json @@ -25,7 +25,7 @@ "php": ">=8.1", "ext-curl": "*", "ext-openssl": "*", - "appwrite/appwrite": "19.*", + "appwrite/appwrite": "23.*", "utopia-php/database": "5.*", "utopia-php/storage": "2.*", "utopia-php/dsn": "0.2.*", diff --git a/composer.lock b/composer.lock index 1588249162..c32afe7088 100644 --- a/composer.lock +++ b/composer.lock @@ -4,29 +4,29 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "38981f8df096cfbc9dd34487643b7ed6", + "content-hash": "577cd7fb43f3f832869661126e0a5090", "packages": [ { "name": "appwrite/appwrite", - "version": "19.1.0", + "version": "23.0.0", "source": { "type": "git", "url": "https://github.com/appwrite/sdk-for-php.git", - "reference": "8738e812062f899c85b2598eef43d6a247f08a56" + "reference": "d22b36167931294bec4259f0803aba14537030ec" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/appwrite/sdk-for-php/zipball/8738e812062f899c85b2598eef43d6a247f08a56", - "reference": "8738e812062f899c85b2598eef43d6a247f08a56", + "url": "https://api.github.com/repos/appwrite/sdk-for-php/zipball/d22b36167931294bec4259f0803aba14537030ec", + "reference": "d22b36167931294bec4259f0803aba14537030ec", "shasum": "" }, "require": { "ext-curl": "*", "ext-json": "*", - "php": ">=7.1.0" + "php": ">=8.2.0" }, "require-dev": { - "mockery/mockery": "^1.6.12", + "mockery/mockery": "1.6.12", "phpunit/phpunit": "^10" }, "type": "library", @@ -39,14 +39,14 @@ "license": [ "BSD-3-Clause" ], - "description": "Appwrite is an open-source self-hosted backend server that abstract and simplify complex and repetitive development tasks behind a very simple REST API", + "description": "Appwrite is an open-source self-hosted backend server that abstracts and simplifies complex and repetitive development tasks behind a very simple REST API", "support": { "email": "team@appwrite.io", "issues": "https://github.com/appwrite/sdk-for-php/issues", - "source": "https://github.com/appwrite/sdk-for-php/tree/19.1.0", + "source": "https://github.com/appwrite/sdk-for-php/tree/23.0.0", "url": "https://appwrite.io/support" }, - "time": "2025-12-18T08:07:43+00:00" + "time": "2026-04-16T12:38:44+00:00" }, { "name": "brick/math", @@ -1420,16 +1420,16 @@ }, { "name": "symfony/deprecation-contracts", - "version": "v3.6.0", + "version": "v3.7.0", "source": { "type": "git", "url": "https://github.com/symfony/deprecation-contracts.git", - "reference": "63afe740e99a13ba87ec199bb07bbdee937a5b62" + "reference": "50f59d1f3ca46d41ac911f97a78626b6756af35b" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/symfony/deprecation-contracts/zipball/63afe740e99a13ba87ec199bb07bbdee937a5b62", - "reference": "63afe740e99a13ba87ec199bb07bbdee937a5b62", + "url": "https://api.github.com/repos/symfony/deprecation-contracts/zipball/50f59d1f3ca46d41ac911f97a78626b6756af35b", + "reference": "50f59d1f3ca46d41ac911f97a78626b6756af35b", "shasum": "" }, "require": { @@ -1442,7 +1442,7 @@ "name": "symfony/contracts" }, "branch-alias": { - "dev-main": "3.6-dev" + "dev-main": "3.7-dev" } }, "autoload": { @@ -1467,7 +1467,7 @@ "description": "A generic function and convention to trigger deprecation notices", "homepage": "https://symfony.com", "support": { - "source": "https://github.com/symfony/deprecation-contracts/tree/v3.6.0" + "source": "https://github.com/symfony/deprecation-contracts/tree/v3.7.0" }, "funding": [ { @@ -1478,12 +1478,16 @@ "url": "https://github.com/fabpot", "type": "github" }, + { + "url": "https://github.com/nicolas-grekas", + "type": "github" + }, { "url": "https://tidelift.com/funding/github/packagist/symfony/symfony", "type": "tidelift" } ], - "time": "2024-09-25T14:21:43+00:00" + "time": "2026-04-13T15:52:40+00:00" }, { "name": "symfony/http-client", @@ -1588,16 +1592,16 @@ }, { "name": "symfony/http-client-contracts", - "version": "v3.6.0", + "version": "v3.7.0", "source": { "type": "git", "url": "https://github.com/symfony/http-client-contracts.git", - "reference": "75d7043853a42837e68111812f4d964b01e5101c" + "reference": "4a2d00c37651c0bdc2b9e1c773487a8bf4edb12d" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/symfony/http-client-contracts/zipball/75d7043853a42837e68111812f4d964b01e5101c", - "reference": "75d7043853a42837e68111812f4d964b01e5101c", + "url": "https://api.github.com/repos/symfony/http-client-contracts/zipball/4a2d00c37651c0bdc2b9e1c773487a8bf4edb12d", + "reference": "4a2d00c37651c0bdc2b9e1c773487a8bf4edb12d", "shasum": "" }, "require": { @@ -1610,7 +1614,7 @@ "name": "symfony/contracts" }, "branch-alias": { - "dev-main": "3.6-dev" + "dev-main": "3.7-dev" } }, "autoload": { @@ -1646,7 +1650,7 @@ "standards" ], "support": { - "source": "https://github.com/symfony/http-client-contracts/tree/v3.6.0" + "source": "https://github.com/symfony/http-client-contracts/tree/v3.7.0" }, "funding": [ { @@ -1657,12 +1661,16 @@ "url": "https://github.com/fabpot", "type": "github" }, + { + "url": "https://github.com/nicolas-grekas", + "type": "github" + }, { "url": "https://tidelift.com/funding/github/packagist/symfony/symfony", "type": "tidelift" } ], - "time": "2025-04-29T11:18:49+00:00" + "time": "2026-03-06T13:17:50+00:00" }, { "name": "symfony/polyfill-mbstring", @@ -1991,16 +1999,16 @@ }, { "name": "symfony/service-contracts", - "version": "v3.6.1", + "version": "v3.7.0", "source": { "type": "git", "url": "https://github.com/symfony/service-contracts.git", - "reference": "45112560a3ba2d715666a509a0bc9521d10b6c43" + "reference": "d25d82433a80eba6aa0e6c24b61d7370d99e444a" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/symfony/service-contracts/zipball/45112560a3ba2d715666a509a0bc9521d10b6c43", - "reference": "45112560a3ba2d715666a509a0bc9521d10b6c43", + "url": "https://api.github.com/repos/symfony/service-contracts/zipball/d25d82433a80eba6aa0e6c24b61d7370d99e444a", + "reference": "d25d82433a80eba6aa0e6c24b61d7370d99e444a", "shasum": "" }, "require": { @@ -2018,7 +2026,7 @@ "name": "symfony/contracts" }, "branch-alias": { - "dev-main": "3.6-dev" + "dev-main": "3.7-dev" } }, "autoload": { @@ -2054,7 +2062,7 @@ "standards" ], "support": { - "source": "https://github.com/symfony/service-contracts/tree/v3.6.1" + "source": "https://github.com/symfony/service-contracts/tree/v3.7.0" }, "funding": [ { @@ -2074,7 +2082,7 @@ "type": "tidelift" } ], - "time": "2025-07-15T11:30:57+00:00" + "time": "2026-03-28T09:44:51+00:00" }, { "name": "tbachert/spi", diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index 312f7e3fd3..c4271c6663 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -2151,11 +2151,11 @@ class Appwrite extends Destination /** * @param User $user - * @return array|null + * @return \Appwrite\Models\User|null * @throws AppwriteException * @throws \Exception */ - public function importPasswordUser(User $user): ?array + public function importPasswordUser(User $user): ?\Appwrite\Models\User { $hash = $user->getPasswordHash(); $result = null; @@ -2277,9 +2277,6 @@ class Appwrite extends Destination 'dart-2.17' => Runtime::DART217(), 'dart-2.18' => Runtime::DART218(), 'dart-2.19' => Runtime::DART219(), - 'deno-1.21' => Runtime::DENO121(), - 'deno-1.24' => Runtime::DENO124(), - 'deno-1.35' => Runtime::DENO135(), 'deno-1.40' => Runtime::DENO140(), 'deno-1.46' => Runtime::DENO146(), 'deno-2.0' => Runtime::DENO20(), @@ -2322,7 +2319,8 @@ class Appwrite extends Destination $resource->getEntrypoint(), $resource->getCommands(), $resource->getScopes(), - specification: $resource->getSpecification() ?: null, + buildSpecification: $resource->getSpecification() ?: null, + runtimeSpecification: $resource->getSpecification() ?: null, ); break; case Resource::TYPE_ENVIRONMENT_VARIABLE: @@ -2498,9 +2496,6 @@ class Appwrite extends Destination 'dart-2.17' => BuildRuntime::DART217(), 'dart-2.18' => BuildRuntime::DART218(), 'dart-2.19' => BuildRuntime::DART219(), - 'deno-1.21' => BuildRuntime::DENO121(), - 'deno-1.24' => BuildRuntime::DENO124(), - 'deno-1.35' => BuildRuntime::DENO135(), 'deno-1.40' => BuildRuntime::DENO140(), 'deno-1.46' => BuildRuntime::DENO146(), 'deno-2.0' => BuildRuntime::DENO20(), @@ -2573,7 +2568,8 @@ class Appwrite extends Destination $resource->getOutputDirectory(), $adapter, fallbackFile: $resource->getFallbackFile(), - specification: $resource->getSpecification(), + buildSpecification: $resource->getSpecification() ?: null, + runtimeSpecification: $resource->getSpecification() ?: null, ); break; case Resource::TYPE_SITE_VARIABLE: diff --git a/src/Migration/Sources/Appwrite/Reader/API.php b/src/Migration/Sources/Appwrite/Reader/API.php index 47a52f9dc6..f08a1f5f58 100644 --- a/src/Migration/Sources/Appwrite/Reader/API.php +++ b/src/Migration/Sources/Appwrite/Reader/API.php @@ -199,7 +199,7 @@ class API implements Reader $resource->getId(), $rowId, $queries - ); + )->toArray(); } /** From a5195bad3e7f56c40d45fdf03166e6e59a170c02 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Fri, 8 May 2026 12:11:49 +0100 Subject: [PATCH 77/91] refactor: convert SDK array-access to property access for typed models SDK 22+ returns typed Models without ArrayAccess, so existing \$response['key'] patterns fail at runtime ('Cannot use object of type Appwrite\Models\\\*List as array'). Convert all SDK call sites in Sources and Destinations to property access: - \$list['total'] / ['users'|'teams'|...] -> \$list->total / ->users - \$user['\$id'] -> \$user->id (SDK 22+ drops \$ prefix) - \$bucket['\$permissions'] -> \$bucket->permissions API Reader keeps its array contract (matches Database reader, used by existing callers): converts SDK typed responses via array_map ->toArray at the I/O boundary. \Appwrite\Models\Deployment param types added to exportDeploymentData and exportSiteDeploymentData. PHPStan level 7 finds zero remaining 'Cannot access offset on Appwrite\Models\\\*' errors. Level 3 (project default) clean. --- src/Migration/Destinations/Appwrite.php | 2 +- src/Migration/Sources/Appwrite.php | 386 +++++++++--------- src/Migration/Sources/Appwrite/Reader/API.php | 87 ++-- 3 files changed, 242 insertions(+), 233 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index c4271c6663..34866141cf 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -1999,7 +1999,7 @@ class Appwrite extends Destination $resource->getTransformations() ); - $resource->setId($response['$id']); + $resource->setId($response->id); } $resource->setStatus(Resource::STATUS_SUCCESS); diff --git a/src/Migration/Sources/Appwrite.php b/src/Migration/Sources/Appwrite.php index 48dc03d949..9c92fce745 100644 --- a/src/Migration/Sources/Appwrite.php +++ b/src/Migration/Sources/Appwrite.php @@ -288,7 +288,7 @@ class Appwrite extends Source limit: 1 ); $userList = $this->users->list($userQueries); - $report[Resource::TYPE_USER] = $userList['total']; + $report[Resource::TYPE_USER] = $userList->total; } if ($needTeams) { @@ -304,11 +304,11 @@ class Appwrite extends Source ); $teamList = $this->teams->list($params); - $totalTeams = $teamList['total']; - $currentTeams = $teamList['teams']; + $totalTeams = $teamList->total; + $currentTeams = $teamList->teams; $allTeams = array_merge($allTeams, $currentTeams); - $lastTeam = $currentTeams[count($currentTeams) - 1]['$id'] ?? null; + $lastTeam = end($currentTeams)?->id ?? null; if (count($currentTeams) < self::DEFAULT_PAGE_LIMIT) { break; @@ -322,7 +322,7 @@ class Appwrite extends Source limit: 1 ); $teamList = $this->teams->list($params); - $teams = ['total' => $teamList['total'], 'teams' => []]; + $teams = ['total' => $teamList->total, 'teams' => []]; } } @@ -334,9 +334,9 @@ class Appwrite extends Source $report[Resource::TYPE_MEMBERSHIP] = 0; foreach ($teams['teams'] as $team) { $report[Resource::TYPE_MEMBERSHIP] += $this->teams->listMemberships( - $team['$id'], + $team->id, [Query::limit(1)] - )['total']; + )->total; } } } @@ -364,7 +364,7 @@ class Appwrite extends Source resourceIds: $resourceIds, limit: 1 ); - $report[Resource::TYPE_BUCKET] = $this->storage->listBuckets($bucketQueries)['total']; + $report[Resource::TYPE_BUCKET] = $this->storage->listBuckets($bucketQueries)->total; } if (\in_array(Resource::TYPE_FILE, $resources)) { @@ -379,10 +379,10 @@ class Appwrite extends Source resourceIds: $resourceIds, cursor: $lastBucket, ); - $currentBuckets = $this->storage->listBuckets($queries)['buckets']; + $currentBuckets = $this->storage->listBuckets($queries)->buckets; $buckets = array_merge($buckets, $currentBuckets); - $lastBucket = $buckets[count($buckets) - 1]['$id'] ?? null; + $lastBucket = $buckets[count($buckets) - 1]->id ?? null; if (count($currentBuckets) < self::DEFAULT_PAGE_LIMIT) { break; @@ -391,12 +391,12 @@ class Appwrite extends Source foreach ($buckets as $bucket) { $filesResponse = $this->storage->listFiles( - $bucket['$id'], + $bucket->id, [Query::limit(1)] ); - $report['size'] += $bucket['totalSize'] ?? 0; - $report[Resource::TYPE_FILE] += $filesResponse['total']; + $report['size'] += $bucket->totalSize ?? 0; + $report[Resource::TYPE_FILE] += $filesResponse->total; } $report['size'] = $report['size'] / 1000 / 1000; // MB @@ -419,7 +419,7 @@ class Appwrite extends Source resourceIds: $resourceIds, limit: 1 ); - $report[Resource::TYPE_FUNCTION] = $this->functions->list($functionQueries)['total']; + $report[Resource::TYPE_FUNCTION] = $this->functions->list($functionQueries)->total; return; } @@ -433,11 +433,11 @@ class Appwrite extends Source ); $funcList = $this->functions->list($params); - $totalFunctions = $funcList['total']; - $currentFunctions = $funcList['functions']; + $totalFunctions = $funcList->total; + $currentFunctions = $funcList->functions; $functions = array_merge($functions, $currentFunctions); - $lastFunction = $currentFunctions[count($currentFunctions) - 1]['$id'] ?? null; + $lastFunction = $currentFunctions[count($currentFunctions) - 1]->id ?? null; if (count($currentFunctions) < self::DEFAULT_PAGE_LIMIT) { break; } @@ -451,7 +451,7 @@ class Appwrite extends Source if (\in_array(Resource::TYPE_DEPLOYMENT, $resources)) { $report[Resource::TYPE_DEPLOYMENT] = 0; foreach ($functions as $function) { - if (!empty($function['deploymentId'])) { + if (!empty($function->deploymentId)) { $report[Resource::TYPE_DEPLOYMENT] += 1; } } @@ -461,7 +461,7 @@ class Appwrite extends Source $report[Resource::TYPE_ENVIRONMENT_VARIABLE] = 0; foreach ($functions as $function) { // function model contains `vars`, we don't need to fetch the list again. - $report[Resource::TYPE_ENVIRONMENT_VARIABLE] += count($function['vars'] ?? []); + $report[Resource::TYPE_ENVIRONMENT_VARIABLE] += count($function->vars ?? []); } } } @@ -482,7 +482,7 @@ class Appwrite extends Source resourceIds: $resourceIds, limit: 1 ); - $report[Resource::TYPE_SITE] = $this->sites->list($siteQueries)['total']; + $report[Resource::TYPE_SITE] = $this->sites->list($siteQueries)->total; return; } @@ -496,15 +496,15 @@ class Appwrite extends Source ); $siteList = $this->sites->list($params); - $totalSites = $siteList['total']; - $currentSites = $siteList['sites']; + $totalSites = $siteList->total; + $currentSites = $siteList->sites; $sites = array_merge($sites, $currentSites); if (count($currentSites) === 0 || count($currentSites) < self::DEFAULT_PAGE_LIMIT) { break; } - $lastSite = $currentSites[count($currentSites) - 1]['$id']; + $lastSite = $currentSites[count($currentSites) - 1]->id; } } @@ -515,7 +515,7 @@ class Appwrite extends Source if (\in_array(Resource::TYPE_SITE_DEPLOYMENT, $resources)) { $report[Resource::TYPE_SITE_DEPLOYMENT] = 0; foreach ($sites as $site) { - if (!empty($site['deploymentId'])) { + if (!empty($site->deploymentId)) { $report[Resource::TYPE_SITE_DEPLOYMENT] += 1; } } @@ -524,8 +524,8 @@ class Appwrite extends Source if (\in_array(Resource::TYPE_SITE_VARIABLE, $resources)) { $report[Resource::TYPE_SITE_VARIABLE] = 0; foreach ($sites as $site) { - $variables = $this->sites->listVariables($site['$id']); - $report[Resource::TYPE_SITE_VARIABLE] += $variables['total'] ?? 0; + $variables = $this->sites->listVariables($site->id); + $report[Resource::TYPE_SITE_VARIABLE] += $variables->total ?? 0; } } } @@ -603,27 +603,27 @@ class Appwrite extends Source } $response = $this->users->list($queries); - if ($response['total'] == 0) { + if ($response->total == 0) { break; } - foreach ($response['users'] as $user) { + foreach ($response->users as $user) { $users[] = new User( - $user['$id'], - empty($user['email']) ? null : $user['email'], - empty($user['name']) ? null : $user['name'], - $user['password'] ? new Hash($user['password'], algorithm: $user['hash']) : null, - empty($user['phone']) ? null : $user['phone'], - $user['labels'] ?? [], + $user->id, + empty($user->email) ? null : $user->email, + empty($user->name) ? null : $user->name, + $user->password ? new Hash($user->password, algorithm: $user->hash) : null, + empty($user->phone) ? null : $user->phone, + $user->labels ?? [], '', - $user['emailVerification'] ?? false, - $user['phoneVerification'] ?? false, - !$user['status'], - $user['prefs'] ?? [], - $user['targets'] ?? [], + $user->emailVerification ?? false, + $user->phoneVerification ?? false, + !$user->status, + $user->prefs ?? [], + $user->targets ?? [], ); - $lastDocument = $user['$id']; + $lastDocument = $user->id; } $this->callback($users); @@ -657,18 +657,18 @@ class Appwrite extends Source } $response = $this->teams->list($queries); - if ($response['total'] == 0) { + if ($response->total == 0) { break; } - foreach ($response['teams'] as $team) { + foreach ($response->teams as $team) { $teams[] = new Team( - $team['$id'], - $team['name'], - $team['prefs'], + $team->id, + $team->name, + $team->prefs, ); - $lastDocument = $team['$id']; + $lastDocument = $team->id; } $this->callback($teams); @@ -709,25 +709,25 @@ class Appwrite extends Source $response = $this->teams->listMemberships($team->getId(), $queries); - if ($response['total'] == 0) { + if ($response->total == 0) { break; } - foreach ($response['memberships'] as $membership) { - $user = $cacheUsers[$membership['userId']] ?? null; + foreach ($response->memberships as $membership) { + $user = $cacheUsers[$membership->userId] ?? null; if ($user === null) { throw new \Exception('User not found', Exception::CODE_NOT_FOUND); } $memberships[] = new Membership( - $membership['$id'], + $membership->id, $team, $user, - $membership['roles'], - $membership['confirm'] + $membership->roles, + $membership->confirm ); - $lastDocument = $membership['$id']; + $lastDocument = $membership->id; } $this->callback($memberships); @@ -1245,20 +1245,20 @@ class Appwrite extends Source $convertedBuckets = []; - foreach ($buckets['buckets'] as $bucket) { + foreach ($buckets->buckets as $bucket) { $bucket = new Bucket( - $bucket['$id'], - $bucket['name'], - $bucket['$permissions'], - $bucket['fileSecurity'], - $bucket['enabled'], - $bucket['maximumFileSize'], - $bucket['allowedFileExtensions'], - $bucket['compression'], - $bucket['encryption'], - $bucket['antivirus'], + $bucket->id, + $bucket->name, + $bucket->permissions, + $bucket->fileSecurity, + $bucket->enabled, + $bucket->maximumFileSize, + $bucket->allowedFileExtensions, + $bucket->compression, + $bucket->encryption, + $bucket->antivirus, false, - $bucket['transformations'] ?? false, + $bucket->transformations ?? false, ); $convertedBuckets[] = $bucket; } @@ -1293,31 +1293,31 @@ class Appwrite extends Source $queries ); - foreach ($response['files'] as $file) { + foreach ($response->files as $file) { try { $this->exportFileData(new File( - $file['$id'], + $file->id, $bucket, - $file['name'], - $file['signature'], - $file['mimeType'], - $file['$permissions'], - $file['sizeOriginal'], + $file->name, + $file->signature, + $file->mimeType, + $file->permissions, + $file->sizeOriginal, )); } catch (\Throwable $e) { $this->addError(new Exception( resourceName: Resource::TYPE_FILE, resourceGroup: Transfer::GROUP_STORAGE, - resourceId: $file['$id'], + resourceId: $file->id, message: $e->getMessage(), code: $e->getCode() )); } - $lastDocument = $file['$id']; + $lastDocument = $file->id; } - if (count($response['files']) < $batchSize) { + if (count($response->files) < $batchSize) { break; } } @@ -1463,40 +1463,40 @@ class Appwrite extends Source $response = $this->functions->list($queries); - if ($response['total'] === 0) { + if ($response->total === 0) { return; } $functions = []; $convertedResources = []; - foreach ($response['functions'] as $function) { + foreach ($response->functions as $function) { $convertedFunc = new Func( - $function['$id'], - $function['name'], - $function['runtime'], - $function['execute'], - $function['enabled'], - $function['events'], - $function['schedule'], - $function['timeout'], - $function['deploymentId'] ?? '', - $function['entrypoint'], - $function['commands'] ?? '', - $function['logging'] ?? true, - $function['scopes'] ?? [], - $function['specification'] ?? '', + $function->id, + $function->name, + $function->runtime, + $function->execute, + $function->enabled, + $function->events, + $function->schedule, + $function->timeout, + $function->deploymentId ?? '', + $function->entrypoint, + $function->commands ?? '', + $function->logging ?? true, + $function->scopes ?? [], + $function->specification ?? '', ); $functions[] = $convertedFunc; $convertedResources[] = $convertedFunc; - foreach ($function['vars'] as $var) { + foreach ($function->vars as $var) { $convertedResources[] = new EnvVar( - $var['$id'], + $var->id, $convertedFunc, - $var['key'], - $var['value'], + $var->key, + $var->value, ); } } @@ -1551,17 +1551,17 @@ class Appwrite extends Source $queries ); - foreach ($response['deployments'] as $deployment) { + foreach ($response->deployments as $deployment) { try { $this->exportDeploymentData($func, $deployment); } catch (\Throwable $e) { $func->setStatus(Resource::STATUS_ERROR, $e->getMessage()); } - $lastDocument = $deployment['$id']; + $lastDocument = $deployment->id; } - if (count($response['deployments']) < $batchSize) { + if (count($response->deployments) < $batchSize) { break; } } @@ -1571,7 +1571,7 @@ class Appwrite extends Source /** * @throws \Exception */ - private function exportDeploymentData(Func $func, array $deployment): void + private function exportDeploymentData(Func $func, \Appwrite\Models\Deployment $deployment): void { // Set the chunk size (5MB) $start = 0; @@ -1582,7 +1582,7 @@ class Appwrite extends Source $this->call( 'HEAD', - "/functions/{$func->getId()}/deployments/{$deployment['$id']}/download", + "/functions/{$func->getId()}/deployments/{$deployment->id}/download", [], [], $responseHeaders @@ -1592,7 +1592,7 @@ class Appwrite extends Source if (!array_key_exists('content-length', $responseHeaders)) { $file = $this->call( 'GET', - "/functions/{$func->getId()}/deployments/{$deployment['$id']}/download", + "/functions/{$func->getId()}/deployments/{$deployment->id}/download", [], [], $responseHeaders @@ -1605,14 +1605,14 @@ class Appwrite extends Source } $deployment = new Deployment( - $deployment['$id'], + $deployment->id, $func, $size, - $deployment['entrypoint'], + $deployment->entrypoint, $start, $end, $file, - $deployment['activate'] + $deployment->activate ); $deployment->setSequence($deployment->getId()); @@ -1628,14 +1628,14 @@ class Appwrite extends Source } $deployment = new Deployment( - $deployment['$id'], + $deployment->id, $func, $fileSize, - $deployment['entrypoint'], + $deployment->entrypoint, $start, $end, '', - $deployment['activate'] + $deployment->activate ); $deployment->setSequence($deployment->getId()); @@ -1680,7 +1680,7 @@ class Appwrite extends Source resourceIds: $resourceIds, limit: 1 ); - $report[Resource::TYPE_PROVIDER] = $this->messaging->listProviders($providerQueries)['total']; + $report[Resource::TYPE_PROVIDER] = $this->messaging->listProviders($providerQueries)->total; } if (\in_array(Resource::TYPE_TOPIC, $resources)) { @@ -1689,7 +1689,7 @@ class Appwrite extends Source resourceIds: $resourceIds, limit: 1 ); - $report[Resource::TYPE_TOPIC] = $this->messaging->listTopics($topicQueries)['total']; + $report[Resource::TYPE_TOPIC] = $this->messaging->listTopics($topicQueries)->total; } if (\in_array(Resource::TYPE_SUBSCRIBER, $resources)) { @@ -1703,16 +1703,16 @@ class Appwrite extends Source } $topicResponse = $this->messaging->listTopics($topicQueries); - if ($topicResponse['total'] == 0 || empty($topicResponse['topics'])) { + if ($topicResponse->total == 0 || empty($topicResponse->topics)) { break; } - foreach ($topicResponse['topics'] as $topic) { - $subscriberTotal += $this->messaging->listSubscribers($topic['$id'], [Query::limit(1)])['total']; - $lastTopic = $topic['$id']; + foreach ($topicResponse->topics as $topic) { + $subscriberTotal += $this->messaging->listSubscribers($topic->id, [Query::limit(1)])->total; + $lastTopic = $topic->id; } - if (\count($topicResponse['topics']) < self::DEFAULT_PAGE_LIMIT) { + if (\count($topicResponse->topics) < self::DEFAULT_PAGE_LIMIT) { break; } } @@ -1726,7 +1726,7 @@ class Appwrite extends Source resourceIds: $resourceIds, limit: 1 ); - $report[Resource::TYPE_MESSAGE] = $this->messaging->listMessages($messageQueries)['total']; + $report[Resource::TYPE_MESSAGE] = $this->messaging->listMessages($messageQueries)->total; } } @@ -1812,24 +1812,24 @@ class Appwrite extends Source $response = $this->messaging->listProviders($queries); - if ($response['total'] == 0) { + if ($response->total == 0) { break; } - foreach ($response['providers'] as $provider) { + foreach ($response->providers as $provider) { $providers[] = new Provider( - $provider['$id'], - $provider['name'], - $provider['provider'], - $provider['type'], - $provider['enabled'], - $provider['credentials'] ?? [], - $provider['options'] ?? [], - $provider['$createdAt'] ?? '', - $provider['$updatedAt'] ?? '', + $provider->id, + $provider->name, + $provider->provider, + $provider->type, + $provider->enabled, + $provider->credentials ?? [], + $provider->options ?? [], + $provider->createdAt ?? '', + $provider->updatedAt ?? '', ); - $lastDocument = $provider['$id']; + $lastDocument = $provider->id; } $this->callback($providers); @@ -1863,20 +1863,20 @@ class Appwrite extends Source $response = $this->messaging->listTopics($queries); - if ($response['total'] == 0) { + if ($response->total == 0) { break; } - foreach ($response['topics'] as $topic) { + foreach ($response->topics as $topic) { $topics[] = new Topic( - $topic['$id'], - $topic['name'], - $topic['subscribe'] ?? [], - $topic['$createdAt'] ?? '', - $topic['$updatedAt'] ?? '', + $topic->id, + $topic->name, + $topic->subscribe ?? [], + $topic->createdAt ?? '', + $topic->updatedAt ?? '', ); - $lastDocument = $topic['$id']; + $lastDocument = $topic->id; } $this->callback($topics); @@ -1909,23 +1909,23 @@ class Appwrite extends Source $response = $this->messaging->listSubscribers($topic->getId(), $queries); - if ($response['total'] == 0) { + if ($response->total == 0) { break; } - foreach ($response['subscribers'] as $subscriber) { + foreach ($response->subscribers as $subscriber) { $subscribers[] = new Subscriber( - $subscriber['$id'], - $subscriber['topicId'], - $subscriber['targetId'], - $subscriber['userId'] ?? '', - $subscriber['userName'] ?? '', - $subscriber['providerType'] ?? '', - $subscriber['$createdAt'] ?? '', - $subscriber['$updatedAt'] ?? '', + $subscriber->id, + $subscriber->topicId, + $subscriber->targetId, + $subscriber->userId ?? '', + $subscriber->userName ?? '', + $subscriber->providerType ?? '', + $subscriber->createdAt ?? '', + $subscriber->updatedAt ?? '', ); - $lastDocument = $subscriber['$id']; + $lastDocument = $subscriber->id; } $this->callback($subscribers); @@ -1960,28 +1960,28 @@ class Appwrite extends Source $response = $this->messaging->listMessages($queries); - if ($response['total'] == 0) { + if ($response->total == 0) { break; } - foreach ($response['messages'] as $message) { + foreach ($response->messages as $message) { $messages[] = new Message( - $message['$id'], - $message['providerType'] ?? '', - $message['topics'] ?? [], - $message['users'] ?? [], - $message['targets'] ?? [], - $message['data'] ?? [], - $message['status'] ?? '', - $message['scheduledAt'] ?? '', - $message['deliveredAt'] ?? '', - $message['deliveryErrors'] ?? [], - $message['deliveredTotal'] ?? 0, - $message['$createdAt'] ?? '', - $message['$updatedAt'] ?? '', + $message->id, + $message->providerType ?? '', + $message->topics ?? [], + $message->users ?? [], + $message->targets ?? [], + $message->data ?? [], + $message->status ?? '', + $message->scheduledAt ?? '', + $message->deliveredAt ?? '', + $message->deliveryErrors ?? [], + $message->deliveredTotal ?? 0, + $message->createdAt ?? '', + $message->updatedAt ?? '', ); - $lastDocument = $message['$id']; + $lastDocument = $message->id; } $this->callback($messages); @@ -2015,40 +2015,40 @@ class Appwrite extends Source $response = $this->sites->list($queries); - if ($response['total'] === 0) { + if ($response->total === 0) { return; } $sites = []; $convertedResources = []; - foreach ($response['sites'] as $site) { + foreach ($response->sites as $site) { $convertedSite = new Site( - $site['$id'], - $site['name'], - $site['framework'], - $site['buildRuntime'], - $site['enabled'], - $site['logging'], - $site['timeout'], - $site['installCommand'] ?? '', - $site['buildCommand'] ?? '', - $site['outputDirectory'] ?? '', - $site['adapter'] ?? 'static', - $site['fallbackFile'] ?? '', - $site['specification'] ?? '', - $site['deploymentId'] ?? '' + $site->id, + $site->name, + $site->framework, + $site->buildRuntime, + $site->enabled, + $site->logging, + $site->timeout, + $site->installCommand ?? '', + $site->buildCommand ?? '', + $site->outputDirectory ?? '', + $site->adapter ?? 'static', + $site->fallbackFile ?? '', + $site->specification ?? '', + $site->deploymentId ?? '' ); $sites[] = $convertedSite; $convertedResources[] = $convertedSite; - $variables = $this->sites->listVariables($site['$id']); - foreach ($variables['variables'] ?? [] as $var) { + $variables = $this->sites->listVariables($site->id); + foreach ($variables->variables ?? [] as $var) { $convertedResources[] = new SiteEnvVar( - $var['$id'], + $var->id, $convertedSite, - $var['key'], - $var['value'] + $var->key, + $var->value ); } } @@ -2104,17 +2104,17 @@ class Appwrite extends Source $queries ); - foreach ($response['deployments'] as $deployment) { + foreach ($response->deployments as $deployment) { try { $this->exportSiteDeploymentData($site, $deployment); } catch (\Throwable $e) { $site->setStatus(Resource::STATUS_ERROR, $e->getMessage()); } - $lastDocument = $deployment['$id']; + $lastDocument = $deployment->id; } - if (count($response['deployments']) < $batchSize) { + if (count($response->deployments) < $batchSize) { break; } } @@ -2124,7 +2124,7 @@ class Appwrite extends Source /** * @throws \Exception */ - private function exportSiteDeploymentData(Site $site, array $deployment): void + private function exportSiteDeploymentData(Site $site, \Appwrite\Models\Deployment $deployment): void { $start = 0; $end = Transfer::STORAGE_MAX_CHUNK_SIZE - 1; @@ -2133,7 +2133,7 @@ class Appwrite extends Source $this->call( 'HEAD', - "/sites/{$site->getId()}/deployments/{$deployment['$id']}/download", + "/sites/{$site->getId()}/deployments/{$deployment->id}/download", [], [], $responseHeaders @@ -2142,7 +2142,7 @@ class Appwrite extends Source if (!\array_key_exists('content-length', $responseHeaders)) { $file = $this->call( 'GET', - "/sites/{$site->getId()}/deployments/{$deployment['$id']}/download", + "/sites/{$site->getId()}/deployments/{$deployment->id}/download", [], [], $responseHeaders @@ -2155,13 +2155,13 @@ class Appwrite extends Source } $siteDeployment = new SiteDeployment( - $deployment['$id'], + $deployment->id, $site, $size, $start, $end, $file, - $deployment['$id'] === $site->getActiveDeployment() + $deployment->id === $site->getActiveDeployment() ); $siteDeployment->setSequence($siteDeployment->getId()); @@ -2177,13 +2177,13 @@ class Appwrite extends Source } $siteDeployment = new SiteDeployment( - $deployment['$id'], + $deployment->id, $site, $fileSize, $start, $end, '', - $deployment['$id'] === $site->getActiveDeployment() + $deployment->id === $site->getActiveDeployment() ); $siteDeployment->setSequence($siteDeployment->getId()); diff --git a/src/Migration/Sources/Appwrite/Reader/API.php b/src/Migration/Sources/Appwrite/Reader/API.php index f08a1f5f58..a187e8c927 100644 --- a/src/Migration/Sources/Appwrite/Reader/API.php +++ b/src/Migration/Sources/Appwrite/Reader/API.php @@ -11,6 +11,10 @@ use Utopia\Migration\Resources\Database\Table; use Utopia\Migration\Sources\Appwrite\Reader; /** + * Adapts Appwrite SDK typed models to the Reader's plain-array contract so that + * downstream callers can use array-offset syntax interchangeably with the + * Database reader (which returns utopia-php Document objects). + * * @implements Reader */ class API implements Reader @@ -51,10 +55,10 @@ class API implements Reader } $databasesResponse = $this->database->list($databaseQueries); - $databases = $databasesResponse['databases']; + $databases = \array_map(fn ($database) => $database->toArray(), $databasesResponse->databases); if (in_array(Resource::TYPE_DATABASE, $resources)) { - $report[Resource::TYPE_DATABASE] = $databasesResponse['total']; + $report[Resource::TYPE_DATABASE] = $databasesResponse->total; } if (count(array_intersect($resources, $relevantResources)) === 1 && @@ -71,12 +75,13 @@ class API implements Reader $lastTable = null; while (true) { - $currentTables = $this->database->listTables( + $tablesResponse = $this->database->listTables( $databaseId, $lastTable ? [Query::cursorAfter($lastTable)] : [Query::limit($pageLimit)] - )['tables']; + ); + $currentTables = \array_map(fn ($table) => $table->toArray(), $tablesResponse->tables); $tables = \array_merge($tables, $currentTables); $lastTable = $tables[count($tables) - 1]['$id'] ?? null; @@ -111,7 +116,7 @@ class API implements Reader [Query::limit(1)] ); - $report[Resource::TYPE_ROW] += $rowsResponse['total']; + $report[Resource::TYPE_ROW] += $rowsResponse->total; } } } @@ -121,75 +126,79 @@ class API implements Reader } /** + * @return array> * @throws AppwriteException */ public function listDatabases(array $queries = []): array { - return $this->database->list($queries)['databases']; + return \array_map( + fn ($database) => $database->toArray(), + $this->database->list($queries)->databases + ); } /** + * @return array> * @throws AppwriteException */ public function listTables(Database $resource, array $queries = []): array { - return $this->database->listTables( - $resource->getId(), - $queries - )['tables']; + return \array_map( + fn ($table) => $table->toArray(), + $this->database->listTables($resource->getId(), $queries)->tables + ); } /** - * @param Table $resource - * @param array $queries - * @return array + * @return array> * @throws AppwriteException */ public function listColumns(Table $resource, array $queries = []): array { - return $this->database->listColumns( - $resource->getDatabase()->getId(), - $resource->getId(), - $queries - )['columns']; + return \array_map( + fn ($column) => $column->toArray(), + $this->database->listColumns( + $resource->getDatabase()->getId(), + $resource->getId(), + $queries + )->columns + ); } /** - * @param Table $resource - * @param array $queries - * @return array + * @return array> * @throws AppwriteException */ public function listIndexes(Table $resource, array $queries = []): array { - return $this->database->listIndexes( - $resource->getDatabase()->getId(), - $resource->getId(), - $queries - )['indexes']; + return \array_map( + fn ($index) => $index->toArray(), + $this->database->listIndexes( + $resource->getDatabase()->getId(), + $resource->getId(), + $queries + )->indexes + ); } - /** - * @param Table $resource - * @param array $queries - * @return array + * @return array> * @throws AppwriteException */ public function listRows(Table $resource, array $queries = []): array { - return $this->database->listRows( - $resource->getDatabase()->getId(), - $resource->getId(), - $queries - )['rows']; + return \array_map( + fn ($row) => $row->toArray(), + $this->database->listRows( + $resource->getDatabase()->getId(), + $resource->getId(), + $queries + )->rows + ); } /** - * @param Table $resource - * @param string $rowId - * @param array $queries - * @return array + * @return array * @throws AppwriteException */ public function getRow(Table $resource, string $rowId, array $queries = []): array From 80e9a0498e1a1a2667607fa4b4aca44a7b4590ab Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Fri, 8 May 2026 16:29:18 +0100 Subject: [PATCH 78/91] fix: handle SDK 23 nested typed objects (Preferences, Target, MessageStatus) Five runtime bugs missed in the previous regex pass; PHPStan level 8 caught them when checking against the SDK Models. Migration's resource constructors expect plain arrays / strings, not the nested typed objects SDK 23 returns: - \$user->prefs is Preferences object -> use ->data array - \$user->targets is array -> array_map(fn(\$t) => \$t->toArray()) - \$team->prefs same Preferences fix - \$function->specification doesn't exist on FunctionModel any more; read runtimeSpecification ?: buildSpecification (SDK 21 split) - \$site->specification same Site fix - \$message->status is MessageStatus enum -> cast to string via __toString PHPStan level 3 (project default) clean. Level 8 has no remaining SDK type issues across Sources/Destinations/Reader. --- src/Migration/Sources/Appwrite.php | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/Migration/Sources/Appwrite.php b/src/Migration/Sources/Appwrite.php index 9c92fce745..2b5906d887 100644 --- a/src/Migration/Sources/Appwrite.php +++ b/src/Migration/Sources/Appwrite.php @@ -619,8 +619,8 @@ class Appwrite extends Source $user->emailVerification ?? false, $user->phoneVerification ?? false, !$user->status, - $user->prefs ?? [], - $user->targets ?? [], + $user->prefs->data ?? [], + \array_map(fn ($target) => $target->toArray(), $user->targets ?? []), ); $lastDocument = $user->id; @@ -665,7 +665,7 @@ class Appwrite extends Source $teams[] = new Team( $team->id, $team->name, - $team->prefs, + $team->prefs->data, ); $lastDocument = $team->id; @@ -1485,7 +1485,7 @@ class Appwrite extends Source $function->commands ?? '', $function->logging ?? true, $function->scopes ?? [], - $function->specification ?? '', + $function->runtimeSpecification ?: $function->buildSpecification ?: '', ); $functions[] = $convertedFunc; @@ -1972,7 +1972,7 @@ class Appwrite extends Source $message->users ?? [], $message->targets ?? [], $message->data ?? [], - $message->status ?? '', + (string) $message->status, $message->scheduledAt ?? '', $message->deliveredAt ?? '', $message->deliveryErrors ?? [], @@ -2036,7 +2036,7 @@ class Appwrite extends Source $site->outputDirectory ?? '', $site->adapter ?? 'static', $site->fallbackFile ?? '', - $site->specification ?? '', + $site->runtimeSpecification ?: $site->buildSpecification ?: '', $site->deploymentId ?? '' ); $sites[] = $convertedSite; From 0e88268d10fef0475de1fa292cbb571ce64e4837 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Sat, 9 May 2026 01:23:29 +0100 Subject: [PATCH 79/91] fix: pass variableId to Functions::createVariable and Sites::createVariable SDK 23.1 added a required \$variableId 2nd parameter: - Sites::createVariable(\$siteId, \$variableId, \$key, \$value, ?\$secret) - Functions::createVariable(\$functionId, \$variableId, \$key, \$value, ?\$secret) Pass the migration resource's id as \$variableId so the destination preserves the source variable id. Bumps appwrite/appwrite to 23.1.0 in composer.lock. --- composer.lock | 12 ++++++------ src/Migration/Destinations/Appwrite.php | 2 ++ 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/composer.lock b/composer.lock index c32afe7088..bd8c429bb6 100644 --- a/composer.lock +++ b/composer.lock @@ -8,16 +8,16 @@ "packages": [ { "name": "appwrite/appwrite", - "version": "23.0.0", + "version": "23.1.0", "source": { "type": "git", "url": "https://github.com/appwrite/sdk-for-php.git", - "reference": "d22b36167931294bec4259f0803aba14537030ec" + "reference": "2f275921f10ceb7cff99f2d463f7328b296234fa" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/appwrite/sdk-for-php/zipball/d22b36167931294bec4259f0803aba14537030ec", - "reference": "d22b36167931294bec4259f0803aba14537030ec", + "url": "https://api.github.com/repos/appwrite/sdk-for-php/zipball/2f275921f10ceb7cff99f2d463f7328b296234fa", + "reference": "2f275921f10ceb7cff99f2d463f7328b296234fa", "shasum": "" }, "require": { @@ -43,10 +43,10 @@ "support": { "email": "team@appwrite.io", "issues": "https://github.com/appwrite/sdk-for-php/issues", - "source": "https://github.com/appwrite/sdk-for-php/tree/23.0.0", + "source": "https://github.com/appwrite/sdk-for-php/tree/23.1.0", "url": "https://appwrite.io/support" }, - "time": "2026-04-16T12:38:44+00:00" + "time": "2026-05-08T13:44:58+00:00" }, { "name": "brick/math", diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index 34866141cf..29a68634a3 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -2327,6 +2327,7 @@ class Appwrite extends Destination /** @var EnvVar $resource */ $this->functions->createVariable( $resource->getFunc()->getId(), + $resource->getId(), $resource->getKey(), $resource->getValue() ); @@ -2576,6 +2577,7 @@ class Appwrite extends Destination /** @var SiteEnvVar $resource */ $this->sites->createVariable( $resource->getSite()->getId(), + $resource->getId(), $resource->getKey(), $resource->getValue() ); From 6deabc665472639d5615e923cc43bb3d9c8aadca Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Sun, 10 May 2026 05:07:41 +0100 Subject: [PATCH 80/91] fix: use named arguments for Sites/Functions create + createVariable MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit SDK 23.1 inserted \$startCommand between \$buildCommand and \$outputDirectory in Sites::create, which silently shifted positional calls — outputDirectory landed in startCommand and adapter landed in outputDirectory, causing testAppwriteMigrationSite to migrate sites with empty adapter. Fixed by switching to named arguments. Apply the same to: - Functions::create - Functions::createVariable - Sites::createVariable Named args are robust against future positional insertions in the generated SDK. --- src/Migration/Destinations/Appwrite.php | 62 ++++++++++++------------- 1 file changed, 31 insertions(+), 31 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index 29a68634a3..71ab9da828 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -2307,18 +2307,18 @@ class Appwrite extends Destination }; $this->functions->create( - $resource->getId(), - $resource->getFunctionName(), - $runtime, - $resource->getExecute(), - $resource->getEvents(), - $resource->getSchedule(), - $resource->getTimeout(), - $resource->getEnabled(), - $resource->getLogging(), - $resource->getEntrypoint(), - $resource->getCommands(), - $resource->getScopes(), + functionId: $resource->getId(), + name: $resource->getFunctionName(), + runtime: $runtime, + execute: $resource->getExecute(), + events: $resource->getEvents(), + schedule: $resource->getSchedule(), + timeout: $resource->getTimeout(), + enabled: $resource->getEnabled(), + logging: $resource->getLogging(), + entrypoint: $resource->getEntrypoint(), + commands: $resource->getCommands(), + scopes: $resource->getScopes(), buildSpecification: $resource->getSpecification() ?: null, runtimeSpecification: $resource->getSpecification() ?: null, ); @@ -2326,10 +2326,10 @@ class Appwrite extends Destination case Resource::TYPE_ENVIRONMENT_VARIABLE: /** @var EnvVar $resource */ $this->functions->createVariable( - $resource->getFunc()->getId(), - $resource->getId(), - $resource->getKey(), - $resource->getValue() + functionId: $resource->getFunc()->getId(), + variableId: $resource->getId(), + key: $resource->getKey(), + value: $resource->getValue(), ); break; case Resource::TYPE_DEPLOYMENT: @@ -2557,17 +2557,17 @@ class Appwrite extends Destination }; $this->sites->create( - $resource->getId(), - $resource->getSiteName(), - $framework, - $buildRuntime, - $resource->getEnabled(), - $resource->getLogging(), - $resource->getTimeout(), - $resource->getInstallCommand(), - $resource->getBuildCommand(), - $resource->getOutputDirectory(), - $adapter, + siteId: $resource->getId(), + name: $resource->getSiteName(), + framework: $framework, + buildRuntime: $buildRuntime, + enabled: $resource->getEnabled(), + logging: $resource->getLogging(), + timeout: $resource->getTimeout(), + installCommand: $resource->getInstallCommand(), + buildCommand: $resource->getBuildCommand(), + outputDirectory: $resource->getOutputDirectory(), + adapter: $adapter, fallbackFile: $resource->getFallbackFile(), buildSpecification: $resource->getSpecification() ?: null, runtimeSpecification: $resource->getSpecification() ?: null, @@ -2576,10 +2576,10 @@ class Appwrite extends Destination case Resource::TYPE_SITE_VARIABLE: /** @var SiteEnvVar $resource */ $this->sites->createVariable( - $resource->getSite()->getId(), - $resource->getId(), - $resource->getKey(), - $resource->getValue() + siteId: $resource->getSite()->getId(), + variableId: $resource->getId(), + key: $resource->getKey(), + value: $resource->getValue(), ); break; case Resource::TYPE_SITE_DEPLOYMENT: From e5dc657423bea96941cd71e5f0b060fd8b047b56 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Mon, 11 May 2026 02:20:10 +0100 Subject: [PATCH 81/91] fix: fallback deprecated deno-1.21/1.24/1.35 runtimes to DENO140 Migrations from older Appwrite servers may still have functions registered with deno-1.21 / 1.24 / 1.35. SDK 23 dropped those Runtime factory methods. Rather than throwing 'Invalid Runtime' and breaking the migration, transparently bump these deprecated runtimes to deno-1.40, the nearest still-supported version (already mapped). --- src/Migration/Destinations/Appwrite.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index 71ab9da828..840df6f6cb 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -2277,7 +2277,7 @@ class Appwrite extends Destination 'dart-2.17' => Runtime::DART217(), 'dart-2.18' => Runtime::DART218(), 'dart-2.19' => Runtime::DART219(), - 'deno-1.40' => Runtime::DENO140(), + 'deno-1.21', 'deno-1.24', 'deno-1.35', 'deno-1.40' => Runtime::DENO140(), 'deno-1.46' => Runtime::DENO146(), 'deno-2.0' => Runtime::DENO20(), 'dotnet-6.0' => Runtime::DOTNET60(), @@ -2497,7 +2497,7 @@ class Appwrite extends Destination 'dart-2.17' => BuildRuntime::DART217(), 'dart-2.18' => BuildRuntime::DART218(), 'dart-2.19' => BuildRuntime::DART219(), - 'deno-1.40' => BuildRuntime::DENO140(), + 'deno-1.21', 'deno-1.24', 'deno-1.35', 'deno-1.40' => BuildRuntime::DENO140(), 'deno-1.46' => BuildRuntime::DENO146(), 'deno-2.0' => BuildRuntime::DENO20(), 'dotnet-6.0' => BuildRuntime::DOTNET60(), From a9bdfba24cd1f069a0c4f28a6060999e5741fc28 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Mon, 11 May 2026 02:27:17 +0100 Subject: [PATCH 82/91] Revert "fix: fallback deprecated deno-1.21/1.24/1.35 runtimes to DENO140" This reverts commit e5dc657423bea96941cd71e5f0b060fd8b047b56. --- src/Migration/Destinations/Appwrite.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index 840df6f6cb..71ab9da828 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -2277,7 +2277,7 @@ class Appwrite extends Destination 'dart-2.17' => Runtime::DART217(), 'dart-2.18' => Runtime::DART218(), 'dart-2.19' => Runtime::DART219(), - 'deno-1.21', 'deno-1.24', 'deno-1.35', 'deno-1.40' => Runtime::DENO140(), + 'deno-1.40' => Runtime::DENO140(), 'deno-1.46' => Runtime::DENO146(), 'deno-2.0' => Runtime::DENO20(), 'dotnet-6.0' => Runtime::DOTNET60(), @@ -2497,7 +2497,7 @@ class Appwrite extends Destination 'dart-2.17' => BuildRuntime::DART217(), 'dart-2.18' => BuildRuntime::DART218(), 'dart-2.19' => BuildRuntime::DART219(), - 'deno-1.21', 'deno-1.24', 'deno-1.35', 'deno-1.40' => BuildRuntime::DENO140(), + 'deno-1.40' => BuildRuntime::DENO140(), 'deno-1.46' => BuildRuntime::DENO146(), 'deno-2.0' => BuildRuntime::DENO20(), 'dotnet-6.0' => BuildRuntime::DOTNET60(), From 4dc72708497729f1aacb133a814bb5b0adab5a8d Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Mon, 11 May 2026 02:37:10 +0100 Subject: [PATCH 83/91] fix(source): guard against empty teams page when computing cursor end([]) returns false, and PHP's nullsafe operator (?->) only short-circuits on null. end($empty)?->id therefore throws TypeError when the teams response is empty, breaking reportAuth for accounts without teams. Replace with an explicit empty check. --- src/Migration/Sources/Appwrite.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Migration/Sources/Appwrite.php b/src/Migration/Sources/Appwrite.php index 2b5906d887..94368e5e88 100644 --- a/src/Migration/Sources/Appwrite.php +++ b/src/Migration/Sources/Appwrite.php @@ -308,7 +308,7 @@ class Appwrite extends Source $currentTeams = $teamList->teams; $allTeams = array_merge($allTeams, $currentTeams); - $lastTeam = end($currentTeams)?->id ?? null; + $lastTeam = empty($currentTeams) ? null : end($currentTeams)->id; if (count($currentTeams) < self::DEFAULT_PAGE_LIMIT) { break; From 447a98706d752254a1cc7829a6d76f3a201b799c Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Mon, 11 May 2026 02:47:15 +0100 Subject: [PATCH 84/91] fix(deps): require PHP >=8.2 and fix composer config.platform MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit appwrite/appwrite 23.x (via SDK 22.0.0) requires PHP >=8.2.0, but this lib's require.php was >=8.1 — composer install would fail on PHP 8.1 consumers. The previous top-level 'platform' key was silently ignored by Composer (must live under 'config.platform'), which hid the inconsistency locally. Move it under 'config.platform' and bump to 8.2 to match the require constraint. --- composer.json | 9 +++++---- composer.lock | 19 +++++++++++-------- 2 files changed, 16 insertions(+), 12 deletions(-) diff --git a/composer.json b/composer.json index 8649e3befd..896a388cd3 100644 --- a/composer.json +++ b/composer.json @@ -22,9 +22,10 @@ "check": "./vendor/bin/phpstan analyse --level 3 src tests --memory-limit 2G" }, "require": { - "php": ">=8.1", + "php": ">=8.2", "ext-curl": "*", "ext-openssl": "*", + "appwrite/appwrite": "23.*", "utopia-php/database": "5.*", "utopia-php/storage": "2.*", @@ -38,10 +39,10 @@ "laravel/pint": "1.*", "phpstan/phpstan": "1.*" }, - "platform": { - "php": "8.1" - }, "config": { + "platform": { + "php": "8.2" + }, "allow-plugins": { "php-http/discovery": true, "tbachert/spi": true diff --git a/composer.lock b/composer.lock index bd8c429bb6..246268b65b 100644 --- a/composer.lock +++ b/composer.lock @@ -4,7 +4,7 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "577cd7fb43f3f832869661126e0a5090", + "content-hash": "b437ef18d3106e157d1d9363962137a4", "packages": [ { "name": "appwrite/appwrite", @@ -2138,16 +2138,16 @@ }, { "name": "utopia-php/cache", - "version": "1.0.1", + "version": "1.0.2", "source": { "type": "git", "url": "https://github.com/utopia-php/cache.git", - "reference": "05ceba981436a4022553f7aaa2a05fa049d0f71c" + "reference": "d36f9050c39c02e09a7763389c9e71258e74af1f" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/cache/zipball/05ceba981436a4022553f7aaa2a05fa049d0f71c", - "reference": "05ceba981436a4022553f7aaa2a05fa049d0f71c", + "url": "https://api.github.com/repos/utopia-php/cache/zipball/d36f9050c39c02e09a7763389c9e71258e74af1f", + "reference": "d36f9050c39c02e09a7763389c9e71258e74af1f", "shasum": "" }, "require": { @@ -2184,9 +2184,9 @@ ], "support": { "issues": "https://github.com/utopia-php/cache/issues", - "source": "https://github.com/utopia-php/cache/tree/1.0.1" + "source": "https://github.com/utopia-php/cache/tree/1.0.2" }, - "time": "2026-03-12T03:39:09+00:00" + "time": "2026-05-08T11:40:20+00:00" }, { "name": "utopia-php/console", @@ -4964,12 +4964,15 @@ "prefer-stable": false, "prefer-lowest": false, "platform": { - "php": ">=8.1", + "php": ">=8.2", "ext-curl": "*", "ext-openssl": "*" }, "platform-dev": { "ext-pdo": "*" }, + "platform-overrides": { + "php": "8.2" + }, "plugin-api-version": "2.9.0" } From 2681028af256838e4d291e6cd539aeb427d5fc6e Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Mon, 11 May 2026 08:13:31 +0100 Subject: [PATCH 85/91] chore(deps): drop config.platform pin Per review: pinning config.platform.php to 8.2 forces composer to resolve against 8.2, which can hold back deps that need 8.3+. The "php": ">=8.2" require constraint is the signal that matters. --- composer.json | 3 --- composer.lock | 5 +---- 2 files changed, 1 insertion(+), 7 deletions(-) diff --git a/composer.json b/composer.json index 896a388cd3..6bd6404197 100644 --- a/composer.json +++ b/composer.json @@ -40,9 +40,6 @@ "phpstan/phpstan": "1.*" }, "config": { - "platform": { - "php": "8.2" - }, "allow-plugins": { "php-http/discovery": true, "tbachert/spi": true diff --git a/composer.lock b/composer.lock index 246268b65b..ab0a68c73c 100644 --- a/composer.lock +++ b/composer.lock @@ -4,7 +4,7 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "b437ef18d3106e157d1d9363962137a4", + "content-hash": "44746ecb1183e23d963fc90b1481541a", "packages": [ { "name": "appwrite/appwrite", @@ -4971,8 +4971,5 @@ "platform-dev": { "ext-pdo": "*" }, - "platform-overrides": { - "php": "8.2" - }, "plugin-api-version": "2.9.0" } From 18a8f88aa8d58a7c6cd58195e4138e65e8ac07eb Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Wed, 13 May 2026 16:45:18 +0100 Subject: [PATCH 86/91] Remove console-key fetch from Appwrite source; use project API key directly --- src/Migration/Sources/Appwrite.php | 90 +++++------------------------- 1 file changed, 14 insertions(+), 76 deletions(-) diff --git a/src/Migration/Sources/Appwrite.php b/src/Migration/Sources/Appwrite.php index b1de4654c7..2e245cf601 100644 --- a/src/Migration/Sources/Appwrite.php +++ b/src/Migration/Sources/Appwrite.php @@ -98,10 +98,6 @@ class Appwrite extends Source */ protected mixed $getDatabasesDB; - private bool $consoleKeyFetched = false; - - private ?string $consoleKey = null; - /** * @throws \Exception */ @@ -152,38 +148,6 @@ class Appwrite extends Source } } - public function setConsoleKey(string $key): void - { - $this->consoleKey = $key; - $this->consoleKeyFetched = true; - } - - /** - * @return array|null - */ - protected function getConsoleHeaders(): ?array - { - if (!$this->consoleKeyFetched) { - $this->consoleKeyFetched = true; - - try { - $response = $this->call('POST', '/migrations/appwrite/console-key'); - $this->consoleKey = $response['key'] ?? null; - } catch (\Throwable) { - $this->consoleKey = null; - } - } - - if ($this->consoleKey === null) { - return null; - } - - return [ - 'x-appwrite-project' => 'console', - 'x-appwrite-key' => $this->consoleKey, - ]; - } - public static function getName(): string { return 'Appwrite'; @@ -2260,14 +2224,8 @@ class Appwrite extends Source private function reportIntegrations(array $resources, array &$report, array $resourceIds = []): void { if (\in_array(Resource::TYPE_PLATFORM, $resources)) { - $consoleHeaders = $this->getConsoleHeaders(); - - if ($consoleHeaders === null) { - return; - } - try { - $response = $this->call('GET', '/projects/' . $this->project . '/platforms', $consoleHeaders); + $response = $this->call('GET', '/projects/' . $this->project . '/platforms'); $report[Resource::TYPE_PLATFORM] = $response['total'] ?? 0; } catch (\Throwable) { $report[Resource::TYPE_PLATFORM] = 0; @@ -2306,37 +2264,17 @@ class Appwrite extends Source protected function exportGroupIntegrations(int $batchSize, array $resources): void { if (\in_array(Resource::TYPE_PLATFORM, $resources)) { - $this->exportWithConsoleHeaders( - Resource::TYPE_PLATFORM, - Transfer::GROUP_INTEGRATIONS, - $this->exportPlatforms(...) - ); - } - } - - protected function exportWithConsoleHeaders(string $resourceType, string $group, callable $callback): void - { - $consoleHeaders = $this->getConsoleHeaders(); - - if ($consoleHeaders === null) { - $this->addError(new Exception( - $resourceType, - $group, - message: 'Console key unavailable for source instance', - )); - return; - } - - try { - $callback($consoleHeaders); - } catch (\Throwable $e) { - $this->addError(new Exception( - $resourceType, - $group, - message: $e->getMessage(), - code: $e->getCode(), - previous: $e - )); + try { + $this->exportPlatforms(); + } catch (\Throwable $e) { + $this->addError(new Exception( + Resource::TYPE_PLATFORM, + Transfer::GROUP_INTEGRATIONS, + message: $e->getMessage(), + code: $e->getCode(), + previous: $e + )); + } } } @@ -2373,9 +2311,9 @@ class Appwrite extends Source /** * @throws AppwriteException */ - private function exportPlatforms(array $consoleHeaders): void + private function exportPlatforms(): void { - $response = $this->call('GET', '/projects/' . $this->project . '/platforms', $consoleHeaders); + $response = $this->call('GET', '/projects/' . $this->project . '/platforms'); if (empty($response['platforms'])) { return; From 01ae076235b2b3c7ad636778620dcd31a97ed892 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Wed, 13 May 2026 21:07:56 +0100 Subject: [PATCH 87/91] Pass dbForPlatform and projectInternalId in Appwrite destination test ctor --- .../Migration/Unit/Destinations/AppwriteDestinationDsnTest.php | 2 ++ 1 file changed, 2 insertions(+) diff --git a/tests/Migration/Unit/Destinations/AppwriteDestinationDsnTest.php b/tests/Migration/Unit/Destinations/AppwriteDestinationDsnTest.php index e6e9e4d8f9..fa22151c17 100644 --- a/tests/Migration/Unit/Destinations/AppwriteDestinationDsnTest.php +++ b/tests/Migration/Unit/Destinations/AppwriteDestinationDsnTest.php @@ -71,6 +71,8 @@ class AppwriteDestinationDsnTest extends TestCase dbForProject: $this->createStub(UtopiaDatabase::class), getDatabasesDB: fn (UtopiaDocument $database): UtopiaDatabase => $this->createStub(UtopiaDatabase::class), collectionStructure: ['attributes' => [], 'indexes' => []], + dbForPlatform: $this->createStub(UtopiaDatabase::class), + projectInternalId: '1', onDuplicate: OnDuplicate::Fail, getDatabaseDSN: $getDatabaseDSN, ); From 052013a29a1cb5199b3330db975710579a5c40a3 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Wed, 13 May 2026 21:32:26 +0100 Subject: [PATCH 88/91] Paginate exportPlatforms via Project SDK service --- src/Migration/Sources/Appwrite.php | 68 +++++++++++++++++++----------- 1 file changed, 44 insertions(+), 24 deletions(-) diff --git a/src/Migration/Sources/Appwrite.php b/src/Migration/Sources/Appwrite.php index 2e245cf601..acf63c6669 100644 --- a/src/Migration/Sources/Appwrite.php +++ b/src/Migration/Sources/Appwrite.php @@ -7,6 +7,7 @@ use Appwrite\Client; use Appwrite\Query; use Appwrite\Services\Functions; use Appwrite\Services\Messaging; +use Appwrite\Services\Project; use Appwrite\Services\Sites; use Appwrite\Services\Storage; use Appwrite\Services\TablesDB; @@ -93,6 +94,8 @@ class Appwrite extends Source private Sites $sites; + private Project $projectService; + /** * @var callable(UtopiaDocument $database|null): UtopiaDatabase */ @@ -121,6 +124,7 @@ class Appwrite extends Source $this->functions = new Functions($this->client); $this->messaging = new Messaging($this->client); $this->sites = new Sites($this->client); + $this->projectService = new Project($this->client); $this->headers['x-appwrite-project'] = $this->project; $this->headers['x-appwrite-key'] = $this->key; @@ -2225,8 +2229,7 @@ class Appwrite extends Source { if (\in_array(Resource::TYPE_PLATFORM, $resources)) { try { - $response = $this->call('GET', '/projects/' . $this->project . '/platforms'); - $report[Resource::TYPE_PLATFORM] = $response['total'] ?? 0; + $report[Resource::TYPE_PLATFORM] = $this->projectService->listPlatforms([Query::limit(1)])->total; } catch (\Throwable) { $report[Resource::TYPE_PLATFORM] = 0; } @@ -2265,7 +2268,7 @@ class Appwrite extends Source { if (\in_array(Resource::TYPE_PLATFORM, $resources)) { try { - $this->exportPlatforms(); + $this->exportPlatforms($batchSize); } catch (\Throwable $e) { $this->addError(new Exception( Resource::TYPE_PLATFORM, @@ -2311,30 +2314,47 @@ class Appwrite extends Source /** * @throws AppwriteException */ - private function exportPlatforms(): void + private function exportPlatforms(int $batchSize): void { - $response = $this->call('GET', '/projects/' . $this->project . '/platforms'); + $lastId = null; - if (empty($response['platforms'])) { - return; + while (true) { + $queries = [Query::limit($batchSize)]; + + if ($lastId !== null) { + $queries[] = Query::cursorAfter($lastId); + } + + $response = $this->projectService->listPlatforms($queries); + if ($response->total === 0) { + break; + } + + $platforms = []; + + // SDK returns the raw platforms array (mixed PlatformWeb/Apple/Android/etc payloads), + // so we read the unified REST fields directly rather than via typed accessors. + foreach ($response->platforms as $platform) { + $platforms[] = new Platform( + $platform['$id'] ?? '', + $platform['type'] ?? '', + $platform['name'] ?? '', + $platform['key'] ?? '', + $platform['store'] ?? '', + $platform['hostname'] ?? '', + createdAt: $platform['$createdAt'] ?? '', + updatedAt: $platform['$updatedAt'] ?? '', + ); + + $lastId = $platform['$id'] ?? null; + } + + $this->callback($platforms); + + if (\count($response->platforms) < $batchSize) { + break; + } } - - $platforms = []; - - foreach ($response['platforms'] as $platform) { - $platforms[] = new Platform( - $platform['$id'] ?? '', - $platform['type'] ?? '', - $platform['name'] ?? '', - $platform['key'] ?? '', - $platform['store'] ?? '', - $platform['hostname'] ?? '', - createdAt: $platform['$createdAt'] ?? '', - updatedAt: $platform['$updatedAt'] ?? '', - ); - } - - $this->callback($platforms); } /** From c0a7d01de8343afc279ef652762406d218bdf733 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Thu, 14 May 2026 05:18:08 +0100 Subject: [PATCH 89/91] Drop null-safe operator on dbForPlatform; ctor type is non-nullable --- src/Migration/Destinations/Appwrite.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/Migration/Destinations/Appwrite.php b/src/Migration/Destinations/Appwrite.php index d176bf6034..36b60c0242 100644 --- a/src/Migration/Destinations/Appwrite.php +++ b/src/Migration/Destinations/Appwrite.php @@ -425,7 +425,7 @@ class Appwrite extends Destination try { $this->dbForProject->setPreserveDates(true); - $this->dbForPlatform?->setPreserveDates(true); + $this->dbForPlatform->setPreserveDates(true); $responseResource = match ($resource->getGroup()) { Transfer::GROUP_DATABASES => $this->importDatabaseResource($resource, $isLast), @@ -453,7 +453,7 @@ class Appwrite extends Destination $responseResource = $resource; } finally { $this->dbForProject->setPreserveDates(false); - $this->dbForPlatform?->setPreserveDates(false); + $this->dbForPlatform->setPreserveDates(false); } $this->cache->update($responseResource); From 4fc5fc3502bc15d6cfcfdde49e244e160ee2e3ed Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Thu, 14 May 2026 05:21:35 +0100 Subject: [PATCH 90/91] Use buildQueries in reportIntegrations to honor resourceIds filter --- src/Migration/Sources/Appwrite.php | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/src/Migration/Sources/Appwrite.php b/src/Migration/Sources/Appwrite.php index acf63c6669..3026767f51 100644 --- a/src/Migration/Sources/Appwrite.php +++ b/src/Migration/Sources/Appwrite.php @@ -2228,8 +2228,13 @@ class Appwrite extends Source private function reportIntegrations(array $resources, array &$report, array $resourceIds = []): void { if (\in_array(Resource::TYPE_PLATFORM, $resources)) { + $platformQueries = $this->buildQueries( + resourceType: Resource::TYPE_PLATFORM, + resourceIds: $resourceIds, + limit: 1 + ); try { - $report[Resource::TYPE_PLATFORM] = $this->projectService->listPlatforms([Query::limit(1)])->total; + $report[Resource::TYPE_PLATFORM] = $this->projectService->listPlatforms($platformQueries)->total; } catch (\Throwable) { $report[Resource::TYPE_PLATFORM] = 0; } From d7b51752dcf2b3cac632ec5847988191ecef9095 Mon Sep 17 00:00:00 2001 From: Prem Palanisamy Date: Thu, 14 May 2026 06:08:15 +0100 Subject: [PATCH 91/91] Apply rootResourceId/rootResourceType guard in exportPlatforms --- src/Migration/Sources/Appwrite.php | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/Migration/Sources/Appwrite.php b/src/Migration/Sources/Appwrite.php index 3026767f51..4b996baaff 100644 --- a/src/Migration/Sources/Appwrite.php +++ b/src/Migration/Sources/Appwrite.php @@ -2326,6 +2326,11 @@ class Appwrite extends Source while (true) { $queries = [Query::limit($batchSize)]; + if ($this->rootResourceId !== '' && $this->rootResourceType === Resource::TYPE_PLATFORM) { + $queries[] = Query::equal('$id', $this->rootResourceId); + $queries[] = Query::limit(1); + } + if ($lastId !== null) { $queries[] = Query::cursorAfter($lastId); }