From 3284fa4058b406b0f824ee6f1fcaaffd9fa746be Mon Sep 17 00:00:00 2001 From: Josh Date: Wed, 1 Jul 2026 17:13:40 -0400 Subject: [PATCH 1/3] docs(db): document MigrationService::createMigrationTable Signed-off-by: Josh --- lib/private/DB/MigrationService.php | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/lib/private/DB/MigrationService.php b/lib/private/DB/MigrationService.php index a0cb407a94d84..0152fca22ad34 100644 --- a/lib/private/DB/MigrationService.php +++ b/lib/private/DB/MigrationService.php @@ -94,7 +94,12 @@ public function getApp(): string { } /** - * @codeCoverageIgnore - this will implicitly tested on installation + * Ensures the `migrations` table exists with the expected schema. + * + * Creates the table if missing, or recreates it if the existing one is incompatible. + * + * @return bool True if the table was created or recreated; false otherwise. + * @codeCoverageIgnore This is exercised implicitly during installation. */ private function createMigrationTable(): bool { if ($this->migrationTableCreated) { @@ -109,8 +114,9 @@ private function createMigrationTable(): bool { $schema = new SchemaWrapper($this->connection); /** - * We drop the table when it has different columns or the definition does not - * match. E.g. ownCloud uses a length of 177 for app and 14 for version. + * Recreate the `migrations` table when the existing schema is incompatible. + * For example, older ownCloud installations used shorter column lengths + * for `app` (177) and `version` (14). */ try { $table = $schema->getTable('migrations'); @@ -131,19 +137,19 @@ private function createMigrationTable(): bool { } if (!$schemaMismatch) { - // Table exists and schema matches: return back! + // The existing table matches the expected schema; nothing to do. $this->migrationTableCreated = true; return false; } } - // Drop the table, when it didn't match our expectations. + // Drop the table because it does not match the expected schema. $this->connection->dropTable('migrations'); - // Recreate the schema after the table was dropped. + // Recreate the schema wrapper after dropping the table. $schema = new SchemaWrapper($this->connection); } catch (SchemaException $e) { - // Table not found, no need to panic, we will create it. + // The table does not exist; it will be created below. } $table = $schema->createTable('migrations'); From 125a25eaeb5b0202f3919ca6b7ae5886fe52d334 Mon Sep 17 00:00:00 2001 From: Josh Date: Wed, 1 Jul 2026 18:08:51 -0400 Subject: [PATCH 2/3] perf(db): drop redundant db-side migrations version sorting Signed-off-by: Josh --- lib/private/DB/MigrationService.php | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/lib/private/DB/MigrationService.php b/lib/private/DB/MigrationService.php index 0152fca22ad34..112cec21d767c 100644 --- a/lib/private/DB/MigrationService.php +++ b/lib/private/DB/MigrationService.php @@ -170,14 +170,13 @@ private function createMigrationTable(): bool { * @return list * @codeCoverageIgnore - no need to test this */ - public function getMigratedVersions() { + public function getMigratedVersions(): array { $this->createMigrationTable(); $qb = $this->connection->getQueryBuilder(); $qb->select('version') ->from('migrations') - ->where($qb->expr()->eq('app', $qb->createNamedParameter($this->getApp()))) - ->orderBy('version'); + ->where($qb->expr()->eq('app', $qb->createNamedParameter($this->getApp()))); $result = $qb->executeQuery(); $rows = $result->fetchAll(\PDO::FETCH_COLUMN); From 3574952e4f893d0def132748fc9dd6a11bfaba8e Mon Sep 17 00:00:00 2001 From: Josh Date: Wed, 1 Jul 2026 18:13:14 -0400 Subject: [PATCH 3/3] refactor(db): add missing typing to MigrationService Signed-off-by: Josh --- lib/private/DB/MigrationService.php | 26 ++++++++------------------ 1 file changed, 8 insertions(+), 18 deletions(-) diff --git a/lib/private/DB/MigrationService.php b/lib/private/DB/MigrationService.php index 112cec21d767c..7166c6da23472 100644 --- a/lib/private/DB/MigrationService.php +++ b/lib/private/DB/MigrationService.php @@ -252,7 +252,7 @@ protected function findMigrations(): array { * @param string $to * @return string[] */ - private function getMigrationsToExecute($to) { + private function getMigrationsToExecute($to): array { $knownMigrations = $this->getMigratedVersions(); $availableMigrations = $this->getAvailableVersions(); @@ -274,7 +274,7 @@ private function getMigrationsToExecute($to) { * @param string[] $knownMigrations * @return bool */ - private function shallBeExecuted($m, $knownMigrations) { + private function shallBeExecuted($m, $knownMigrations): bool { if (in_array($m, $knownMigrations)) { return false; } @@ -294,28 +294,22 @@ private function markAsExecuted($version): void { /** * Returns the name of the table which holds the already applied versions - * - * @return string */ - public function getMigrationsTableName() { + public function getMigrationsTableName(): string { return $this->connection->getPrefix() . 'migrations'; } /** * Returns the namespace of the version classes - * - * @return string */ - public function getMigrationsNamespace() { + public function getMigrationsNamespace(): string { return $this->migrationsNamespace; } /** * Returns the directory which holds the versions - * - * @return string */ - public function getMigrationsDirectory() { + public function getMigrationsDirectory(): string { return $this->migrationsPath; } @@ -457,7 +451,7 @@ public function migrateSchemaOnly(string $to = 'latest'): void { * @param string $to * @return string[] [$name => $description] */ - public function describeMigrationStep($to = 'latest') { + public function describeMigrationStep(string $to = 'latest'): array { $toBeExecuted = $this->getMigrationsToExecute($to); $description = []; foreach ($toBeExecuted as $version) { @@ -470,11 +464,9 @@ public function describeMigrationStep($to = 'latest') { } /** - * @param string $version - * @return IMigrationStep * @throws \InvalidArgumentException */ - public function createInstance($version) { + public function createInstance(string $version): IMigrationStep { /** @psalm-var class-string $class */ $class = $this->getClass($version); try { @@ -496,11 +488,9 @@ public function createInstance($version) { /** * Executes one explicit version * - * @param string $version - * @param bool $schemaOnly * @throws \InvalidArgumentException */ - public function executeStep($version, $schemaOnly = false): void { + public function executeStep(string $version, bool $schemaOnly = false): void { $instance = $this->createInstance($version); if (!$schemaOnly) {