summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorAndrey Andreev <narf@devilix.net>2014-12-03 11:01:16 +0100
committerAndrey Andreev <narf@devilix.net>2014-12-03 11:01:16 +0100
commitf29c21e186a36351338297ae62eabb9ab8c4ec45 (patch)
tree477b8b8549816905715e096b14f3a50da4cf161e
parentdf5299fd41c03ce2ad2e302e265aace36751bd31 (diff)
parent7eb492b77a30498c9d563032866fd0aaf494e44c (diff)
Merge pull request #3378 from jim-parry/userguide/database_utilities
User Guide update - Database Utilities
-rw-r--r--user_guide_src/source/database/utilities.rst134
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