Improve failure mode handling in enginefacade

Check explicitly for the cases where no "sql_connection"
attribute was set when running _start(), so that the
lack of this parameter is documented by the
exception rather than failing into create_engine()
with an unclear failure mode.
If _start() fails as it will here, make sure _started
stays False so that repeated calls to _start() continue
to raise the same exception, rather than raising
attribute errors.  When accessing the "session" or
"connection" attributes of the context when these
attributes were not requested by the decorator or
context manager, raise explicit exceptions
for each, rather than returning None which leads to
hard-to-debug NoneType errors.

Change-Id: Iadfbf4707daed4140285a3a472009f6863b18275
Closes-bug: 1477080

1 files changed, 6 insertions, 0 deletions

diff --git a/doc/source/usage.rst b/doc/source/usage.rst
index 11c8c2a..cc4f2fd 100644
--- a/doc/source/usage.rst
+++ b/doc/source/usage.rst
@@ -76,6 +76,12 @@ positional argument:
         results = some_reader_api_function(context)
         some_writer_api_function(context, 5, 10)
 
+.. 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
+   raised otherwise.
+
+
 The scope of transaction and connectivity for both approaches is managed
 transparently.   The configuration for the connection comes from the standard
 :obj:`oslo_config.cfg.CONF` collection.  Additional configurations can be