1 files changed, 62 insertions, 17 deletions

diff --git a/sql/sql_class.h b/sql/sql_class.h
index 7117c08a7e1..7875870bd1a 100644
--- a/sql/sql_class.h
+++ b/sql/sql_class.h
@@ -593,6 +593,22 @@ public:
   uint32 query_length;                          // current query length
   Server_side_cursor *cursor;
 
+  /**
+    Name of the current (default) database.
+
+    If there is the current (default) database, "db" contains its name. If
+    there is no current (default) database, "db" is NULL and "db_length" is
+    0. In other words, "db", "db_length" must either be NULL, or contain a
+    valid database name.
+
+    @note this attribute is set and alloced by the slave SQL thread (for
+    the THD of that thread); that thread is (and must remain, for now) the
+    only responsible for freeing this member.
+  */
+
+  char *db;
+  uint db_length;
+
 public:
 
   /* This constructor is called for backup statements */
@@ -1024,18 +1040,21 @@ public:
   */
   char	  *thread_stack;
 
+  /**
+    Currently selected catalog.
+  */
+  char *catalog;
+
   /*
-    db - currently selected database
-    catalog - currently selected catalog
-    WARNING: some members of THD (currently 'db', 'catalog' and 'query')  are
-    set and alloced by the slave SQL thread (for the THD of that thread); that
-    thread is (and must remain, for now) the only responsible for freeing these
-    3 members. If you add members here, and you add code to set them in
-    replication, don't forget to free_them_and_set_them_to_0 in replication
-    properly. For details see the 'err:' label of the handle_slave_sql()
-    in sql/slave.cc.
-   */
-  char   *db, *catalog;
+    WARNING: some members of THD (currently 'Statement::db',
+    'catalog' and 'query')  are set and alloced by the slave SQL thread
+    (for the THD of that thread); that thread is (and must remain, for now)
+    the only responsible for freeing these 3 members. If you add members
+    here, and you add code to set them in replication, don't forget to
+    free_them_and_set_them_to_0 in replication properly. For details see
+    the 'err:' label of the handle_slave_sql() in sql/slave.cc.
+  */
+
   Security_context main_security_ctx;
   Security_context *security_ctx;
 
@@ -1390,7 +1409,6 @@ public:
   uint	     tmp_table, global_read_lock;
   uint	     server_status,open_options;
   enum enum_thread_type system_thread;
-  uint       db_length;
   uint       select_number;             //number of select (used for EXPLAIN)
   /* variables.transaction_isolation is reset to this after each commit */
   enum_tx_isolation session_tx_isolation;
@@ -1802,11 +1820,26 @@ public:
     }
   }
 
-  /*
-    Initialize the current database from a NULL-terminated string with length
-    If we run out of memory, we free the current database and return TRUE.
-    This way the user will notice the error as there will be no current
-    database selected (in addition to the error message set by malloc).
+  /**
+    Set the current database; use deep copy of C-string.
+
+    @param new_db     a pointer to the new database name.
+    @param new_db_len length of the new database name.
+
+    Initialize the current database from a NULL-terminated string with
+    length. If we run out of memory, we free the current database and
+    return TRUE.  This way the user will notice the error as there will be
+    no current database selected (in addition to the error message set by
+    malloc).
+
+    @note This operation just sets {db, db_length}. Switching the current
+    database usually involves other actions, like switching other database
+    attributes including security context. In the future, this operation
+    will be made private and more convenient interface will be provided.
+
+    @return Operation status
+      @retval FALSE Success
+      @retval TRUE  Out-of-memory error
   */
   bool set_db(const char *new_db, size_t new_db_len)
   {
@@ -1821,6 +1854,18 @@ public:
     db_length= db ? new_db_len : 0;
     return new_db && !db;
   }
+
+  /**
+    Set the current database; use shallow copy of C-string.
+
+    @param new_db     a pointer to the new database name.
+    @param new_db_len length of the new database name.
+
+    @note This operation just sets {db, db_length}. Switching the current
+    database usually involves other actions, like switching other database
+    attributes including security context. In the future, this operation
+    will be made private and more convenient interface will be provided.
+  */
   void reset_db(char *new_db, size_t new_db_len)
   {
     db= new_db;