Improve SQL Server pyodbc documentation

While we were told years ago that ODBC is intended to be used with
DSNs only, however this use does not correspond well with how most
other database connectivity systems work in that modern systems
already have their own registries of connection information in any
case, meaning this is usually the best place to add details such
as hostnames and driver names, rather than having them locked away
in a server-specific ODBC registry.    So here we dial back the
language that one style or another of connecting is "preferred";
both styles are supported equally, and the critical advantage of
hostname mapping in that the target database name is both explicit
as well as modifyable is also added.

Add additional background for how DSNs work and refine other
sentences.   "URL encoding" is the correct terminology for
adding spaces and special characters to a URL.

Change-Id: I13a74432976e6d3166633b98f9bb84c4856caac8
(cherry picked from commit 65466dec6346ad84340af1cf3e431020add0f9a5)
(cherry picked from commit e2dc03ff0983a36ce132733b6a1f82ec3ee344da)

diff --git a/lib/sqlalchemy/dialects/mssql/pyodbc.py b/lib/sqlalchemy/dialects/mssql/pyodbc.py
index 98b7cad320a932ef9ac7c0c735fa795e11c585cd..3e9b140708ff806125c19b8ab45c0c67ede394ce 100644 (file)
--- a/lib/sqlalchemy/dialects/mssql/pyodbc.py
+++ b/lib/sqlalchemy/dialects/mssql/pyodbc.py
@@ -21,8 +21,11 @@ detailed in `ConnectionStrings <https://code.google.com/p/pyodbc/wiki/Connection
 DSN Connections
 ^^^^^^^^^^^^^^^
 
-A DSN-based connection is **preferred** overall when using ODBC.  A
-basic DSN-based connection looks like::
+A DSN connection in ODBC means that a pre-existing ODBC datasource is
+configured on the client machine.   The application then specifies the name
+of this datasource, which encompasses details such as the specific ODBC driver
+in use as well as the network address of the database.   Assuming a datasource
+is configured on the client, a basic DSN-based connection looks like::
 
     engine = create_engine("mssql+pyodbc://scott:tiger@some_dsn")
 
@@ -36,15 +39,16 @@ the ``Trusted_Connection=yes`` directive to the ODBC string.
 Hostname Connections
 ^^^^^^^^^^^^^^^^^^^^
 
-Hostname-based connections are **not preferred**, however are supported.
-The ODBC driver name must be explicitly specified::
+Hostname-based connections are also supported by pyodbc.  These are often
+easier to use than a DSN and have the additional advantage that the specific
+database name to connect towards may be specified locally in the URL, rather
+than it being fixed as part of a datasource configuration.
 
-    engine = create_engine("mssql+pyodbc://scott:tiger@myhost:port/databasename?driver=SQL+Server+Native+Client+10.0")
+When using a hostname connection, the driver name must also be specified in the
+query parameters of the URL.  As these names usually have spaces in them, the
+name must be URL encoded which means using plus signs for spaces::
 
-.. versionchanged:: 1.0.0 Hostname-based PyODBC connections now require the
-   SQL Server driver name specified explicitly.  SQLAlchemy cannot
-   choose an optimal default here as it varies based on platform
-   and installed drivers.
+    engine = create_engine("mssql+pyodbc://scott:tiger@myhost:port/databasename?driver=SQL+Server+Native+Client+10.0")
 
 Other keywords interpreted by the Pyodbc dialect to be passed to
 ``pyodbc.connect()`` in both the DSN and hostname cases include:
@@ -53,10 +57,11 @@ Other keywords interpreted by the Pyodbc dialect to be passed to
 Pass through exact Pyodbc string
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-A PyODBC connection string can also be sent exactly as specified in
-`ConnectionStrings <https://code.google.com/p/pyodbc/wiki/ConnectionStrings>`_
-into the driver using the parameter ``odbc_connect``.  The delimeters must be URL escaped, however,
-as illustrated below using ``urllib.quote_plus``::
+A PyODBC connection string can also be sent in pyodbc's format directly, as
+specified in `ConnectionStrings
+<https://code.google.com/p/pyodbc/wiki/ConnectionStrings>`_ into the driver
+using the parameter ``odbc_connect``.  The delimeters must be URL encoded, as
+illustrated below using ``urllib.parse.quote_plus``::
 
     import urllib
     params = urllib.quote_plus("DRIVER={SQL Server Native Client 10.0};SERVER=dagger;DATABASE=test;UID=user;PWD=password")