diff --git a/src/docs/user/configuration/storage_adjust.diviner b/src/docs/user/configuration/storage_adjust.diviner --- a/src/docs/user/configuration/storage_adjust.diviner +++ b/src/docs/user/configuration/storage_adjust.diviner @@ -118,7 +118,7 @@ Troubleshooting =============== -When you apply adjustments, some adjustments may fail. The two most common +When you apply adjustments, some adjustments may fail. Some of the most common errors you may encounter are: - **#1406 Data Too Long**: Usually this is caused by a very long object name @@ -145,3 +145,47 @@ adjustments, it is safe to file a task in the upstream describing the problem you've encountered and continue using Phabricator normally until the issue can be resolved. + +Surplus Schemata +================ + +After performing adjustment, you may receive an error that a table or column is +"Surplus". The error looks something like this: + +| Target | Error | +| --- | --- | +| phabricator_example.example_table | Surplus | + +Generally, "Surplus" means that Phabricator does not expect the table or column +to exist. These surpluses usually exist because you (or someone else +with database access) added the table or column manually. Rarely, they can +also exist for other reasons. They are usually safe to delete, but because +deleting them destroys data and Phabricator can not be sure that the table or +column doesn't have anything important in it, it does not delete them +automatically. + +If you recognize the schema causing the issue as something you added and you +don't need it anymore, you can safely delete it. If you aren't sure whether +you added it or not, you can move the data somewhere else and delete it later. + +To move a table, first create a database for it like `my_backups`. Then, rename +the table to move it into that database (use the table name given in the error +message): + +```lang=sql +CREATE DATABASE my_backups; +RENAME TABLE phabricator_example.example_table + TO my_backups.example_table; +``` + +Phabricator will ignore tables that aren't in databases it owns, so you can +safely move anything you aren't sure about outside of the Phabricator databases. + +If you're sure you don't need a table, use `DROP TABLE` to destroy it, +specifying the correct table name (the one given in the error message): + +```lang=sql +DROP TABLE phabricator_example.example_table; +``` + +This will destroy the table permanently. diff --git a/src/infrastructure/storage/management/workflow/PhabricatorStorageManagementWorkflow.php b/src/infrastructure/storage/management/workflow/PhabricatorStorageManagementWorkflow.php --- a/src/infrastructure/storage/management/workflow/PhabricatorStorageManagementWorkflow.php +++ b/src/infrastructure/storage/management/workflow/PhabricatorStorageManagementWorkflow.php @@ -595,6 +595,8 @@ ->addColumn('target', array('title' => pht('Target'))) ->addColumn('error', array('title' => pht('Error'))); + $any_surplus = false; + $all_surplus = true; foreach ($errors as $error) { $pieces = array_select_keys( $error, @@ -604,6 +606,12 @@ $name = PhabricatorConfigStorageSchema::getIssueName($error['issue']); + if ($error['issue'] === PhabricatorConfigStorageSchema::ISSUE_SURPLUS) { + $any_surplus = true; + } else { + $all_surplus = false; + } + $table->addRow( array( 'target' => $target, @@ -615,19 +623,50 @@ $table->draw(); $console->writeOut("\n"); - $message = pht( - "The schemata have serious errors (detailed above) which the adjustment ". - "workflow can not fix.\n\n". - "If you are not developing Phabricator itself, report this issue to ". - "the upstream.\n\n". - "If you are developing Phabricator, these errors usually indicate that ". - "your schema specifications do not agree with the schemata your code ". - "actually builds."); - $console->writeOut( - "** %s **\n\n%s\n", - pht('SCHEMATA ERRORS'), - phutil_console_wrap($message)); + $message = array(); + if ($all_surplus) { + $message[] = pht( + 'You have surplus schemata (extra tables or columns which Phabricator '. + 'does not expect). For information on resolving these '. + 'issues, see the "Surplus Schemata" section in the "Managing Storage '. + 'Adjustments" article in the documentation.'); + } else { + $message[] = pht( + 'The schemata have errors (detailed above) which the adjustment '. + 'workflow can not fix.'); + + if ($any_surplus) { + $message[] = pht( + 'Some of these errors are caused by surplus schemata (extra '. + 'tables or columsn which Phabricator does not expect). These are '. + 'not serious. For information on resolving these issues, see the '. + '"Surplus Schemata" section in the "Managing Storage Adjustments" '. + 'article in the documentation.'); + } + + $message[] = pht( + 'If you are not developing Phabricator itself, report this issue to '. + 'the upstream.'); + + $message[] = pht( + 'If you are developing Phabricator, these errors usually indicate '. + 'that your schema specifications do not agree with the schemata your '. + 'code actually builds.'); + } + $message = implode("\n\n", $message); + + if ($all_surplus) { + $console->writeOut( + "** %s **\n\n%s\n", + pht('SURPLUS SCHEMATA'), + phutil_console_wrap($message)); + } else { + $console->writeOut( + "** %s **\n\n%s\n", + pht('SCHEMATA ERRORS'), + phutil_console_wrap($message)); + } return 2; }