summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJames L Parry <jim_parry@bcit.ca>2014-11-26 01:15:18 +0100
committerJames L Parry <jim_parry@bcit.ca>2014-11-26 01:15:18 +0100
commitee477c656fae90604fd2fca6e56e57402c1464f4 (patch)
treec9dbd6d5cdacfa0c9e061fe7d6012140cff90716
parent20862e72592a3afae3c313ed207f9e2e24870e17 (diff)
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 <jim_parry@bcit.ca>
-rw-r--r--user_guide_src/source/database/utilities.rst121
1 files 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