Merge pull request #3378 from jim-parry/userguide/database_utilities
User Guide update - Database Utilities
diff --git a/user_guide_src/source/database/utilities.rst b/user_guide_src/source/database/utilities.rst
index bd40cda..da53cba 100644
--- a/user_guide_src/source/database/utilities.rst
+++ b/user_guide_src/source/database/utilities.rst
@@ -5,15 +5,14 @@
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 @@
$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 @@
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 @@
.. 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 @@
.. 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 @@
.. 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 @@
.. 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 @@
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 @@
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 @@
have root privileges.
Usage Example
--------------
+=============
::
@@ -201,7 +209,7 @@
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 @@
$this->dbutil->backup($prefs);
Description of Backup Preferences
----------------------------------
+=================================
======================= ======================= ======================= ========================================================================
Preference Default Value Options Description
@@ -234,4 +242,80 @@
**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