Merge pull request #3378 from jim-parry/userguide/database_utilities

User Guide update - Database Utilities

1 files changed, 109 insertions, 25 deletions

diff --git a/user_guide_src/source/database/utilities.rst b/user_guide_src/source/database/utilities.rst
index bd40cdadd..da53cba38 100644
--- a/user_guide_src/source/database/utilities.rst
+++ b/user_guide_src/source/database/utilities.rst
@@ -5,15 +5,14 @@ Database Utility Class
 The Database Utility Class contains methods that help you manage your
 database.
 
-.. contents:: Table of Contents
+.. contents::
+    :local:
+    :depth: 2
 
 
-******************
-Function Reference
-******************
-
+******************************
 Initializing the Utility Class
-==============================
+******************************
 
 .. important:: In order to initialize the Utility class, your database
 	driver must already be running, since the utilities class relies on it.
@@ -39,7 +38,11 @@ object::
 
 	$this->dbutil->some_method()
 
-$this->dbutil->list_databases();
+****************************
+Using the Database Utilities
+****************************
+
+Retrieve list of database names
 ================================
 
 Returns an array of database names::
@@ -51,8 +54,9 @@ Returns an array of database names::
  		echo $db;
 	}
 
-$this->dbutil->database_exists();
-=================================
+
+Determine If a Database Exists
+==============================
 
 Sometimes it's helpful to know whether a particular database exists.
 Returns a boolean TRUE/FALSE. Usage example::
@@ -65,8 +69,8 @@ Returns a boolean TRUE/FALSE. Usage example::
 .. note:: Replace *database_name* with the name of the table you are
 	looking for. This method is case sensitive.
 
-$this->dbutil->optimize_table('table_name');
-============================================
+Optimize a Table
+================
 
 Permits you to optimize a table using the table name specified in the
 first parameter. Returns TRUE/FALSE based on success or failure::
@@ -79,8 +83,8 @@ first parameter. Returns TRUE/FALSE based on success or failure::
 .. note:: Not all database platforms support table optimization. It is
 	mostly for use with MySQL.
 
-$this->dbutil->repair_table('table_name');
-==========================================
+Repair a Table
+==============
 
 Permits you to repair a table using the table name specified in the
 first parameter. Returns TRUE/FALSE based on success or failure::
@@ -92,8 +96,8 @@ first parameter. Returns TRUE/FALSE based on success or failure::
 
 .. note:: Not all database platforms support table repairs.
 
-$this->dbutil->optimize_database();
-====================================
+Optimize a Database
+===================
 
 Permits you to optimize the database your DB class is currently
 connected to. Returns an array containing the DB status messages or
@@ -111,8 +115,8 @@ FALSE on failure.
 .. note:: Not all database platforms support table optimization. It
 	it is mostly for use with MySQL.
 
-$this->dbutil->csv_from_result($db_result);
-===========================================
+Export a Query Result as a CSV File
+===================================
 
 Permits you to generate a CSV file from a query result. The first
 parameter of the method must contain the result object from your
@@ -139,8 +143,8 @@ is used as the enclosure. Example::
 	simply creates the CSV layout. If you need to write the file
 	use the :doc:`File Helper <../helpers/file_helper>`.
 
-$this->dbutil->xml_from_result($db_result);
-===========================================
+Export a Query Result as an XML Document
+========================================
 
 Permits you to generate an XML file from a query result. The first
 parameter expects a query result object, the second may contain an
@@ -163,8 +167,12 @@ optional array of config parameters. Example::
 	simply creates the XML layout. If you need to write the file
 	use the :doc:`File Helper <../helpers/file_helper>`.
 
-$this->dbutil->backup();
-========================
+********************
+Backup Your Database
+********************
+
+Database Backup Notes
+=====================
 
 Permits you to backup your full database or individual tables. The
 backup data can be compressed in either Zip or Gzip format.
@@ -182,7 +190,7 @@ backup data can be compressed in either Zip or Gzip format.
 	have root privileges.
 
 Usage Example
--------------
+=============
 
 ::
 
@@ -201,7 +209,7 @@ Usage Example
 	force_download('mybackup.gz', $backup);
 
 Setting Backup Preferences
---------------------------
+==========================
 
 Backup preferences are set by submitting an array of values to the first
 parameter of the ``backup()`` method. Example::
@@ -219,7 +227,7 @@ parameter of the ``backup()`` method. Example::
 	$this->dbutil->backup($prefs);
 
 Description of Backup Preferences
----------------------------------
+=================================
 
 ======================= ======================= ======================= ========================================================================
 Preference              Default Value           Options                 Description
@@ -234,4 +242,80 @@ Preference              Default Value           Options                 Descript
 **add_insert**           TRUE                    TRUE/FALSE              Whether to include INSERT statements in your SQL export file.
 **newline**              "\\n"                   "\\n", "\\r", "\\r\\n"  Type of newline to use in your SQL export file.
 **foreign_key_checks**   TRUE                    TRUE/FALSE              Whether output should keep foreign key checks enabled.
-======================= ======================= ======================= ========================================================================
\ No newline at end of file
+======================= ======================= ======================= ========================================================================
+
+***************
+Class Reference
+***************
+
+.. class:: DB_utility
+
+	.. method:: backup($params)
+
+		:param	array	$params: associative array of backup preferences
+		:returns:	void
+                :rtype:         void
+
+		Perform a database backup, per user preferences
+
+        .. method:: csv_from_results($query, $delim = ',', $newline = "\n", $enclosure = '"')
+
+                :param  object  $query:   DB_result with data to backup
+                :param  string  $delim:  Delimniter character for the CSV file, default is ','
+                :param  string  $newline:    Character to use for newlines, default is "\n"
+                :param  string  $enclosure:  Delimiter used for enclosure, default is '"'
+                :returns:   The generated CSV file as a string
+                :rtype:     string
+
+	.. method:: database_exists($database_name)
+
+		:param	string	$database_name: name of the database to check for
+		:returns:	TRUE if the database exists, FALSE otherwise
+                :rtype:         boolean
+
+		Perform a database backup, per user preferences
+
+	.. method:: database_exists($database_name)
+
+		:param	string	$database_name: name of the database to check for
+		:returns:	TRUE if the database exists, FALSE otherwise
+                :rtype:         boolean
+
+		Check for the existence of a database
+
+	.. method:: list_databases()
+
+		:returns:	Array of database names found
+                :rtype:         array
+
+		Retrieve all the database names
+
+	.. method:: optimize_database()
+
+		:returns:	Array of optimization messages, FALSE on failure
+                :rtype:         array
+
+		Optimizes a database
+
+	.. method:: optimize_table($table_name)
+
+                :param  string  $table_name:    Name of the table to optimize
+		:returns:	Array of optimization messages, FALSE on failure
+                :rtype:         array
+
+		Optimizes a database table
+
+	.. method:: repair_table($table_name)
+
+                :param  string  $table_name:    Name of the table to repair
+		:returns:	Array of repair messages, FALSE on failure
+                :rtype:         array
+
+		Repairs a database table
+
+        .. method:: xml_from_results($query, $params)
+
+                :param  object  $query:   DB_result with data to backup
+                :param  array  $params:  Associative array of preferences
+                :returns:   The generated XML document as a string
+                :rtype:         string