From ee477c656fae90604fd2fca6e56e57402c1464f4 Mon Sep 17 00:00:00 2001 From: James L Parry Date: Tue, 25 Nov 2014 16:15:18 -0800 Subject: User Guide update - Datbase Utilities 1) Updated TOC structure of the DB Utilities writeup 2) Added a class reference at the end, ordered by method name Signed-off-by:James L Parry --- user_guide_src/source/database/utilities.rst | 121 +++++++++++++++++++++------ 1 file changed, 97 insertions(+), 24 deletions(-) diff --git a/user_guide_src/source/database/utilities.rst b/user_guide_src/source/database/utilities.rst index bd40cdadd..f1f5e4a01 100644 --- a/user_guide_src/source/database/utilities.rst +++ b/user_guide_src/source/database/utilities.rst @@ -8,12 +8,9 @@ database. .. contents:: Table of Contents -****************** -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 +36,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 +52,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 +67,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 +81,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 +94,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 +113,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 +141,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 +165,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 +188,7 @@ backup data can be compressed in either Zip or Gzip format. have root privileges. Usage Example -------------- +============= :: @@ -201,7 +207,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 +225,7 @@ parameter of the ``backup()`` method. Example:: $this->dbutil->backup($prefs); Description of Backup Preferences ---------------------------------- +================================= ======================= ======================= ======================= ======================================================================== Preference Default Value Options Description @@ -234,4 +240,71 @@ 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 + :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 + + .. method:: database_exists($database_name) + + :param string $database_name: name of the database to check for + :returns: TRUE if the database exists, FALSE otherwise + + 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 + + Check for the existence of a database + + .. method:: list_databases() + + :returns: Array of database names found + + Retrieve all the database names + + .. method:: optimize_database() + + :returns: Array of optimization messages, FALSE on failure + + 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 + + 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 + + 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 \ No newline at end of file -- cgit v1.2.3-24-g4f1b From 50d06496fbcead11c85b19daf50afe0ff4a3d756 Mon Sep 17 00:00:00 2001 From: James L Parry Date: Tue, 25 Nov 2014 16:21:39 -0800 Subject: User Guide update - Datbase Utilities 1) Updated TOC structure of the DB Utilities writeup 2) Added a class reference at the end, ordered by method name Signed-off-by:James L Parry --- user_guide_src/source/database/utilities.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/user_guide_src/source/database/utilities.rst b/user_guide_src/source/database/utilities.rst index f1f5e4a01..a9bfbddfb 100644 --- a/user_guide_src/source/database/utilities.rst +++ b/user_guide_src/source/database/utilities.rst @@ -5,7 +5,9 @@ Database Utility Class The Database Utility Class contains methods that help you manage your database. -.. contents:: Table of Contents +.. contents:: + :local: + :depth: 2 ****************************** -- cgit v1.2.3-24-g4f1b From d2485a3c8f62a6963cf5c49195e490ac67135b5d Mon Sep 17 00:00:00 2001 From: James L Parry Date: Wed, 26 Nov 2014 08:52:50 -0800 Subject: User Guide update - Datbase Utilities Fixed the return types Signed-off-by:James L Parry --- user_guide_src/source/database/utilities.rst | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/user_guide_src/source/database/utilities.rst b/user_guide_src/source/database/utilities.rst index a9bfbddfb..da53cba38 100644 --- a/user_guide_src/source/database/utilities.rst +++ b/user_guide_src/source/database/utilities.rst @@ -253,7 +253,8 @@ Class Reference .. method:: backup($params) :param array $params: associative array of backup preferences - :rtype: void + :returns: void + :rtype: void Perform a database backup, per user preferences @@ -264,11 +265,13 @@ Class Reference :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 @@ -276,18 +279,21 @@ Class Reference :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 @@ -295,6 +301,7 @@ Class Reference :param string $table_name: Name of the table to optimize :returns: Array of optimization messages, FALSE on failure + :rtype: array Optimizes a database table @@ -302,6 +309,7 @@ Class Reference :param string $table_name: Name of the table to repair :returns: Array of repair messages, FALSE on failure + :rtype: array Repairs a database table @@ -309,4 +317,5 @@ Class Reference :param object $query: DB_result with data to backup :param array $params: Associative array of preferences - :returns: The generated XML document as a string \ No newline at end of file + :returns: The generated XML document as a string + :rtype: string -- cgit v1.2.3-24-g4f1b