Add emphasis to URL documentation re: URL encoding

Fixes: #5715
Change-Id: I2ac16541d34f49b25070e00c43596bcd71aff72d

1 files changed, 7 insertions, 2 deletions

diff --git a/lib/sqlalchemy/engine/create.py b/lib/sqlalchemy/engine/create.py
index dd732a09a..381e0879d 100644
--- a/lib/sqlalchemy/engine/create.py
+++ b/lib/sqlalchemy/engine/create.py
@@ -45,13 +45,18 @@ from ..sql import compiler
 def create_engine(url, **kwargs):
     """Create a new :class:`_engine.Engine` instance.
 
-    The standard calling form is to send the URL as the
+    The standard calling form is to send the :ref:`URL <database_urls>` as the
     first positional argument, usually a string
     that indicates database dialect and connection arguments::
 
-
         engine = create_engine("postgresql://scott:tiger@localhost/test")
 
+    .. note::
+
+        Please review :ref:`database_urls` for general guidelines in composing
+        URL strings.  In particular, special characters, such as those often
+        part of passwords, must be URL encoded to be properly parsed.
+
     Additional keyword arguments may then follow it which
     establish various options on the resulting :class:`_engine.Engine`
     and its underlying :class:`.Dialect` and :class:`_pool.Pool`