From e09ef30d879daa00895098d0fca2a2a58065292b Mon Sep 17 00:00:00 2001 From: Peter Cock Date: Thu, 7 Nov 2024 09:51:22 -0500 Subject: [PATCH] Clarify what autogenerate compares ### Description I was struggling with empty upgrade/downgrade functions because both my database and my ORM were up to date. I wrongly assumed the comparison was against the previous database scheme as per the prior revision script(s). ### Checklist This pull request is: - [x] A documentation / typographical error fix - Good to go, no issue or tests are needed - [ ] A short code fix - please include the issue number, and create an issue if none exists, which must include a complete example of the issue. one line code fixes without an issue and demonstration will not be accepted. - Please include: `Fixes: #` in the commit message - please include tests. one line code fixes without tests will not be accepted. - [ ] A new feature implementation - please include the issue number, and create an issue if none exists, which must include a complete example of how the feature would look. - Please include: `Fixes: #` in the commit message - please include tests. **Have a nice day!** Closes: #1570 Pull-request: https://github.com/sqlalchemy/alembic/pull/1570 Pull-request-sha: dec968b136a813d27e1d2bca04574a2399343a1a Change-Id: I04dadc3c3d26ad000aca499208d8024cd63eec40 --- docs/build/autogenerate.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/build/autogenerate.rst b/docs/build/autogenerate.rst index 519aa5bc..c7641fe4 100644 --- a/docs/build/autogenerate.rst +++ b/docs/build/autogenerate.rst @@ -1,10 +1,12 @@ Auto Generating Migrations =========================== -Alembic can view the status of the database and compare against the table metadata -in the application, generating the "obvious" migrations based on a comparison. This -is achieved using the ``--autogenerate`` option to the ``alembic revision`` command, -which places so-called *candidate* migrations into our new migrations file. We +Alembic can view the status of the database (pointed to by ``sqlalchemy.url`` in +your ``alemic.ini`` file using the *current* schema) and compare against the +table metadata in the application (your ORM which defines the *proposed* schema), +generating the "obvious" migrations based on a comparison. This is achieved +using the ``--autogenerate`` option to the ``alembic revision`` command, which +places so-called *candidate* migrations into our new migrations file. We review and modify these by hand as needed, then proceed normally. To use autogenerate, we first need to modify our ``env.py`` so that it gets access