=====
Ovens
=====

Ovens are used to bake (execute) the queries generated by recipes. A standard
oven is included in a recipe library, which provides connectivity to any
database supported by SQLAlchemy. Remember, you'll need to have the required
database driver installed. You can learn more in the SQLAlchemy
`documentation <http://docs.sqlalchemy.org/en/latest/core/engines.html#database-urls>`_.

Initializing an Oven
====================

To initialize an oven, you pass it the connection string for your database to
the get_oven() function. You'll get back an oven that has a ready to use
engine and session. For example, to connect to an in-memory sqlite database
and use with a recipe.

.. code-block:: python

    from recipe import get_oven

    oven = get_oven('sqlite://')
    recipe = Recipe(session=oven.Session())

If you need to access the SQLAlchemy engine for any reason, it is available
via the `engine` attribute.

Oven Drivers
============

Developers can also build custom oven drivers that provide advanced features.
One example of that is the recipe_caching oven. You can pip install the
recipe_caching python package, and you'll have access to an oven that caches
the results of every query. If you want to use a custom oven driver, you pass
the drivers name to the name keyword argument as shown here:

.. code-block:: python

    from recipe import get_oven

    oven = get_oven('sqlite://', name='caching')

.. note::  Other ovens may require additional configuration or settings. So
           make sure to review their documentation.


You can learn more about creating your own drivers in the :ref:`custom_ovens`
section.