.. seealso::
- :ref:`pooling_toplevel`
+ :ref:`pooling_toplevel`
DBAPI
DBAPI is shorthand for the phrase "Python Database API
created perhaps within distinct databases::
DefaultBase.metadata.create_all(some_engine)
- OtherBase.metadata_create_all(some_other_engine)
+ OtherBase.metadata.create_all(some_other_engine)
``__table_cls__``
:class:`~sqlalchemy.orm.session.Session` which is bound either to multiple
engines, or none at all (i.e. relies upon bound metadata), both
:meth:`~.Session.execute` and
-:meth:`~.Session.connection` accept a ``mapper`` keyword
-argument, which is passed a mapped class or
+:meth:`~.Session.connection` accept a dictionary of bind arguments
+:paramref:`~.Session.execute.bind_arguments` which may include "mapper"
+which is passed a mapped class or
:class:`~sqlalchemy.orm.mapper.Mapper` instance, which is used to locate the
proper context for the desired engine::
session = Session()
# need to specify mapper or class when executing
- result = session.execute("select * from table where id=:id", {'id':7}, mapper=MyMappedClass)
+ result = session.execute("select * from table where id=:id", {'id':7}, bind_arguments={'mapper': MyMappedClass})
- result = session.execute(select([mytable], mytable.c.id==7), mapper=MyMappedClass)
+ result = session.execute(select([mytable], mytable.c.id==7), bind_arguments={'mapper': MyMappedClass})
connection = session.connection(MyMappedClass)
For server-generating columns that are not primary key columns or that are not
simple autoincrementing integer columns, the ORM requires that these columns
-are marked with an appropriate server_default directive that allows the ORM to
+are marked with an appropriate ``server_default`` directive that allows the ORM to
retrieve this value. Not all methods are supported on all backends, however,
so care must be taken to use the appropriate method. The two questions to be
answered are, 1. is this column part of the primary key or not, and 2. does the
----------------------------
:meth:`~.Session.add` is used to place instances in the
-session. For *transient* (i.e. brand new) instances, this will have the effect
+session. For :term:`transient` (i.e. brand new) instances, this will have the effect
of an INSERT taking place for those instances upon the next flush. For
-instances which are *persistent* (i.e. were loaded by this session), they are
-already present and do not need to be added. Instances which are *detached*
+instances which are :term:`persistent` (i.e. were loaded by this session), they are
+already present and do not need to be added. Instances which are :term:`detached`
(i.e. have been removed from a session) may be re-associated with a session
using this method::
# ...
addresses = relationship(
- "Address", cascade="all, delete, delete-orphan")
+ "Address", cascade="all, delete-orphan")
# ...
# ...
preference = relationship(
- "Preference", cascade="all, delete, delete-orphan",
+ "Preference", cascade="all, delete-orphan",
single_parent=True)
representing a complete statement can be passed to
:meth:`~sqlalchemy.orm.query.Query.from_statement()`. Without further
specification, the ORM will match columns in the ORM mapping to the result
-returned by the SQL statement based on column name::
+returned by the SQL statement based on column name:
.. sourcecode:: python+sql
resolved through any of the optional keyword arguments. This
ultimately makes usage of the :meth:`.get_bind` method for resolution.
- :param bind_arguments: dictionary of bind arguments. may include
+ :param bind_arguments: dictionary of bind arguments. May include
"mapper", "bind", "clause", other custom arguments that are passed
to :meth:`.Session.get_bind`.
The :meth:`.Session.execute` method does *not* invoke autoflush.
- The :class:`_engine.CursorResult` returned by the :meth:`.Session.
- execute`
+ The :class:`_engine.CursorResult` returned by the
+ :meth:`.Session.execute`
method is returned with the "close_with_result" flag set to true;
the significance of this flag is that if this :class:`.Session` is
autocommitting and does not have a transaction-dedicated
:class:`.Session` is configured with autocommit=True and no
transaction has been started.
- :param clause:
+ :param statement:
An executable statement (i.e. an :class:`.Executable` expression
such as :func:`_expression.select`) or string SQL statement
to be executed.
must correspond to parameter names present in the statement.
:param bind_arguments: dictionary of additional arguments to determine
- the bind. may include "mapper", "bind", or other custom arguments.
+ the bind. May include "mapper", "bind", or other custom arguments.
Contents of this dictionary are passed to the
:meth:`.Session.get_bind` method.
The order of resolution is:
- 1. if mapper given and session.binds is present,
+ 1. if mapper given and :paramref:`.Session.binds` is present,
locate a bind based first on the mapper in use, then
on the mapped class in use, then on any base classes that are
present in the ``__mro__`` of the mapped class, from more specific
superclasses to more general.
- 2. if clause given and session.binds is present,
+ 2. if clause given and ``Session.binds`` is present,
locate a bind based on :class:`_schema.Table` objects
- found in the given clause present in session.binds.
- 3. if session.bind is present, return that.
+ found in the given clause present in ``Session.binds``.
+ 3. if ``Session.binds`` is present, return that.
4. if clause given, attempt to return a bind
linked to the :class:`_schema.MetaData` ultimately
associated with the clause.
.. seealso::
- ``load_on_pending`` at :func:`_orm.relationship` - this flag
+ :paramref:`_orm.relationship.load_on_pending` - this flag
allows per-relationship loading of many-to-ones on items that
are pending.
E.g.::
- >>> row = engine.execute(\
- text("select * from table where a=1 and b=2")\
- ).first()
+ >>> row = engine.execute(
+ ... text("select * from table where a=1 and b=2")).first()
>>> identity_key(MyClass, row=row)
(<class '__main__.MyClass'>, (1, 2), None)
added to any existing RETURNING clause, provided that
:meth:`.UpdateBase.returning` is not used simultaneously. The column
values will then be available on the result using the
- :attr:`_engine.CursorResult.returned_defaults` accessor as a dictionary
- ,
+ :attr:`_engine.CursorResult.returned_defaults` accessor as
+ a dictionary,
referring to values keyed to the :class:`_schema.Column`
object as well as
its ``.key``.
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
