.. image:: sqla_engine_arch.png
-Where above, a :class:`~sqlalchemy.engine.base.Engine` references both a
-:class:`~sqlalchemy.engine.base.Dialect` and :class:`~sqlalchemy.pool.Pool`,
+Where above, an :class:`~sqlalchemy.engine.base.Engine` references both a
+:class:`~sqlalchemy.engine.base.Dialect` and a :class:`~sqlalchemy.pool.Pool`,
which together interpret the DBAPI's module functions as well as the behavior
of the database.
Creating an engine is just a matter of issuing a single call,
-:func:`create_engine()`::
+:func:`.create_engine()`::
engine = create_engine('postgresql://scott:tiger@localhost:5432/mydatabase')
SQLAlchemy indicates the source of an Engine strictly via `RFC-1738
<http://rfc.net/rfc1738.html>`_ style URLs, combined with optional keyword
-arguments to specify options for the Engine. The form of the URL is:
+arguments to specify options for the Engine. The form of the URL is::
dialect+driver://username:password@host:port/database
* ``sqlalchemy.engine`` - controls SQL echoing. set to ``logging.INFO`` for SQL query output, ``logging.DEBUG`` for query + result set output.
* ``sqlalchemy.dialects`` - controls custom logging for SQL dialects. See the documentation of individual dialects for details.
* ``sqlalchemy.pool`` - controls connection pool logging. set to ``logging.INFO`` or lower to log connection pool checkouts/checkins.
-* ``sqlalchemy.orm`` - controls logging of various ORM functions. set to ``logging.INFO`` for configurational logging as well as unit of work dumps, ``logging.DEBUG`` for extensive logging during query and flush() operations. Subcategories of ``sqlalchemy.orm`` include:
- * ``sqlalchemy.orm.attributes`` - logs certain instrumented attribute operations, such as triggered callables
- * ``sqlalchemy.orm.mapper`` - logs Mapper configuration and operations
- * ``sqlalchemy.orm.unitofwork`` - logs flush() operations, including dependency sort graphs and other operations
- * ``sqlalchemy.orm.strategies`` - logs relationship loader operations (i.e. lazy and eager loads)
- * ``sqlalchemy.orm.sync`` - logs synchronization of attributes from parent to child instances during a flush()
+* ``sqlalchemy.orm`` - controls logging of various ORM functions. set to ``logging.INFO`` for information on mapper configurations.
-For example, to log SQL queries as well as unit of work debugging:
-
-.. sourcecode:: python+sql
+For example, to log SQL queries using Python logging instead of the ``echo=True`` flag::
import logging
logging.basicConfig()
logging.getLogger('sqlalchemy.engine').setLevel(logging.INFO)
- logging.getLogger('sqlalchemy.orm.unitofwork').setLevel(logging.DEBUG)
By default, the log level is set to ``logging.ERROR`` within the entire
``sqlalchemy`` namespace so that no log operations occur, even within an
additional keyword arguments.
:param convert_unicode=False: if set to True, all
- String/character based types will convert Unicode values to raw
- byte values going into the database, and all raw byte values to
+ String/character based types will convert Python Unicode values to raw
+ byte values sent to the DBAPI as bind parameters, and all raw byte values to
Python Unicode coming out in result sets. This is an
- engine-wide method to provide unicode conversion across the
- board. For unicode conversion on a column-by-column level, use
- the ``Unicode`` column type instead, described in `types`.
+ engine-wide method to provide Unicode conversion across the
+ board for those DBAPIs that do not accept Python Unicode objects
+ as input. For Unicode conversion on a column-by-column level, use
+ the ``Unicode`` column type instead, described in :ref:`types_toplevel`. Note that
+ many DBAPIs have the ability to return Python Unicode objects in
+ result sets directly - SQLAlchemy will use these modes of operation
+ if possible and will also attempt to detect "Unicode returns"
+ behavior by the DBAPI upon first connect by the
+ :class:`.Engine`. When this is detected, string values in
+ result sets are passed through without further processing.
:param creator: a callable which returns a DBAPI connection.
This creation function will be passed to the underlying
opened above and beyond the pool_size setting, which defaults
to five. this is only used with :class:`~sqlalchemy.pool.QueuePool`.
- :param module=None: used by database implementations which
- support multiple DBAPI modules, this is a reference to a DBAPI2
- module to be used instead of the engine's default module. For
- PostgreSQL, the default is psycopg2. For Oracle, it's cx_Oracle.
+ :param module=None: reference to a Python module object (the module itself, not
+ its string name). Specifies an alternate DBAPI module to be used
+ by the engine's dialect. Each sub-dialect references a specific DBAPI which
+ will be imported before first connect. This parameter causes the
+ import to be bypassed, and the given module to be used instead.
+ Can be used for testing of DBAPIs as well as to inject "mock"
+ DBAPI implementations into the :class:`.Engine`.
:param pool=None: an already-constructed instance of
:class:`~sqlalchemy.pool.Pool`, such as a
pool will be used directly as the underlying connection pool
for the engine, bypassing whatever connection parameters are
present in the URL argument. For information on constructing
- connection pools manually, see `pooling`.
+ connection pools manually, see :ref:`pooling_toplevel`.
:param poolclass=None: a :class:`~sqlalchemy.pool.Pool`
subclass, which will be used to create a connection pool
connections after the given number of seconds has passed. It
defaults to -1, or no timeout. For example, setting to 3600
means connections will be recycled after one hour. Note that
- MySQL in particular will ``disconnect automatically`` if no
+ MySQL in particular will disconnect automatically if no
activity is detected on a connection for eight hours (although
this is configurable with the MySQLDB connection itself and the
server configuration as well).
up on getting a connection from the pool. This is only used
with :class:`~sqlalchemy.pool.QueuePool`.
- :param strategy='plain': used to invoke alternate :class:`~sqlalchemy.engine.base.Engine.`
- implementations. Currently available is the ``threadlocal``
+ :param strategy='plain': selects alternate engine implementations.
+ Currently available is the ``threadlocal``
strategy, which is described in :ref:`threadlocal_strategy`.
"""
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
