Cosmetic changes to the ATTACH DATABASE code

6 files changed, 30 insertions, 22 deletions

diff --git a/odb/sqlite/connection-factory.cxx b/odb/sqlite/connection-factory.cxx
index 0bbf617..794c6dd 100644
--- a/odb/sqlite/connection-factory.cxx
+++ b/odb/sqlite/connection-factory.cxx
@@ -317,7 +317,7 @@ namespace odb
         // While it may seem like a good idea to also invalidate query results
         // and reset active statements, if any such result/statement is still
         // alive, then there would be bigger problems since it would have a
-        // dangling reference to the connection. In a way, this's the same
+        // dangling reference to the connection. In a way, that's the same
         // reason we don't do it in the connection destructor.
 
         // Remove ourselves from the active object list of the main
diff --git a/odb/sqlite/connection-factory.hxx b/odb/sqlite/connection-factory.hxx
index 0d01b85..b410997 100644
--- a/odb/sqlite/connection-factory.hxx
+++ b/odb/sqlite/connection-factory.hxx
@@ -250,14 +250,14 @@ namespace odb
       virtual connection_ptr
       connect ();
 
+      virtual void
+      detach ();
+
       // Active object interface.
       //
       virtual void
       clear ();
 
-      virtual void
-      detach ();
-
       virtual
       ~default_attached_connection_factory ();
 
diff --git a/odb/sqlite/connection.hxx b/odb/sqlite/connection.hxx
index f8df9d0..366239f 100644
--- a/odb/sqlite/connection.hxx
+++ b/odb/sqlite/connection.hxx
@@ -78,9 +78,9 @@ namespace odb
       typedef sqlite::statement_cache statement_cache_type;
       typedef sqlite::database database_type;
 
-      // Translate the database schema in statement text (used to implement
-      // attached databases). If the result is empty, then no translation is
-      // required and the original text should be used as is.
+      // Translate the database schema in the statement text (used to
+      // implement attached databases). If the result is empty, then no
+      // translation is required and the original text should be used as is.
       //
       typedef void (statement_translator) (std::string& result,
                                            const char* text,
@@ -341,7 +341,7 @@ namespace odb
         return main_connection_->factory ();
       }
 
-      // Note that this essentially establishes a "protocol" for all the
+      // Note that this essentially establishes a "framework" for all the
       // attached connection factory implementations: they hold a counted
       // reference to the main connection and they maintain a single shared
       // attached connection.
diff --git a/odb/sqlite/database.hxx b/odb/sqlite/database.hxx
index 478fbdb..614ed63 100644
--- a/odb/sqlite/database.hxx
+++ b/odb/sqlite/database.hxx
@@ -85,8 +85,8 @@ namespace odb
 
       // Attach to the specified connection a database with the specified name
       // as the specified schema. Good understanding of SQLite ATTACH/DETACH
-      // DATABASE semantics and ODB connection management is recommended when
-      // using this mechanism.
+      // DATABASE statements semantics and ODB connection management is
+      // strongly recommended when using this mechanism.
       //
       // The resulting database instance is referred to as an "attached
       // database" and the connection it returns as an "attached connection"
@@ -97,6 +97,14 @@ namespace odb
       // pre-attached "main" and "temp" schemas (in this case name can be
       // anything).
       //
+      // The automatic translation of the statements relies on their text
+      // having references to top-level database entities (tables, indexes,
+      // etc) qualified with the "main" schema. To achieve this, compile your
+      // headers with `--schema main` and, if using schema migration, with
+      // `--schema-version-table main.schema_version`. You must also not use
+      // "main" as an object/table alias in views of native statements. For
+      // optimal translation performance use 4-character schema names.
+      //
       // The main connection and attached to it databases and connections are
       // all meant to be used withing the same thread. In particular, the
       // attached database holds a counted reference to the main connection
@@ -107,25 +115,21 @@ namespace odb
       // main connection, not to the (main) database, which mimics the
       // underlying semantics of SQLite. An alternative model would have been
       // to notionally attach the databases to the main database and under the
-      // hood automatically attach them to each returned connecton. While this
-      // may seem like a more convenient model in some cases, it is also less
-      // flexible: the current model allows attaching a different set of
+      // hood automatically attach them to each returned connection. While
+      // this may seem like a more convenient model in some cases, it is also
+      // less flexible: the current model allows attaching a different set of
       // databases to different connections, attaching them on demand as the
       // transaction progresses, etc. Also, the more convenient model can be
-      // implemented on top this model by deriving an aplication-specific
+      // implemented on top this model by deriving an application-specific
       // database class and/or providing custom connection factories.
       //
-      // Note also that unless the name is a URI with appropriate mode, it is
+      // Note that unless the name is a URI with appropriate mode, it is
       // opened with the SQLITE_OPEN_READWRITE|SQLITE_OPEN_CREATE flags. So if
       // you want just SQLITE_OPEN_READWRITE, then you will need to verify its
       // existence manually prior to calling this constructor.
       //
-      // The automatic translation of the statements relies on all the
-      // statements text having references to top-level database entities
-      // (tables, indexes, etc) qualified with the "main" schema. To achieve
-      // this, compile your headers with `--schema main` and, if using schema
-      // migration, with `--schema-version-table main.schema_version`. You
-      // must also not use "main" as a table alias.
+      // Note that attaching/detaching databases withing a transaction is only
+      // supported since SQLite 3.21.0.
       //
       database (const connection_ptr&,
                 const std::string& name,
diff --git a/odb/sqlite/stream.hxx b/odb/sqlite/stream.hxx
index c2d45c0..6ee76cb 100644
--- a/odb/sqlite/stream.hxx
+++ b/odb/sqlite/stream.hxx
@@ -23,6 +23,10 @@ namespace odb
     class LIBODB_SQLITE_EXPORT stream: public active_object
     {
     public:
+      // @@ TODO: db is actually what we now (and SQLite in other places)
+      //    call schema (see database::schema(), ATTACH DATABASE). So we
+      //    should probably rename this at some point for consistency.
+      //
       stream (const char* db,
               const char* table,
               const char* column,
diff --git a/odb/sqlite/transaction-impl.cxx b/odb/sqlite/transaction-impl.cxx
index 106270d..6485f7e 100644
--- a/odb/sqlite/transaction-impl.cxx
+++ b/odb/sqlite/transaction-impl.cxx
@@ -155,7 +155,7 @@ namespace odb
         : *static_cast<attached_connection_factory&> (*db.factory_).attached_connection_;
     }
 
-    // Store transaction tracer in the main database.
+    // Store transaction tracer in the main connection.
     //
     void transaction_impl::
     tracer (odb::tracer* t)