- break out sample URLs into individual, per-database sections each with a link

to the dialect page.
- add a section for unix domain sockets under psycopg2 [ticket:2393]

diff --git a/doc/build/core/engines.rst b/doc/build/core/engines.rst
index 7e315c1a7422db5c81e72888a8ab7cf4e5a3883b..c4a0b9af4e3ae917e6b8b2f6e22cc188dbd22d04 100644 (file)
--- a/doc/build/core/engines.rst
+++ b/doc/build/core/engines.rst
@@ -169,38 +169,63 @@ known driver available for that backend (i.e. cx_oracle, pysqlite/sqlite3,
 psycopg2, mysqldb). For Jython connections, specify the `zxjdbc` driver, which
 is the JDBC-DBAPI bridge included with Jython.
 
-.. sourcecode:: python+sql
+Postgresql
+----------
+
+The Postgresql dialect uses psycopg2 as the default DBAPI::
+
+    # default
+    engine = create_engine('postgresql://scott:tiger@localhost/mydatabase')
+
+    # psycopg2
+    engine = create_engine('postgresql+psycopg2://scott:tiger@localhost/mydatabase')
+
+    # pg8000
+    engine = create_engine('postgresql+pg8000://scott:tiger@localhost/mydatabase')
+
+    # Jython
+    engine = create_engine('postgresql+zxjdbc://scott:tiger@localhost/mydatabase')
+
+More notes on connecting to Postgresql at :ref:`postgresql_toplevel`.
+
+MySQL
+-----
+
+The MySQL dialect uses mysql-python as the default DBAPI::
+
+    # default
+    engine = create_engine('mysql://scott:tiger@localhost/foo')
+
+    # mysql-python
+    engine = create_engine('mysql+mysqldb://scott:tiger@localhost/foo')
+
+    # OurSQL
+    engine = create_engine('mysql+oursql://scott:tiger@localhost/foo')
+
+More notes on connecting to MySQL at :ref:`mysql_toplevel`.
+
+Oracle
+------
 
-    # postgresql - psycopg2 is the default driver.
-    pg_db = create_engine('postgresql://scott:tiger@localhost/mydatabase')
-    pg_db = create_engine('postgresql+psycopg2://scott:tiger@localhost/mydatabase')
-    pg_db = create_engine('postgresql+pg8000://scott:tiger@localhost/mydatabase')
-    pg_db = create_engine('postgresql+pypostgresql://scott:tiger@localhost/mydatabase')
+cx_oracle is usualjy used here::
 
-    # postgresql on Jython
-    pg_db = create_engine('postgresql+zxjdbc://scott:tiger@localhost/mydatabase')
+    engine = create_engine('oracle://scott:tiger@127.0.0.1:1521/sidname')
 
-    # mysql - MySQLdb (mysql-python) is the default driver
-    mysql_db = create_engine('mysql://scott:tiger@localhost/foo')
-    mysql_db = create_engine('mysql+mysqldb://scott:tiger@localhost/foo')
+    engine = create_engine('oracle+cx_oracle://scott:tiger@tnsname')
 
-    # mysql on Jython
-    mysql_db = create_engine('mysql+zxjdbc://localhost/foo')
+More notes on connecting to Oracle at :ref:`oracle_toplevel`.
 
-    # mysql with pyodbc (buggy)
-    mysql_db = create_engine('mysql+pyodbc://scott:tiger@some_dsn')
+Microsoft SQL Server
+--------------------
 
-    # oracle - cx_oracle is the default driver
-    oracle_db = create_engine('oracle://scott:tiger@127.0.0.1:1521/sidname')
+There are a few drivers for SQL Server, currently PyODBC is the most solid::
 
-    # oracle via TNS name
-    oracle_db = create_engine('oracle+cx_oracle://scott:tiger@tnsname')
+    engine = create_engine('mssql+pyodbc://mydsn')
 
-    # mssql using ODBC datasource names.  PyODBC is the default driver.
-    mssql_db = create_engine('mssql://mydsn')
-    mssql_db = create_engine('mssql+pyodbc://mydsn')
-    mssql_db = create_engine('mssql+adodbapi://mydsn')
-    mssql_db = create_engine('mssql+pyodbc://username:password@mydsn')
+More notes on connecting to SQL Server at :ref:`mssql_toplevel`.
+
+SQLite
+------
 
 SQLite connects to file based databases. The same URL format is used, omitting
 the hostname, and using the "file" portion as the filename of the database.
@@ -208,14 +233,31 @@ This has the effect of four slashes being present for an absolute file path::
 
     # sqlite://<nohostname>/<path>
     # where <path> is relative:
-    sqlite_db = create_engine('sqlite:///foo.db')
+    engine = create_engine('sqlite:///foo.db')
 
     # or absolute, starting with a slash:
-    sqlite_db = create_engine('sqlite:////absolute/path/to/foo.db')
+    engine = create_engine('sqlite:////absolute/path/to/foo.db')
 
 To use a SQLite ``:memory:`` database, specify an empty URL::
 
-    sqlite_memory_db = create_engine('sqlite://')
+    engine = create_engine('sqlite://')
+
+More notes on connecting to SQLite at :ref:`sqlite_toplevel`.
+
+Others
+------
+
+See :ref:`dialect_toplevel`, the top-level page for all dialect
+documentation.
+
+URL API
+--------
+
+.. autoclass:: sqlalchemy.engine.url.URL
+    :members:
+
+Pooling
+=======
 
 The :class:`.Engine` will ask the connection pool for a
 connection when the ``connect()`` or ``execute()`` methods are called. The
@@ -233,8 +275,9 @@ application, rather than creating a new one for each connection.
    :class:`.QueuePool` is not used by default for SQLite engines.  See
    :ref:`sqlite_toplevel` for details on SQLite connection pool usage.
 
-.. autoclass:: sqlalchemy.engine.url.URL
-    :members:
+For more information on connection pooling, see :ref:`pooling_toplevel`.
+
+
 
 .. _custom_dbapi_args:
 

diff --git a/doc/build/dialects/mssql.rst b/doc/build/dialects/mssql.rst
index 3b676060214329400e3280d6244c4ef7024f34b2..f969983328215283afb023e00d1553c2720134fc 100644 (file)
--- a/doc/build/dialects/mssql.rst
+++ b/doc/build/dialects/mssql.rst
@@ -1,3 +1,5 @@
+.. _mssql_toplevel:
+
 Microsoft SQL Server
 ====================
 

diff --git a/doc/build/dialects/mysql.rst b/doc/build/dialects/mysql.rst
index ff8f37bcb503881dc99852ab1483393c5db1b4f9..2439d8aa2ea97e14299737e7b4160526b4ec5190 100644 (file)
--- a/doc/build/dialects/mysql.rst
+++ b/doc/build/dialects/mysql.rst
@@ -1,3 +1,5 @@
+.. _mysql_toplevel:
+
 MySQL
 =====
 

diff --git a/doc/build/dialects/oracle.rst b/doc/build/dialects/oracle.rst
index d5cd969ea40a0ea9774883b88c15357ce86abb17..5e259ead76c9d3df17e10db32622fdee9b0891f7 100644 (file)
--- a/doc/build/dialects/oracle.rst
+++ b/doc/build/dialects/oracle.rst
@@ -1,3 +1,5 @@
+.. _oracle_toplevel:
+
 Oracle
 ======
 

diff --git a/lib/sqlalchemy/dialects/postgresql/psycopg2.py b/lib/sqlalchemy/dialects/postgresql/psycopg2.py
index 47c9e2232661005540e8140fd9e035d2a55ddba3..5aa93978bc8fa5f2cf921028f588225646693471 100644 (file)
--- a/lib/sqlalchemy/dialects/postgresql/psycopg2.py
+++ b/lib/sqlalchemy/dialects/postgresql/psycopg2.py
@@ -38,6 +38,26 @@ psycopg2-specific keyword arguments which are accepted by
 * *use_native_unicode* - Enable the usage of Psycopg2 "native unicode" mode
   per connection. True by default.
 
+Unix Domain Connections
+------------------------
+
+psycopg2 supports connecting via Unix domain connections.   When the ``host``
+portion of the URL is omitted, SQLAlchemy passes ``None`` to psycopg2,
+which specifies Unix-domain communication rather than TCP/IP communication::
+
+    create_engine("postgresql+psycopg2://user:password@/dbname")
+
+By default, the socket file used is to connect to a Unix-domain socket
+in ``/tmp``, or whatever socket directory was specified when PostgreSQL 
+was built.  This value can be overridden by passing a pathname to psycopg2,
+using ``host`` as an additional keyword argument::
+
+    create_engine("postgresql+psycopg2://user:password@/dbname?host=/var/lib/postgresql")
+
+See also:
+
+`PQconnectdbParams <http://www.postgresql.org/docs/9.1/static/libpq-connect.html#LIBPQ-PQCONNECTDBPARAMS>`_
+
 Per-Statement/Connection Execution Options
 -------------------------------------------