diff --git a/docs/codeql/codeql-cli/analyzing-databases-with-the-codeql-cli.rst b/docs/codeql/codeql-cli/analyzing-databases-with-the-codeql-cli.rst
index 209b8877098..7a47b98032d 100644
--- a/docs/codeql/codeql-cli/analyzing-databases-with-the-codeql-cli.rst
+++ b/docs/codeql/codeql-cli/analyzing-databases-with-the-codeql-cli.rst
@@ -36,6 +36,7 @@ You can analyze a database by running the following command::
 
    codeql database analyze <database> --format=<format> --output=<output> <queries>
 
+
 You must specify:
 
 - ``<database>``: the path to the CodeQL database you want to analyze.
@@ -79,6 +80,21 @@ You can also specify:
 
 - .. include:: ../reusables/threads-query-execution.rst
 
+. pull-quote::
+
+   Upgrading databases
+
+   For databases that were creaated by CodeQL CLI v2.3.3 or earlier, you will need
+   to explicitly upgrade the database before you can run an analysis with a newer
+   version of the CodeQL CLI. If this step is necessary, then you will see a message telling you
+   that your database needs to be upgraded when you run ``database analyze``.
+
+   CodeQL databases are upgraded by running the following command::
+
+       codeql database upgrade <database>
+
+   For full details of all the options you can use when upgrading databases,
+   see the "`database upgrade <../manual/database-upgrade>`__"  reference documentation.
 
 For full details of all the options you can use when analyzing databases, see
 the `database analyze reference documentation <../manual/database-analyze>`__.