Add more documentation for online_data_migrations CLI

This is a follow up to commit c4c6dc736 to clarify some
confusing comments in the code, add more comments in
the actual runtime code, and also provide an example
in the CLI man page docs along with an explanation of
the output, specifically for the case that $found>0
but done=0 and what that means.

Change-Id: I0691caab2c44d3189504c54e51bb263ecdc5d1d2
Related-Bug: #1794364
This commit is contained in:
Matt Riedemann 2018-09-27 14:53:10 -04:00
parent 835faf3f40
commit c86f309c56
2 changed files with 42 additions and 6 deletions

View File

@ -105,6 +105,36 @@ Nova Database
required to resolve the issue causing remaining updates to fail. It should be
considered successfully completed only when the exit status is 0.
For example::
$ nova-manage db online_data_migrations
Running batches of 50 until complete
2 rows matched query migrate_instances_add_request_spec, 0 migrated
2 rows matched query populate_queued_for_delete, 2 migrated
+---------------------------------------------+--------------+-----------+
| Migration | Total Needed | Completed |
+---------------------------------------------+--------------+-----------+
| create_incomplete_consumers | 0 | 0 |
| delete_build_requests_with_no_instance_uuid | 0 | 0 |
| migrate_instances_add_request_spec | 2 | 0 |
| migrate_keypairs_to_api_db | 0 | 0 |
| migrate_quota_classes_to_api_db | 0 | 0 |
| migrate_quota_limits_to_api_db | 0 | 0 |
| migration_migrate_to_uuid | 0 | 0 |
| populate_missing_availability_zones | 0 | 0 |
| populate_queued_for_delete | 2 | 2 |
| populate_uuids | 0 | 0 |
| service_uuids_online_data_migration | 0 | 0 |
+---------------------------------------------+--------------+-----------+
In the above example, the ``migrate_instances_add_request_spec`` migration
found two candidate records but did not need to perform any kind of data
migration for either of them. In the case of the
``populate_queued_for_delete`` migration, two candidate records were found
which did require a data migration. Since ``--max-count`` defaults to 50
and only two records were migrated with no more candidates remaining, the
command completed successfully with exit code 0.
``nova-manage db ironic_flavor_migration [--all] [--host] [--node] [--resource_class]``
Perform the ironic flavor migration process against the database
while services are offline. This is `not recommended` for most

View File

@ -377,15 +377,15 @@ class DbCommands(object):
# count, which is the maximum batch size requested by the
# user. They must be idempotent. At most $count records should be
# migrated. The function must return a tuple of (found, done). The
# found value indicates how many unmigrated records existed in the
# database prior to the migration (either total, or up to the
# $count limit provided), and a nonzero found value tells the user
# found value indicates how many unmigrated/candidate records existed in
# the database prior to the migration (either total, or up to the
# $count limit provided), and a nonzero found value may tell the user
# that there is still work to do. The done value indicates whether
# or not any records were actually migrated by the function. Thus
# if both (found, done) are nonzero, work was done and some work
# remains. If found is nonzero and done is zero, some records are
# not migratable, but all migrations that can complete have
# finished.
# not migratable (or don't need migrating), but all migrations that can
# complete have finished.
online_migrations = (
# Added in Newton
# TODO(mriedem): Remove this in Stein along with the compatibility
@ -692,6 +692,10 @@ Error: %s""") % six.text_type(e))
'migrated') % {'total': found,
'meth': name,
'done': done})
# This is the per-migration method result for this batch, and
# _run_migration will either continue on to the next migration,
# or stop if up to this point we've processed max_count of
# records across all migration methods.
migrations[name] = found, done
if max_count is not None:
ran += done
@ -723,6 +727,8 @@ Error: %s""") % six.text_type(e))
while ran is None or ran != 0:
migrations, exceptions = self._run_migration(ctxt, max_count)
ran = 0
# For each batch of migration method results, build the cumulative
# set of results.
for name in migrations:
migration_info.setdefault(name, (0, 0))
migration_info[name] = (
@ -734,7 +740,7 @@ Error: %s""") % six.text_type(e))
break
t = prettytable.PrettyTable([_('Migration'),
_('Total Needed'),
_('Total Needed'), # Really: Total Found
_('Completed')])
for name in sorted(migration_info.keys()):
info = migration_info[name]