Merge "Clarify --before help text in nova manage"

doc/source/cli/nova-manage.rst

@@ -69,7 +69,7 @@ Nova Database
     deleted rows are archived. Use the ``--max_rows`` option, which defaults to
     1000, as a batch size for each iteration (note that the purged API database
     table records are not included in this batch size). Specifying ``--before``
-    will archive only instances that were deleted before the date provided, and
+    will archive only instances that were deleted before the date_ provided, and
     records in other tables related to those instances. Specifying ``--purge``
     will cause a `full` DB purge to be completed after archival. If a date
     range is desired for the purge, then run ``nova-manage db purge --before
@@ -78,12 +78,12 @@ Nova Database
 ``nova-manage db purge [--all] [--before <date>] [--verbose] [--all-cells]``
     Delete rows from shadow tables. Specifying ``--all`` will delete all data from
     all shadow tables. Specifying ``--before`` will delete data from all shadow tables
-    that is older than the date provided. Date strings may be fuzzy, such as
+    that is older than the date_ provided. Specifying ``--verbose`` will
-    ``Oct 21 2015``. Specifying ``--verbose`` will cause information to be printed about
+    cause information to be printed about purged records. Specifying
-    purged records. Specifying ``--all-cells`` will cause the purge to be applied against
+    ``--all-cells`` will cause the purge to be applied against all cell databases.
-    all cell databases. For ``--all-cells`` to work, the api database connection
+    For ``--all-cells`` to work, the api database connection information must
-    information must be configured. Returns exit code 0 if rows were deleted, 1 if
+    be configured. Returns exit code 0 if rows were deleted, 1 if required
-    required arguments are not provided, 2 if an invalid date is provided, 3 if no
+    arguments are not provided, 2 if an invalid date is provided, 3 if no
     data was deleted, 4 if the list of cells cannot be obtained.
 
 ``nova-manage db null_instance_uuid_scan [--delete]``
@@ -163,6 +163,27 @@ Nova Database
    the work done is non-trivial. Running smaller and more targeted batches (such as
    specific nodes) is recommended.
 
+.. _date:
+
+``--before <date>``
+   The date argument accepted by the ``--before`` option can be in any
+   of several formats, including ``YYYY-MM-DD [HH:mm[:ss]]`` and the default
+   format produced by the ``date`` command, e.g. ``Fri May 24 09:20:11 CDT 2019``.
+   Date strings containing spaces must be quoted appropriately. Some examples::
+
+     # Purge shadow table rows older than a specific date
+     nova-manage db purge --before 2015-10-21
+     # or
+     nova-manage db purge --before "Oct 21 2015"
+     # Times are also accepted
+     nova-manage db purge --before "2015-10-21 12:00"
+
+   Note that relative dates (such as ``yesterday``) are not supported natively.
+   The ``date`` command can be helpful here::
+
+     # Archive deleted rows more than one month old
+     nova-manage db archive_deleted_rows --before "$(date -d 'now - 1 month')"
+
 Nova API Database
 ~~~~~~~~~~~~~~~~~
 

nova/cmd/manage.py

@@ -488,8 +488,9 @@ Error: %s""") % six.text_type(e))
                'rows, if any, that are removed from the API database for '
                'deleted instances.')
     @args('--before', metavar='<date>',
-          help=('Archive rows that have been deleted before this date'
+          help=('Archive rows that have been deleted before this date. '
-                '(YYYY-MM-DD)'))
+                'Accepts date strings in the default format output by the '
+                '``date`` command, as well as ``YYYY-MM-DD [HH:mm:ss]``.'))
     @args('--verbose', action='store_true', dest='verbose', default=False,
           help='Print how many rows were archived per table.')
     @args('--until-complete', action='store_true', dest='until_complete',
@@ -596,7 +597,9 @@ Error: %s""") % six.text_type(e))
 
     @args('--before', metavar='<before>', dest='before',
           help='If specified, purge rows from shadow tables that are older '
-               'than this. Fuzzy time specs are allowed')
+               'than this. Accepts date strings in the default format output '
+               'by the ``date`` command, as well as ``YYYY-MM-DD '
+               '[HH:mm:ss]``.')
     @args('--all', dest='purge_all', action='store_true',
           help='Purge all rows in the shadow tables')
     @args('--verbose', dest='verbose', action='store_true', default=False,