Downloads for each DBAPI at the time of this writing are as follows:
* Supported Dialects
- - PostgreSQL: `psycopg2 <http://www.initd.org/tracker/psycopg/wiki/PsycopgTwo>`_ `pg8000 <http://pybrary.net/pg8000/>`_
- - PostgreSQL on Jython: `PostgreSQL JDBC Driver <http://jdbc.postgresql.org/>`_
- - SQLite: `sqlite3 <http://www.python.org/doc/2.5.2/lib/module-sqlite3.html>`_ (included in Python 2.5 or greater) `pysqlite <http://initd.org/tracker/pysqlite>`_
- - MySQL: `MySQLdb (a.k.a. mysql-python) <http://sourceforge.net/projects/mysql-python>`_
- - MySQL on Jython: `MySQL Connector/J JDBC driver <http://dev.mysql.com/downloads/connector/j/>`_
- - Oracle: `cx_Oracle <http://cx-oracle.sourceforge.net/>`_
- - Oracle on Jython: `Oracle JDBC Driver <http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/index.html>`_
- - Firebird: `kinterbasdb <http://kinterbasdb.sourceforge.net/>`_
- - MS-SQL, MSAccess: `pyodbc <http://pyodbc.sourceforge.net/>`_ (recommended) `adodbapi <http://adodbapi.sourceforge.net/>`_ `pymssql <http://pymssql.sourceforge.net/>`_
- - MS-SQL on Jython: `jTDS JDBC Driver <http://jtds.sourceforge.net/>`_
+ - PostgreSQL: `psycopg2 <http://www.initd.org/tracker/psycopg/wiki/PsycopgTwo>`_ `pg8000 <http://pybrary.net/pg8000/>`_
+ - PostgreSQL on Jython: `PostgreSQL JDBC Driver <http://jdbc.postgresql.org/>`_
+ - SQLite: `sqlite3 <http://www.python.org/doc/2.5.2/lib/module-sqlite3.html>`_ (included in Python 2.5 or greater) `pysqlite <http://initd.org/tracker/pysqlite>`_
+ - MySQL: `MySQLdb (a.k.a. mysql-python) <http://sourceforge.net/projects/mysql-python>`_
+ - MySQL on Jython: `MySQL Connector/J JDBC driver <http://dev.mysql.com/downloads/connector/j/>`_
+ - Oracle: `cx_Oracle <http://cx-oracle.sourceforge.net/>`_
+ - Oracle on Jython: `Oracle JDBC Driver <http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/index.html>`_
+ - Firebird: `kinterbasdb <http://kinterbasdb.sourceforge.net/>`_
+ - MS-SQL, MSAccess: `pyodbc <http://pyodbc.sourceforge.net/>`_ (recommended) `adodbapi <http://adodbapi.sourceforge.net/>`_ `pymssql <http://pymssql.sourceforge.net/>`_
+ - MS-SQL on Jython: `jTDS JDBC Driver <http://jtds.sourceforge.net/>`_
* Experimental Dialects
- - MSAccess: `pyodbc <http://pyodbc.sourceforge.net/>`_
- - Informix: `informixdb <http://informixdb.sourceforge.net/>`_
- - Sybase: TODO
- - MAXDB: TODO
+ - MSAccess: `pyodbc <http://pyodbc.sourceforge.net/>`_
+ - Informix: `informixdb <http://informixdb.sourceforge.net/>`_
+ - Sybase: TODO
+ - MAXDB: TODO
* Third Party Dialects
- - DB2/Informix IDS: `ibm-db <http://code.google.com/p/ibm-db/>`_
+ - DB2/Informix IDS: `ibm-db <http://code.google.com/p/ibm-db/>`_
The SQLAlchemy Wiki contains a page of database notes, describing whatever quirks and behaviors have been observed. Its a good place to check for issues with specific databases. `Database Notes <http://www.sqlalchemy.org/trac/wiki/DatabaseNotes>`_
print row['col1'], row['col2']
connection.close()
-The above SQL construct is known as a ``select()``. The full range of SQL constructs available are described in `sql`.
+The above SQL construct is known as a ``select()``. The full range of SQL constructs available are described in :ref:`sqlexpression_toplevel`.
Both ``Connection`` and ``Engine`` fulfill an interface known as ``Connectable`` which specifies common functionality between the two objects, namely being able to call ``connect()`` to return a ``Connection`` object (``Connection`` just returns itself), and being able to call ``execute()`` to get a result set. Following this, most SQLAlchemy functions and objects which accept an ``Engine`` as a parameter or attribute with which to execute SQL will also accept a ``Connection``. This argument is named ``bind``::
Above, ``method_a`` is called first, which calls ``connection.begin()``. Then it calls ``method_b``. When ``method_b`` calls ``connection.begin()``, it just increments a counter that is decremented when it calls ``commit()``. If either ``method_a`` or ``method_b`` calls ``rollback()``, the whole transaction is rolled back. The transaction is not committed until ``method_a`` calls the ``commit()`` method. This "nesting" behavior allows the creation of functions which "guarantee" that a transaction will be used if one was not already available, but will automatically participate in an enclosing transaction if one exists.
-Note that SQLAlchemy's Object Relational Mapper also provides a way to control transaction scope at a higher level; this is described in `unitofwork_transaction`.
+Note that SQLAlchemy's Object Relational Mapper also provides a way to control transaction scope at a higher level; this is described in :ref:`unitofwork_transaction`.
.. index::
single: thread safety; transactions
conn = engine.connect()
conn.execute("INSERT INTO users VALUES (1, 'john')") # autocommits
+.. _dbengine_implicit:
+
Connectionless Execution, Implicit Execution
=============================================
-Recall from the first section we mentioned executing with and without a ``Connection``. ``Connectionless`` execution refers to calling the ``execute()`` method on an object which is not a ``Connection``, which could be on the ``Engine`` itself, or could be a constructed SQL object. When we say "implicit", we mean that we are calling the ``execute()`` method on an object which is neither a ``Connection`` nor an ``Engine`` object; this can only be used with constructed SQL objects which have their own ``execute()`` method, and can be "bound" to an ``Engine``. A description of "constructed SQL objects" may be found in `sql`.
+Recall from the first section we mentioned executing with and without a ``Connection``. ``Connectionless`` execution refers to calling the ``execute()`` method on an object which is not a ``Connection``, which could be on the ``Engine`` itself, or could be a constructed SQL object. When we say "implicit", we mean that we are calling the ``execute()`` method on an object which is neither a ``Connection`` nor an ``Engine`` object; this can only be used with constructed SQL objects which have their own ``execute()`` method, and can be "bound" to an ``Engine``. A description of "constructed SQL objects" may be found in :ref:`sqlexpression_toplevel`.
-A summary of all three methods follows below. First, assume the usage of the following ``MetaData`` and ``Table`` objects; while we haven't yet introduced these concepts, for now you only need to know that we are representing a database table, and are creating an "executable" SQL construct which issues a statement to the database. These objects are described in `metadata`.
+A summary of all three methods follows below. First, assume the usage of the following ``MetaData`` and ``Table`` objects; while we haven't yet introduced these concepts, for now you only need to know that we are representing a database table, and are creating an "executable" SQL construct which issues a statement to the database. These objects are described in :ref:`metadata_toplevel`.
.. sourcecode:: python+sql
# ....
result.close()
-Implicit execution is also connectionless, and calls the ``execute()`` method on the expression itself, utilizing the fact that either an ``Engine`` or ``Connection`` has been *bound* to the expression object (binding is discussed further in the next section, `metadata`):
+Implicit execution is also connectionless, and calls the ``execute()`` method on the expression itself, utilizing the fact that either an ``Engine`` or ``Connection`` has been *bound* to the expression object (binding is discussed further in the next section, :ref:`metadata_toplevel`):
.. sourcecode:: python+sql
m = mapper(User, users_table, extension=[ext1, ext2, ext3])
+.. _advdatamapping_relation:
+
Relation Configuration
=======================
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-A ``dict`` can be used as a collection, but a keying strategy is needed to map entities loaded by the ORM to key, value pairs. The `sqlalchemy.orm.collections` package provides several built-in types for dictionary-based collections:
+A ``dict`` can be used as a collection, but a keying strategy is needed to map entities loaded by the ORM to key, value pairs. The :mod:`sqlalchemy.orm.collections` package provides several built-in types for dictionary-based collections:
.. sourcecode:: python+sql
These functions each provide a ``dict`` subclass with decorated ``set`` and ``remove`` methods and the keying strategy of your choice.
-The `sqlalchemy.orm.collections.MappedCollection` class can be used as a base class for your custom types or as a mix-in to quickly add ``dict`` collection support to other classes. It uses a keying function to delegate to ``__setitem__`` and ``__delitem__``:
+The :class:`sqlalchemy.orm.collections.MappedCollection` class can be used as a base class for your custom types or as a mix-in to quickly add ``dict`` collection support to other classes. It uses a keying function to delegate to ``__setitem__`` and ``__delitem__``:
.. sourcecode:: python+sql
The ORM uses this approach for built-ins, quietly substituting a trivial subclass when a ``list``, ``set`` or ``dict`` is used directly.
-The collections package provides additional decorators and support for authoring custom types. See the `sqlalchemy.orm.collections` for more information and discussion of advanced usage and Python 2.3-compatible decoration options.
+The collections package provides additional decorators and support for authoring custom types. See the :mod:`sqlalchemy.orm.collections` package for more information and discussion of advanced usage and Python 2.3-compatible decoration options.
Configuring Loader Strategies: Lazy Loading, Eager Loading
-----------------------------------------------------------
>>> jack.addresses
[<Address('jack@google.com')>, <Address('j25@yahoo.com')>]
-SQLAlchemy has the ability to control exactly which attributes and how many levels deep should be joined together in a single SQL query. More information on this feature is available in `advdatamapping_relation`.
+SQLAlchemy has the ability to control exactly which attributes and how many levels deep should be joined together in a single SQL query. More information on this feature is available in :ref:`advdatamapping_relation`.
Querying with Joins
====================
.. autoclass:: collection
+.. autoclass:: sqlalchemy.orm.collections.MappedCollection
+ :members:
+
.. autofunction:: collection_adapter
.. autofunction:: column_mapped_collection
You typically invoke ``Session()`` when you first need to talk to your database, and want to save some objects or load some existing ones. Then, you work with it, save your changes, and then dispose of it....or at the very least ``close()`` it. It's not a "global" kind of object, and should be handled more like a "local variable", as it's generally **not** safe to use with concurrent threads. Sessions are very inexpensive to make, and don't use any resources whatsoever until they are first used...so create some !
- There is also a pattern whereby you're using a **contextual session**, this is described later in `unitofwork_contextual`. In this pattern, a helper object is maintaining a ``Session`` for you, most commonly one that is local to the current thread (and sometimes also local to an application instance). SQLAlchemy has worked this pattern out such that it still *looks* like you're creating a new session as you need one...so in that case, it's still a guaranteed win to just say ``Session()`` whenever you want a session.
+ There is also a pattern whereby you're using a **contextual session**, this is described later in :ref:`unitofwork_contextual`. In this pattern, a helper object is maintaining a ``Session`` for you, most commonly one that is local to the current thread (and sometimes also local to an application instance). SQLAlchemy has worked this pattern out such that it still *looks* like you're creating a new session as you need one...so in that case, it's still a guaranteed win to just say ``Session()`` whenever you want a session.
* Is the Session a cache ?
session.add_all([item1, item2, item3])
-The ``add()`` operation **cascades** along the ``save-update`` cascade. For more details see the section `unitofwork_cascades`.
+The ``add()`` operation **cascades** along the ``save-update`` cascade. For more details see the section :ref:`unitofwork_cascades`.
Merging
-------
Note that objects within the session are by default *weakly referenced*. This means that when they are dereferenced in the outside application, they fall out of scope from within the ``Session`` as well and are subject to garbage collection by the Python interpreter. The exceptions to this include objects which are pending, objects which are marked as deleted, or persistent objects which have pending changes on them. After a full flush, these collections are all empty, and all objects are again weakly referenced. To disable the weak referencing behavior and force all objects within the session to remain until explicitly expunged, configure ``sessionmaker()`` with the ``weak_identity_map=False`` setting.
+.. _unitofwork_cascades:
+
Cascades
========
The default value for ``cascade`` on :func:`~sqlalchemy.orm.relation()` is ``save-update, merge``.
+.. _unitofwork_transaction:
+
Managing Transactions
=====================
engine.commit() # commit the transaction
+.. _unitofwork_contextual:
+
Contextual/Thread-local Sessions
=================================
>>> metadata.bind = None
-Detailed examples of connectionless and implicit execution are available in the "Engines" chapter: `dbengine_implicit`.
+Detailed examples of connectionless and implicit execution are available in the "Engines" chapter: :ref:`dbengine_implicit`.
Selecting
==========
Deletes rows matched by this query from the database.
:param synchronize_session: chooses the strategy for the removal of
- matched objects from the session. Valid values are:
-
- False
- don't synchronize the session. This option is the most efficient
- and is reliable once the session is expired, which typically
- occurs after a commit(), or explicitly using expire_all().
- Before the expiration, objects may still remain in the session
- which were in fact deleted which can lead to confusing results
- if they are accessed via get() or already loaded collections.
-
- 'fetch'
- performs a select query before the delete to find objects that
- are matched by the delete query and need to be removed from the
- session. Matched objects are removed from the session.
-
- 'evaluate'
- experimental feature. Tries to evaluate the querys criteria in
- Python straight on the objects in the session. If evaluation of
- the criteria isn't implemented, the 'fetch' strategy will be
- used as a fallback.
-
- The expression evaluator currently doesn't account for
- differing string collations between the database and Python.
+ matched objects from the session. Valid values are:
+
+ False - don't synchronize the session. This option is the most
+ efficient and is reliable once the session is expired, which
+ typically occurs after a commit(), or explicitly using
+ expire_all(). Before the expiration, objects may still remain in
+ the session which were in fact deleted which can lead to confusing
+ results if they are accessed via get() or already loaded
+ collections.
+
+ 'fetch' - performs a select query before the delete to find
+ objects that are matched by the delete query and need to be
+ removed from the session. Matched objects are removed from the
+ session.
+
+ 'evaluate' - Evaluate the query's criteria in Python straight on
+ the objects in the session. If evaluation of the criteria isn't
+ implemented, the 'fetch' strategy will be used as a fallback.
+
+ The expression evaluator currently doesn't account for differing
+ string collations between the database and Python.
Returns the number of rows deleted, excluding any cascades.
Updates rows matched by this query in the database.
- :param values: a dictionary with attributes names as keys and literal values or sql expressions
- as values.
+ :param values: a dictionary with attributes names as keys and literal
+ values or sql expressions as values.
:param synchronize_session: chooses the strategy to update the
attributes on objects in the session. Valid values are:
- False
- don't synchronize the session. This option is the most efficient and is reliable
- once the session is expired, which typically occurs after a commit(), or explicitly
- using expire_all(). Before the expiration, updated objects may still remain in the session
- with stale values on their attributes, which can lead to confusing results.
+ False - don't synchronize the session. This option is the most
+ efficient and is reliable once the session is expired, which
+ typically occurs after a commit(), or explicitly using
+ expire_all(). Before the expiration, updated objects may still
+ remain in the session with stale values on their attributes, which
+ can lead to confusing results.
- 'fetch'
- performs a select query before the update to find objects that are matched
- by the update query. The updated attributes are expired on matched objects.
+ 'fetch' - performs a select query before the update to find
+ objects that are matched by the update query. The updated
+ attributes are expired on matched objects.
- 'evaluate'
- Tries to evaluate the Query's criteria in Python
- straight on the objects in the session. If evaluation of the criteria isn't
- implemented, an exception is raised.
+ 'evaluate' - Evaluate the Query's criteria in Python straight on
+ the objects in the session. If evaluation of the criteria isn't
+ implemented, an exception is raised.
- The expression evaluator currently doesn't account for differing string
- collations between the database and Python.
+ The expression evaluator currently doesn't account for differing
+ string collations between the database and Python.
Returns the number of rows matched by the update.
This should be the base of new types. Note that
for most cases, :class:`TypeDecorator` is probably
- more appropriate.
+ more appropriate::
import sqlalchemy.types as types
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
