add check command for upgrade diffs

Added new Alembic command ``alembic check``. This performs the widely
requested feature of running an "autogenerate" comparison between the
current database and the :class:`.MetaData` that's currently set up for
autogenerate, returning an error code if the two do not match, based on
current autogenerate settings. Pull request courtesy Nathan Louie.

As this is a new feature we will call this 1.9.0

Fixes: #724
Closes: #1101
Pull-request: https://github.com/sqlalchemy/alembic/pull/1101
Pull-request-sha: 807ed545df70e7a10b913e2951a1b636f138a4ff

Change-Id: I03b146eaf762be464a0ff0858ff5730cc9366c84

3 files changed, 57 insertions, 1 deletions

diff --git a/docs/build/autogenerate.rst b/docs/build/autogenerate.rst
index a623372..4cb8006 100644
--- a/docs/build/autogenerate.rst
+++ b/docs/build/autogenerate.rst
@@ -886,3 +886,45 @@ be run against the newly generated file path::
     Generating /path/to/project/versions/481b13bc369a_rev1.py ... done
     Running post write hook "spaces_to_tabs" ...
     done
+
+.. _alembic_check:
+
+Running Alembic Check to test for new upgrade operations
+--------------------------------------------------------
+
+When developing code it's useful to know if a set of code changes has made any
+net change to the database model, such that new revisions would need to be
+generated. To automate this, Alembic provides the ``alembic check`` command.
+This command will run through the same process as
+``alembic revision --autogenerate``, up until the point where revision files
+would be generated, however does not generate any new files. Instead, it
+returns an error code plus a message if it is detected that new operations
+would be rendered into a new revision, or if not, returns a success code plus a
+message.   When ``alembic check`` returns a success code, this is an indication
+that the ``alembic revision --autogenerate`` command would produce only empty
+migrations, and does not need to be run.
+
+``alembic check`` can be worked into CI systems and on-commit schemes to ensure
+that incoming code does not warrant new revisions to be generated.  In
+the example below, a check that detects new operations is illustrated::
+
+
+    $ alembic check
+    FAILED: New upgrade operations detected: [
+      ('add_column', None, 'my_table', Column('data', String(), table=<my_table>)),
+      ('add_column', None, 'my_table', Column('newcol', Integer(), table=<my_table>))]
+
+by contrast, when no new operations are detected::
+
+    $ alembic check
+    No new upgrade operations detected.
+
+
+.. versionadded:: 1.9.0
+
+.. note::  The ``alembic check`` command uses the same model comparison process
+   as the ``alembic revision --autogenerate`` process.  This means parameters
+   such as :paramref:`.EnvironmentContext.configure.compare_type`
+   and :paramref:`.EnvironmentContext.configure.compare_server_default`
+   are in play as usual, as well as that limitations in autogenerate
+   detection are the same when running ``alembic check``.
\ No newline at end of file
diff --git a/docs/build/changelog.rst b/docs/build/changelog.rst
index f88978a..178a2a2 100644
--- a/docs/build/changelog.rst
+++ b/docs/build/changelog.rst
@@ -4,7 +4,7 @@ Changelog
 ==========
 
 .. changelog::
-    :version: 1.8.2
+    :version: 1.9.0
     :include_notes_from: unreleased
 
 .. changelog::
diff --git a/docs/build/unreleased/724.rst b/docs/build/unreleased/724.rst
new file mode 100644
index 0000000..5bd1987
--- /dev/null
+++ b/docs/build/unreleased/724.rst
@@ -0,0 +1,14 @@
+.. change::
+    :tags: feature, commands
+    :tickets: 724
+
+    Added new Alembic command ``alembic check``. This performs the widely
+    requested feature of running an "autogenerate" comparison between the
+    current database and the :class:`.MetaData` that's currently set up for
+    autogenerate, returning an error code if the two do not match, based on
+    current autogenerate settings. Pull request courtesy Nathan Louie.
+
+    .. seealso::
+
+        :ref:`alembic_check`
+