Plugin install migration suggestion failures

Description

I was adding a semi-clone of a well-toasted plugin to scaffold something related. In the course of this I deinstalled the earlier plugin, and then it wouldn't install.

The problems boiled down to this, from your suggested Install migration code here

• the query at the top will always return a supposed rowid, at least on my untouched Homestead-Vagrant MySql configuration. What it actually returns is the next Autoincrement number, which had no row, after which trouble ensues. I think this is probably related to the obscure sql_auto_is_null directive, though this is not the specified action of that.

Here is a substitute that works, avoiding the issue:

        // Fetch the old plugin row, if it was installed
        $row = (new \craft\db\Query())
            ->select(['id', 'settings'])
            ->from(['{{%plugins}}'])
            ->where(['in', 'handle', ['standards-agent', 'StandardsAgent']])
            ->andWhere(['not', ['settings' => null]])
            ->one();

• Ok, and then the code following this for the true return of a row doesn't seem to make good sense, and also causes failure. Why would you delete the row, if you've just updated it? I've just commented the delete out.

I presume either that what's there depends on some unusual behavior of update making an insertion ??) but that would also depend on this undocumentable return of a faux record with the autoincremented id in it. But the row id would be wrong for any game like that, and I don't think you play those at P&T, except maybe with a comment.

• last is the question of where your 'Update' code should go. There needs to be an else case for when there wasn't a row in the plugins table, as that's where you'd install tables for a fresh Install under C3. Update means only update, like adding columns or the like. This code example would be a lot clearer if you show that part....

Steps to reproduce

1. Well, the way I ran into this was to uninstall an actually ok, big, C3 plugin -- and then couldn't re-install it.
2. the error messages around safeUp and safeDown are not going to help a bit - they just say Fail, without giving any information. Maybe that's desirable for a plugin? But not heartening, forthe customer who has to call you about it?
3. no fair mentioning to anyone what you might glean from fresh plugin's name...

Additional info

PHP version 7.1.7-1+ubuntu16.04.1+deb.sury.org+1
Database driver & version MySQL 5.7.19-0ubuntu0.16.04.1
Image driver & version GD 7.1.7-1+ubuntu16.04.1+deb.sury.org+1
Craft edition & version Craft Personal 3.0.0-beta.23 to the moment's dev-develop
Yii version 2.0.12
Twig version 2.3.2
Guzzle version 6.2.1
Imagine version 0.7-dev
Plugins

Trimmer 1.0.0
Bactrian 1.0.0
Craft Rabbit 2.0.1
Standards Agent 2.0.1

Read en/updating-plugins.md at the “Setting it Up” section and review the plugin migration example against the reported MySQL behavior. Clarify the existing-row and fresh-install paths, and ensure the documented example’s query and follow-up operations match their intended behavior. Done means the migration guidance is internally consistent and addresses the reported reinstall failure.