From: Mike Bayer Date: Tue, 21 Mar 2023 17:40:36 +0000 (-0400) Subject: add tip that reflection is not necessary for an existing database X-Git-Tag: rel_1_4_48~7 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=1a7f56a1bd2c583577159343327b04a49e8f57fb;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git add tip that reflection is not necessary for an existing database a new user spent many days misled by this paragraph thinking they were required to use reflection for an existing database. Change-Id: I4c6757b931481db7a8d4202334382143e1491935 (cherry picked from commit 42b3b80fae8d7b808125efc1dd9a900231c2ed21) --- diff --git a/doc/build/tutorial/metadata.rst b/doc/build/tutorial/metadata.rst index 215d9fd8b8..df3b336f45 100644 --- a/doc/build/tutorial/metadata.rst +++ b/doc/build/tutorial/metadata.rst @@ -498,8 +498,19 @@ another operation that was mentioned at the beginning of the section, that of **table reflection**. Table reflection refers to the process of generating :class:`_schema.Table` and related objects by reading the current state of a database. Whereas in the previous sections we've been declaring -:class:`_schema.Table` objects in Python and then emitting DDL to the database, -the reflection process does it in reverse. +:class:`_schema.Table` objects in Python, where we then have the option +to emit DDL to the database to generate such a schema, the reflection process +does these two steps in reverse, starting from an existing database +and generating in-Python data structures to represent the schemas within +that database. + +.. tip:: There is no requirement that reflection must be used in order to + use SQLAlchemy with a pre-existing database. It is entirely typical that + the SQLAlchemy application declares all metadata explicitly in Python, + such that its structure corresponds to that the existing database. + The metadata structure also need not include tables, columns, or other + constraints and constructs in the pre-existing database that are not needed + for the local application to function. As an example of reflection, we will create a new :class:`_schema.Table` object which represents the ``some_table`` object we created manually in