docs: mention that it's possible to use Connection directly

Sometimes people just do not need the ORM part and a Session at all.
Mention the fact, that it's possible to ask for a Connection in
enginefacade.

Change-Id: I7a135be7149cd3fa140e0268fea5a17f23f402b2

1 files changed, 15 insertions, 0 deletions

diff --git a/doc/source/usage.rst b/doc/source/usage.rst
index 448afaa..1b2d996 100644
--- a/doc/source/usage.rst
+++ b/doc/source/usage.rst
@@ -75,6 +75,21 @@ decorator.   Each function must receive the context argument:
         results = some_reader_api_function(context)
         some_writer_api_function(context, 5, 10)
 
+
+``connection`` modifier can be used when a :class:`.Session` object is not
+needed, e.g. when `SQLAlchemy Core <http://docs.sqlalchemy.org/en/latest/core/>`_
+is preferred:
+
+.. code:: python
+
+    @enginefacade.reader.connection
+    def _refresh_from_db(context, cache):
+        sel = sa.select([table.c.id, table.c.name])
+        res = context.connection.execute(sel).fetchall()
+        cache.id_cache = {r[1]: r[0] for r in res}
+        cache.str_cache = {r[0]: r[1] for r in res}
+
+
 .. note::  The ``context.session`` and ``context.connection`` attributes
    must be accessed within the scope of an appropriate writer/reader block
    (either the decorator or contextmanager approach). An AttributeError is