From add50195743e1f7a2fa45d0e5fcfd633201e33d0 Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Thu, 3 Oct 2019 11:43:38 -0400 Subject: [PATCH] Clarify sqlalchemy.url in tutorial.rst Change-Id: Idf47390d132424a2a1998bbe73371d4cce9ce4f3 Fixes: #606 --- docs/build/tutorial.rst | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/docs/build/tutorial.rst b/docs/build/tutorial.rst index f3d513cd..d423842f 100644 --- a/docs/build/tutorial.rst +++ b/docs/build/tutorial.rst @@ -252,11 +252,18 @@ This file contains the following features: .. versionadded:: 0.6.1 - added ``truncate_slug_length`` configuration -* ``sqlalchemy.url`` - A URL to connect to the database via SQLAlchemy. This key is in fact - only referenced within the ``env.py`` file that is specific to the "generic" configuration; - a file that can be customized by the developer. A multiple - database configuration may respond to multiple keys here, or may reference other sections - of the file. +* ``sqlalchemy.url`` - A URL to connect to the database via SQLAlchemy. This + configuration value is only used if the ``env.py`` file calls upon them; + in the "generic" template, the call to + ``config.get_main_option("sqlalchemy.url")`` in the + ``run_migrations_offline()`` function and the call to + ``engine_from_config(prefix="sqlalchemy.")`` in the + ``run_migrations_online()`` function are where this key is referenced. If + the SQLAlchemy URL should come from some other source, such as from + environment variables or a global registry, or if the migration environment + makes use of multiple database URLs, the developer is encouraged to alter the + ``env.py`` file to use whatever methods are appropriate in order to acquire + the database URL or URLs. * ``revision_environment`` - this is a flag which when set to the value 'true', will indicate that the migration environment script ``env.py`` should be run unconditionally when -- 2.47.2