Working with Engines and Connections
=====================================
-.. module:: sqlalchemy.engine.base
+.. module:: sqlalchemy.engine
This section details direct usage of the :class:`.Engine`,
:class:`.Connection`, and related objects. Its important to note that when
object internally. See :ref:`unitofwork_transaction` for further
information.
-The :class:`~sqlalchemy.engine.base.Connection` object provides a ``begin()``
+The :class:`~sqlalchemy.engine.Connection` object provides a ``begin()``
method which returns a :class:`~sqlalchemy.engine.base.Transaction` object.
This object is usually used within a try/except clause so that it is
guaranteed to ``rollback()`` or ``commit()``::
)
Explicit execution delivers the SQL text or constructed SQL expression to the
-``execute()`` method of :class:`~sqlalchemy.engine.base.Connection`:
+``execute()`` method of :class:`~sqlalchemy.engine.Connection`:
.. sourcecode:: python+sql
connection.close()
Explicit, connectionless execution delivers the expression to the
-``execute()`` method of :class:`~sqlalchemy.engine.base.Engine`:
+``execute()`` method of :class:`~sqlalchemy.engine.Engine`:
.. sourcecode:: python+sql
Implicit execution is also connectionless, and calls the ``execute()`` method
on the expression itself, utilizing the fact that either an
-:class:`~sqlalchemy.engine.base.Engine` or
-:class:`~sqlalchemy.engine.base.Connection` has been *bound* to the expression
+:class:`~sqlalchemy.engine.Engine` or
+:class:`~sqlalchemy.engine.Connection` has been *bound* to the expression
object (binding is discussed further in
:ref:`metadata_toplevel`):
result.close()
In both "connectionless" examples, the
-:class:`~sqlalchemy.engine.base.Connection` is created behind the scenes; the
-:class:`~sqlalchemy.engine.base.ResultProxy` returned by the ``execute()``
-call references the :class:`~sqlalchemy.engine.base.Connection` used to issue
+:class:`~sqlalchemy.engine.Connection` is created behind the scenes; the
+:class:`~sqlalchemy.engine.ResultProxy` returned by the ``execute()``
+call references the :class:`~sqlalchemy.engine.Connection` used to issue
the SQL statement. When the :class:`.ResultProxy` is closed, the underlying
:class:`.Connection` is closed for us, resulting in the
DBAPI connection being returned to the pool with transactional resources removed.
:show-inheritance:
:members:
-.. autoclass:: sqlalchemy.engine.base.ResultProxy
+.. autoclass:: sqlalchemy.engine.ResultProxy
:members:
-.. autoclass:: sqlalchemy.engine.base.RowProxy
+.. autoclass:: sqlalchemy.engine.RowProxy
:members:
.. autoclass:: Transaction
.. image:: sqla_engine_arch.png
-Where above, an :class:`~sqlalchemy.engine.base.Engine` references both a
+Where above, an :class:`~sqlalchemy.engine.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.
The ``echo`` flags present as keyword arguments to
:func:`~sqlalchemy.create_engine` and others as well as the ``echo`` property
-on :class:`~sqlalchemy.engine.base.Engine`, when set to ``True``, will first
+on :class:`~sqlalchemy.engine.Engine`, when set to ``True``, will first
attempt to ensure that logging is enabled. Unfortunately, the ``logging``
module provides no way of determining if output has already been configured
(note we are referring to if a logging configuration has been set up, not just
**when using Python logging, ensure all echo flags are set to False at all
times**, to avoid getting duplicate log lines.
-The logger name of instance such as an :class:`~sqlalchemy.engine.base.Engine`
+The logger name of instance such as an :class:`~sqlalchemy.engine.Engine`
or :class:`~sqlalchemy.pool.Pool` defaults to using a truncated hex identifier
string. To set this to a specific name, use the "logging_name" and
"pool_logging_name" keyword arguments with :func:`sqlalchemy.create_engine`.
:show-inheritance:
.. autoclass:: sqlalchemy.sql.operators.Operators
- :members:
+ :members: __and__, __or__, __invert__, op, operate, reverse_operate
:undoc-members:
- .. automethod:: __and__
- .. automethod:: __or__
- .. automethod:: __invert__
.. autoclass:: Select
:members:
.. currentmodule: sqlalchemy
-.. autoclass:: sqlalchemy.engine.base.Compiled
+.. autoclass:: sqlalchemy.engine.Compiled
:members:
:undoc-members:
:show-inheritance:
:undoc-members:
:show-inheritance:
-.. autoclass:: sqlalchemy.engine.base.Dialect
+.. autoclass:: sqlalchemy.engine.Dialect
:members:
:undoc-members:
:show-inheritance:
:undoc-members:
:show-inheritance:
-.. autoclass:: sqlalchemy.engine.base.ExecutionContext
+.. autoclass:: sqlalchemy.engine.ExecutionContext
:members:
:undoc-members:
:show-inheritance:
Connection Pool Configuration
-----------------------------
-The :class:`~.engine.base.Engine` returned by the
+The :class:`~.engine.Engine` returned by the
:func:`~sqlalchemy.create_engine` function in most cases has a :class:`.QueuePool`
integrated, pre-configured with reasonable pooling defaults. If
you're reading this section only to learn how to enable pooling - congratulations!
Notice in the previous section the creator/dropper methods accept an argument
for the database engine in use. When a schema construct is combined with an
-:class:`~sqlalchemy.engine.base.Engine` object, or an individual
-:class:`~sqlalchemy.engine.base.Connection` object, we call this the *bind*.
+:class:`~sqlalchemy.engine.Engine` object, or an individual
+:class:`~sqlalchemy.engine.Connection` object, we call this the *bind*.
In the above examples the bind is associated with the schema construct only
for the duration of the operation. However, the option exists to persistently
associate a bind with a set of schema constructs via the
meta.bind = engine
We can now call methods like :func:`~sqlalchemy.schema.MetaData.create_all`
-without needing to pass the :class:`~sqlalchemy.engine.base.Engine`::
+without needing to pass the :class:`~sqlalchemy.engine.Engine`::
meta.create_all()
* You aren't using the ORM, are usually using "connectionless" execution, and
find yourself constantly needing to specify the same
- :class:`~sqlalchemy.engine.base.Engine` object throughout the entire
+ :class:`~sqlalchemy.engine.Engine` object throughout the entire
application. Bind can be used here to provide "implicit" execution.
* Your application has multiple schemas that correspond to different engines.
Using one :class:`~sqlalchemy.schema.MetaData` for each schema, bound to
When the statement is executed with a single set of parameters (that is, it is
not an "executemany" style execution), the returned
-:class:`~sqlalchemy.engine.base.ResultProxy` will contain a collection
+:class:`~sqlalchemy.engine.ResultProxy` will contain a collection
accessible via ``result.postfetch_cols()`` which contains a list of all
:class:`~sqlalchemy.schema.Column` objects which had an inline-executed
default. Similarly, all parameters which were bound to the statement,
including all Python and SQL expressions which were pre-executed, are present
in the ``last_inserted_params()`` or ``last_updated_params()`` collections on
-:class:`~sqlalchemy.engine.base.ResultProxy`. The ``inserted_primary_key``
+:class:`~sqlalchemy.engine.ResultProxy`. The ``inserted_primary_key``
collection contains a list of primary key values for the row inserted (a list
so that single-column and composite-column primary keys are represented in the
same format).
>>> conn = engine.connect()
>>> conn #doctest: +ELLIPSIS
- <sqlalchemy.engine.base.Connection object at 0x...>
+ <sqlalchemy.engine.Connection object at 0x...>
-The :class:`~sqlalchemy.engine.base.Connection` object represents an actively
+The :class:`~sqlalchemy.engine.Connection` object represents an actively
checked out DBAPI connection resource. Lets feed it our
:class:`~sqlalchemy.sql.expression.Insert` object and see what happens:
So the INSERT statement was now issued to the database. Although we got
positional "qmark" bind parameters instead of "named" bind parameters in the
output. How come ? Because when executed, the
-:class:`~sqlalchemy.engine.base.Connection` used the SQLite **dialect** to
+:class:`~sqlalchemy.engine.Connection` used the SQLite **dialect** to
help generate the statement; when we use the ``str()`` function, the statement
isn't aware of this dialect, and falls back onto a default which uses named
parameters. We can view this manually as follows:
'INSERT INTO users (name, fullname) VALUES (?, ?)'
What about the ``result`` variable we got when we called ``execute()`` ? As
-the SQLAlchemy :class:`~sqlalchemy.engine.base.Connection` object references a
+the SQLAlchemy :class:`~sqlalchemy.engine.Connection` object references a
DBAPI connection, the result, known as a
-:class:`~sqlalchemy.engine.base.ResultProxy` object, is analogous to the DBAPI
+:class:`~sqlalchemy.engine.ResultProxy` object, is analogous to the DBAPI
cursor object. In the case of an INSERT, we can get important information from
it, such as the primary key values which were generated from our statement:
various behaviors of expression language constructs. In the usual case, an
:class:`~sqlalchemy.sql.expression.Insert` statement is usually compiled
against the parameters sent to the ``execute()`` method on
-:class:`~sqlalchemy.engine.base.Connection`, so that there's no need to use
+:class:`~sqlalchemy.engine.Connection`, so that there's no need to use
the ``values`` keyword with :class:`~sqlalchemy.sql.expression.Insert`. Lets
create a generic :class:`~sqlalchemy.sql.expression.Insert` statement again
and use it in the "normal" way:
{opensql}INSERT INTO users (id, name, fullname) VALUES (?, ?, ?)
(2, 'wendy', 'Wendy Williams')
COMMIT
- {stop}<sqlalchemy.engine.base.ResultProxy object at 0x...>
+ {stop}<sqlalchemy.engine.ResultProxy object at 0x...>
Above, because we specified all three columns in the the ``execute()`` method,
the compiled :class:`~sqlalchemy.sql.expression.Insert` included all three
{opensql}INSERT INTO addresses (user_id, email_address) VALUES (?, ?)
((1, 'jack@yahoo.com'), (1, 'jack@msn.com'), (2, 'www@www.org'), (2, 'wendy@aol.com'))
COMMIT
- {stop}<sqlalchemy.engine.base.ResultProxy object at 0x...>
+ {stop}<sqlalchemy.engine.ResultProxy object at 0x...>
Above, we again relied upon SQLite's automatic generation of primary key
identifiers for each ``addresses`` row.
====================================
We're executing our :class:`~sqlalchemy.sql.expression.Insert` using a
-:class:`~sqlalchemy.engine.base.Connection`. There's two options that allow
+:class:`~sqlalchemy.engine.Connection`. There's two options that allow
you to not have to deal with the connection part. You can execute in the
**connectionless** style, using the engine, which checks out from the
connection pool a connection for you, performs the execute operation with that
COMMIT
and you can save even more steps than that, if you connect the
-:class:`~sqlalchemy.engine.base.Engine` to the
+:class:`~sqlalchemy.engine.Engine` to the
:class:`~sqlalchemy.schema.MetaData` object we created earlier. When this is
done, all SQL expressions which involve tables within the
:class:`~sqlalchemy.schema.MetaData` object will be automatically **bound** to
-the :class:`~sqlalchemy.engine.base.Engine`. In this case, we call it
+the :class:`~sqlalchemy.engine.Engine`. In this case, we call it
**implicit execution**:
.. sourcecode:: pycon+sql
within the COLUMNS clause of the select, and then executing. SQLAlchemy
expanded the ``users`` table into the set of each of its columns, and also
generated a FROM clause for us. The result returned is again a
-:class:`~sqlalchemy.engine.base.ResultProxy` object, which acts much like a
+:class:`~sqlalchemy.engine.ResultProxy` object, which acts much like a
DBAPI cursor, including methods such as
-:func:`~sqlalchemy.engine.base.ResultProxy.fetchone` and
-:func:`~sqlalchemy.engine.base.ResultProxy.fetchall`. The easiest way to get
+:func:`~sqlalchemy.engine.ResultProxy.fetchone` and
+:func:`~sqlalchemy.engine.ResultProxy.fetchall`. The easiest way to get
rows from it is to just iterate:
.. sourcecode:: pycon+sql
Result sets which have pending rows remaining should be explicitly closed
before discarding. While the cursor and connection resources referenced by the
-:class:`~sqlalchemy.engine.base.ResultProxy` will be respectively closed and
+:class:`~sqlalchemy.engine.ResultProxy` will be respectively closed and
returned to the connection pool when the object is garbage collected, it's
better to make it explicit as some database APIs are very picky about such
things:
concat(users.name, users.fullname)
The above illustrates the SQL that's generated for an
-:class:`~sqlalchemy.engine.base.Engine` that's connected to a MySQL database;
+:class:`~sqlalchemy.engine.Engine` that's connected to a MySQL database;
the ``||`` operator now compiles as MySQL's ``concat()`` function.
If you have come across an operator which really isn't available, you can
UPDATE users SET name=? WHERE users.name = ?
('ed', 'jack')
COMMIT
- {stop}<sqlalchemy.engine.base.ResultProxy object at 0x...>
+ {stop}<sqlalchemy.engine.ResultProxy object at 0x...>
>>> # use bind parameters
>>> u = users.update().\
UPDATE users SET name=? WHERE users.name = ?
('ed', 'jack')
COMMIT
- {stop}<sqlalchemy.engine.base.ResultProxy object at 0x...>
+ {stop}<sqlalchemy.engine.ResultProxy object at 0x...>
>>> # with binds, you can also update many rows at once
{sql}>>> conn.execute(u,
UPDATE users SET name=? WHERE users.name = ?
[('ed', 'jack'), ('mary', 'wendy'), ('jake', 'jim')]
COMMIT
- {stop}<sqlalchemy.engine.base.ResultProxy object at 0x...>
+ {stop}<sqlalchemy.engine.ResultProxy object at 0x...>
>>> # update a column to an expression.:
{sql}>>> conn.execute(users.update().
UPDATE users SET fullname=(? || users.name)
('Fullname: ',)
COMMIT
- {stop}<sqlalchemy.engine.base.ResultProxy object at 0x...>
+ {stop}<sqlalchemy.engine.ResultProxy object at 0x...>
Correlated Updates
------------------
LIMIT 1 OFFSET 0)
()
COMMIT
- {stop}<sqlalchemy.engine.base.ResultProxy object at 0x...>
+ {stop}<sqlalchemy.engine.ResultProxy object at 0x...>
Multiple Table Updates
----------------------
DELETE FROM addresses
()
COMMIT
- {stop}<sqlalchemy.engine.base.ResultProxy object at 0x...>
+ {stop}<sqlalchemy.engine.ResultProxy object at 0x...>
{sql}>>> conn.execute(users.delete().where(users.c.name > 'm')) #doctest: +ELLIPSIS
DELETE FROM users WHERE users.name > ?
('m',)
COMMIT
- {stop}<sqlalchemy.engine.base.ResultProxy object at 0x...>
+ {stop}<sqlalchemy.engine.ResultProxy object at 0x...>
Further Reference
==================
:class:`~sqlalchemy.orm.session.Session` within its transactional context.
This is most easily accomplished using the
:func:`~sqlalchemy.orm.session.Session.execute` method, which returns a
-:class:`~sqlalchemy.engine.base.ResultProxy` in the same manner as an
-:class:`~sqlalchemy.engine.base.Engine` or
-:class:`~sqlalchemy.engine.base.Connection`::
+:class:`~sqlalchemy.engine.ResultProxy` in the same manner as an
+:class:`~sqlalchemy.engine.Engine` or
+:class:`~sqlalchemy.engine.Connection`::
Session = sessionmaker(bind=engine)
session = Session()
# execute a SQL expression construct
result = session.execute(select([mytable]).where(mytable.c.id==7))
-The current :class:`~sqlalchemy.engine.base.Connection` held by the
+The current :class:`~sqlalchemy.engine.Connection` held by the
:class:`~sqlalchemy.orm.session.Session` is accessible using the
:func:`~sqlalchemy.orm.session.Session.connection` method::
connection = session.connection()
The examples above deal with a :class:`~sqlalchemy.orm.session.Session` that's
-bound to a single :class:`~sqlalchemy.engine.base.Engine` or
-:class:`~sqlalchemy.engine.base.Connection`. To execute statements using a
+bound to a single :class:`~sqlalchemy.engine.Engine` or
+:class:`~sqlalchemy.engine.Connection`. To execute statements using a
:class:`~sqlalchemy.orm.session.Session` which is bound either to multiple
engines, or none at all (i.e. relies upon bound metadata), both
:func:`~sqlalchemy.orm.session.Session.execute` and
>>> Session = sessionmaker(bind=engine)
In the case where your application does not yet have an
-:class:`~sqlalchemy.engine.base.Engine` when you define your module-level
+:class:`~sqlalchemy.engine.Engine` when you define your module-level
objects, just set it up like this::
>>> Session = sessionmaker()
``connection.cursor('some name')``, which has the effect that result rows are
not immediately pre-fetched and buffered after statement execution, but are
instead left on the server and only retrieved as needed. SQLAlchemy's
- :class:`~sqlalchemy.engine.base.ResultProxy` uses special row-buffering
+ :class:`~sqlalchemy.engine.ResultProxy` uses special row-buffering
behavior when this feature is enabled, such that groups of 100 rows at a
time are fetched over the wire to reduce conversational overhead.
Note that the ``stream_results=True`` execution option is a more targeted
:param execution_options: Dictionary execution options which will
be applied to all connections. See
- :meth:`~sqlalchemy.engine.base.Connection.execution_options`
+ :meth:`~sqlalchemy.engine.Connection.execution_options`
:param implicit_returning=True: When ``True``, a RETURNING-
compatible construct, if available, will be used to
:param bind: a :class:`~sqlalchemy.engine.base.Connectable`,
which is typically an instance of
- :class:`~sqlalchemy.engine.base.Engine` or
- :class:`~sqlalchemy.engine.base.Connection`.
+ :class:`~sqlalchemy.engine.Engine` or
+ :class:`~sqlalchemy.engine.Connection`.
For a dialect-specific instance of :class:`.Inspector`, see
:meth:`Inspector.from_engine`
:param bind: a :class:`~sqlalchemy.engine.base.Connectable`,
which is typically an instance of
- :class:`~sqlalchemy.engine.base.Engine` or
- :class:`~sqlalchemy.engine.base.Connection`.
+ :class:`~sqlalchemy.engine.Engine` or
+ :class:`~sqlalchemy.engine.Connection`.
This method differs from direct a direct constructor call of :class:`.Inspector`
in that the :class:`~sqlalchemy.engine.base.Dialect` is given a chance to provide
should be issued. Results from all shards returned will be combined
together into a single listing.
- :param shards: A dictionary of string shard names to :class:`~sqlalchemy.engine.base.Engine`
+ :param shards: A dictionary of string shard names to :class:`~sqlalchemy.engine.Engine`
objects.
"""
:param session: The target :class:`.Session`.
:param transaction: The :class:`.SessionTransaction`.
- :param connection: The :class:`~.engine.base.Connection` object
+ :param connection: The :class:`~.engine.Connection` object
which will be used for SQL statements.
"""
item from the identity map.
row
- A ``sqlalchemy.engine.base.RowProxy`` instance or a
+ A ``sqlalchemy.engine.RowProxy`` instance or a
dictionary corresponding result-set ``ColumnElement``
instances to their values within a row.
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
