From: Mike Bayer Date: Mon, 13 Feb 2012 00:06:49 +0000 (-0500) Subject: - break out sample URLs into individual, per-database sections each with a link X-Git-Tag: rel_0_7_6~53 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=c6278444aa58f74c9373823b8dc4eebc6a21b2f1;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git - 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 7e315c1a74..c4a0b9af4e 100644 --- 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:/// # where 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 3b67606021..f969983328 100644 --- 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 ff8f37bcb5..2439d8aa2e 100644 --- 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 d5cd969ea4..5e259ead76 100644 --- 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 47c9e22326..5aa93978bc 100644 --- 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 `_ + Per-Statement/Connection Execution Options -------------------------------------------